You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "Benjamin Bentmann (JIRA)" <ji...@codehaus.org> on 2008/04/18 17:08:55 UTC
[jira] Commented: (DOXIA-236) Clarify Sink API
[ http://jira.codehaus.org/browse/DOXIA-236?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=131285#action_131285 ]
Benjamin Bentmann commented on DOXIA-236:
-----------------------------------------
A thought with regard to event order/nesting: What about defining a Sink Object Model in terms of a XSD? This tree structure should not be expressed by a programmatic API but merely serves as a reference for parser validation. I.e. a {{CanonicalSink}} would output the XML document
{code:xml}
<sink>
<head>
<title>
<text>foo</text>
</title>
</head>
</sink>
{code}
for the event sequence {{head()}}, {{title()}}, {{text("foo")}}, {{_title()}}, {{_head()}}. This tree could then be passed through a validating XML parser (conveniently wrapped in a {{ValidatingSink}}, superceding the {{WellformednessCheckingSink}}) to check that the parser obeys the ordering/nesting rules defined by the XSD. Of course, the XSD would also serve the purpose of documenting the intended usage of the Sink API to implementors.
> 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