[
http://jira.codehaus.org/browse/DOXIA-236?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=132855#action_132855
]
Lukas Theussl commented on DOXIA-236:
-------------------------------------
Some preliminary comments to the points you raised above, just to open the
discussion:
bq. What characters may constitute an anchor reported by anchor()?
An anchor in HTML should be a valid HTML ID token, so IMO we could apply the
same rules to a general sink. See the javadoc for HtmlTools.encodeId().
bq. What format applies to the name parameter of link()?
As I said at DOXIA-208, internal links should start with "#", again a la html.
bq. What character chunks are reported by text()?
Longest consecutive sequence IMO. No pretty printing, no modification
whatsoever.
bq. What exactly is a figure's source as reported by figureGraphics()?
A figure source is just a link, so it can be relative to the current document
or absolute. The figure extension is now required as noted at DOXIA-99.
bq. What order of events is "reasonable" (DOXIA-132)?
We should define a 'canonical' order of events that should be followed by all
parsers. IMO the order emitted by SinkTestDocument could serve as a definition.
What is 'reasonable' is of course subjective, eg IMO a figureCaption can come
before or after figureGraphics, but a definedTerm in a definitionList should
come before the definition.
bq. Is closing a sink twice acceptable or an error?
Can you elaborate why this is relevant? IMO closing a sink a second time should
just do nothing, as it basically just closes the underlying Writer.
> 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
