Thanks for the graphic illustration
Sometimes I just can't resist my brain dumps, sorry
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.
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.
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
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.
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 still reads "Section titles are implicitly defined anchors." which does not apply to the version of Doxia used by the Site Plugin, IIRC.