maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Benjamin Bentmann" <>
Subject Re: Review Link Handling in APT
Date Sat, 12 Apr 2008 14:05:25 GMT
> Intuitive is probably a subjective concept


> I don't find the current behavior that un-intuitive. If current apt makes
> {{foo}bar}}  an internal link then I would intuitively expect that
> {{foo.x}bar}} is an internal link too

Let's remember that this expectation is in general not true regarding the
current implementation: {{{foo.html}bar}} will be considered external. This
is an exception to your otherwise simple rule, breaking with intuition.

> I think the current apt format is well-defined, it's just different from
> html.

A fair amount behind intuition is about past experiences. I doubt that users
that are used to HTML will find APT's link handling intuitive because it's
just different from their experiences. Of course, somebody that is used to
the original APT format will be happy. So the question might be which group
of users is bigger?

> If all parsers would emit a # for internal links then any sink can process
> it without making assumptions of where it came from. Once we have defined
> and consistently implemented that in all modules, it would be easy to do
> format changes without worrying about breaking stuff all over place.

Yes, if the idea behind Doxia with pluggable parsers and renderes should be
of any use, the Sink API must be well defined. I guess I already posted it
over on dev@maven but would like to repeat: I consider it crucial for the
longterm vitality of a project that its APIs are properly documented (e.g.
Javadoc). For instance, would surely need some more lines to
precisely describe the format of its name argument, the same for
Sink.anchor(). Are links/anchors restricted to certain characters or are
renderers assumed to automatically fix inappropriate names? I also remember
that we once wondered whether Sink.text() events need to be reported
individually for each line. Whitespace handling might also be worth a 
detailed specification. The API should either define its requirements or 
clearly declare a parser's freedom on event generation.


View raw message