[ http://jira.codehaus.org/browse/DOXIA-236?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=133023#action_133023 ]
Benjamin Bentmann commented on DOXIA-236: ----------------------------------------- bq. See DOXIA-59 Alright, we just need to have specs on both sides: What terminators may a parser report to a sink and what line terminator should a sink issue to the output document? bq. I am working on updated javadocs to the Sink interface Thanks Lukas, I really appreciate your efforts on this. I can't fight the impression that some Maven developers don't consider the importance of well-defined/-documented APIs and so it's a gladness to see that there are exceptions! > 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
