[
http://jira.codehaus.org/browse/DOXIA-236?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=133159#action_133159
]
Lukas Theussl commented on DOXIA-236:
-------------------------------------
bq. Anchor events are part of the Sink API, so a parser has to my understanding
always the right to push this event into a sink
Not if there is no anchor in the parsed source document. Just because anchors
are valid sink events doesn't mean a parser can emit one wherever it deems
convenient.
bq. regardless whether the event is driven by explicit user input or by
implicit convention.
I disagree on the latter. A doxia parser is a translator, not an interpreter,
if you want anchors for your section titles, provide them explicitly.
bq. I still don't understand why sinks are allowed to output implicit anchors
Because there is no hard reason why they shouldn't. While there is such a
reason to forbid it for parsers (because they don't know the output format), I
don't see why it should in principle be forbidden for sinks. My personal
opinion is that implicit anchors should never be generated neither by parser
nor sink, and I think I made that clear in the javadocs, but after all,
automatically generated anchors are still a useful and widely used feature for
one single output format (html).
bq. If we consider such anchors as problematic, nobody should be allowed to
create them
The problem is not the existence of the implicit anchor, but its translation
into different output formats. 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. Of course you will be in
trouble the day you want to create a pdf from your docs. You will either have
to adjust your input documents, or use an adapted pdf sink as well. So you
could have adapted your input docs in the first place...
bq. it would be cool to have this doc online
The docs are for doxia-beta-1 which is not released yet, so we can't publish
them.
> 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
