[
http://jira.codehaus.org/browse/DOXIA-236?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=133124#action_133124
]
Benjamin Bentmann commented on DOXIA-236:
-----------------------------------------
Fine that you pointed out the optional nulls for the sink attributes, too! Just
one concern:
bq. Section titles [...] should (sic!) never be implicit anchors.
IMHO, this should have been the opposite of the current javadocs, i.e. "must
not" add anchors on the sink side, "may" do so on the parser side.
Rationale:
I believe it's a valuable design choice if the syntax and semantics of an
output document are completely separated:
- a parser defines the semantics (text, links, formatting) by means of sink
events, i.e. it defines *what* elements constitute the document
- a sink defines the syntax for a particular output format, i.e. it defines
*how* the document will be encoded
If a parser did not emit an anchor within a section title, I don't see any
argument why a sink should be allowed to add one. This would only lead to
inconsistent behavior of the output documents: one document might have a link
and another one might have not, surprise suprise. The parser is (usually)
processing an input file from the user, so if the parser didn't get the user's
intention to output an anchor, why should the sink think differently out of a
sudden?
{noformat}
Parser: Dear sink, my master wants to output a section title.
Sink: Dear parser, I don't know your master but I know he meant to output an
anchor, too.
{noformat}
Some people would call this sink a fortune teller ;-)
Regarding the parser: If an input format defines (say as a matter of
convenience) that something like
{noformat}
* Section
{noformat}
defines an implicit anchor and is equivalent to
{noformat}
* {Section}
{noformat}
a parser simply needs to be allowed to issue both a section title and an
(implicit) anchor in case of the first input snippet. I mean, restricting the
parsers is equivalent to restricting the input formats which seems plain wrong
if Doxia wants to be open-minded.
I'm not too familar with Doxia so my understanding might be wrong. If you feel
there's more to discuss, we can simply switch over to doxia-dev where Jason and
Vincent can hopefully clarify things, too.
> 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
