[
http://jira.codehaus.org/browse/DOXIA-236?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=133167#action_133167
]
Benjamin Bentmann commented on DOXIA-236:
-----------------------------------------
bq. Just because anchors are valid sink events doesn't mean a parser can emit
one wherever it deems convenient.
Yes of course, a parser should not emit events at random. What I did not
clearly express is my understanding that a parser adopts a certain input format
for usage with Doxia, just like a sink realizes some output format. Now if the
format (which is in general external and unrelated to Doxia) specifies that a
single syntactical construct like a section title is to be interpreted as a
title with an implicit anchor, a parser which wants to feed this format into
Doxia now simply can't follow the format specification because sending the
anchor event is prohibited, i.e. informataion from the input document is lost.
That's the only thing that puzzled me a little, wondering if it's really
necessary/desired. I'm fine if Doxia says "you ugly input format, don't use
implicit anchors", it's just some kind of pushing best practices, I can fairly
well understand that ;-)
bq. I don't see why it should in principle be forbidden for sinks.
Alright, as long as the implicit anchors generated by such a sink do not
interfere with the explicit anchors defined by the user (e.g. name clash).
bq. If you are only interested in a html web site for your project, I see no
reason why you shouldn't be allowed to write a sink that automatically
generates those anchors for you.
If you are only interested in -a html web site-_APT sources_ for your project,
I see no reason why you shouldn't be allowed to write a -sink-_parser_ that
automatically generates those anchors for you.
Just for the fun of the words, it wasn't meant seriously ;-)
bq. so we can't publish them.
I see, at least I know where to look for them.
To come to an end, I might not fully understand all your arguments but that's
mostly because I'm not familiar enough with Doxia's architecture. If I look
back to where this issue started, I can only repeat you did a good job and feel
this issue is ready for being closed, thanks Lukas!
> Clarify Sink API
> ----------------
>
> Key: DOXIA-236
> URL: http://jira.codehaus.org/browse/DOXIA-236
> Project: Maven Doxia
> Issue Type: Task
> Components: Sink API
> Affects Versions: 1.0-alpha-2
> Reporter: Benjamin Bentmann
>
> If the idea with extensibility and interchangeable input/output formats
> should be more than a nice dream, the Sink API needs a thorough specification
> (e.g. by means of more javadoc at {{Sink}}) because that's were everything
> meets. It should define
> # what rules parsers must obey when generating events and
> # what events a sink needs to be prepared to handle
> Currently, all of this is left to assumptions. Some example issues that need
> to be clarified:
> - What characters may constitute an anchor reported by {{anchor()}}?
> Arbitrary, ASCII-only, ...?
> - What format applies to the {{name}} parameter of {{link()}}? How are
> internal and external links to be distinguished (DOXIA-208)?
> - What character chunks are reported by {{text()}}? Longest consecutive
> sequence, line-by-line, arbitrary, ... (DOXIA-222)?
> - What exactly is a figure's source as reported by {{figureGraphics()}}?
> Relative/absolute path, relative to which directory? What about file
> extensions (DOXIA-99)?
> - What order of events is "reasonable" (DOXIA-132)? May parsers report table
> body and caption in a specific or arbitrary order? Must the document head
> always be reported before body or may it be postponed?
> - Is closing a sink twice acceptable or an error?
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
