[
http://jira.codehaus.org/browse/DOXIA-236?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=133153#action_133153
]
Benjamin Bentmann commented on DOXIA-236:
-----------------------------------------
bq. Thanks for the graphic illustration
Sometimes I just can't resist my brain dumps, sorry ;-)
bq. a parser doesn't know yet where it's output will go,
Yep, exactly my motivation for this issue: Since a parser can't and shouldn't
know the various sinks, he must at least know the contract of their common
interface that *every* sink obeys. If you can't setup such a common denominator
among the sinks, it's all lost with interchangable output formats.
bq. some feature that might be acceptable for one Sink may lead to errors in
others
Of course the output formats created by sinks will have different
requirements/restrictions, but every sink should
a) either fully support an event that is defined as part of the Sink API
b) or at least gracefully ignore an event it can't handle
such that users get a (best-effort) output regardless of the selected sink. It
is the responsibility of the sink implementor to shield parsers from the
details of its realized output format. IMHO, a sink should never ever fail with
an exception if the input event is valid according to the Sink API.
bq. Only a Sink knows what output is legal for its format, a Parser should
therefore never insert anything that was not explicitly there in the original
input format.
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, regardless whether the event
is driven by explicit user input or by implicit convention. It is the sink's
responsibility to handle this defined event, whether it support anchors or not.
Regarding the issue of unique anchor names: This is merely another aspect that
needs to be added to the javadoc of the Sink API. If you define that anchor
names must be unique within a document then
# a conforming parser is responsible for providing this uniqueness
# a sink has all right to fail if a non-conforming parser outputs two anchor
events with the same name
bq. I consider it a fundamental design flaw if an input format defines implicit
anchors for section titles.
I am fine with your arguments against implicit anchors. However, then I still
don't understand why sinks are allowed to output implicit anchors for sections.
If we consider such anchors as problematic, nobody should be allowed to create
them. An implicit anchor is an implicit anchor, regardless whether the parser
of the sink created it, isn't it?
For example, if we consider the SiteRenderingSite to be one of those
specialized sinks that may output implicit anchors to the XHTML pages, people
could start using these auto-links to cross-reference to those sections from
external documents (of the same site). Now this a dangerous because as soon as
the users wants to output his nicely linked HTML website into a PDF book, he
will find all the auto-links not working anymore because the PdfSink doesn't
create implicit anchors like the SiteRenderingSink.
bq. We have modified the original apt format
>From SVN logs I see this was created after the last deployment of the doxia
>site (2007-11-06). If it doesn't cause any harm to the overall site, it would
>be cool to have this doc online. For example, the [APT
>Reference|http://maven.apache.org/doxia/references/apt-format.html] still
>reads "Section titles are implicitly defined anchors." which does not apply to
>the version of Doxia used by the Site Plugin, IIRC.
> 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
