Coming back to your original mail, I actually don't quite see the
necessity of the change. Intuitive is probably a subjective concept, but
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 (remembering that dots are legal
characters in anchor names). And if you move your doc.pdf up one
directory I find it clear that you should use ./doc.pdf instead of
dir/doc.pdf for the anchor. I think the current apt format is
well-defined, it's just different from html.
IMO it would be enough to just properly document it but I think it's
much more important that we clean up internally the current mess of
link/anchor handling (DOXIA-208). Eg all the methods that check anchors
in XhtmlBaseSink were tagged on later to account for the behavior of the
AptParser, but they really shouldn't be necessary.
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.
-Lukas
Benjamin Bentmann wrote:
Hi,
According to the APT Reference [0] and the output delivered by the Maven
Site Plugin 2.0-beta-6, the construct
{{{foo}baa}}
denotes an internal link to the anchor "foo" in the current document. I
believe this kind of linking is inconsistent/unintuitive and hence
error-prone.
For example, {{{dir/doc.pdf}baa}} will render an external link as
expected. Now let's move doc.pdf up one directory. The appealing snippet
{{{doc.pdf}baa}} will not give you the desired external link but out of
a sudden an internal link. To get the desired link, users need to write
{{{./doc.pdf}baa}}.
Wouldn't it be easier, both for users and the parser, if APT would
handle links just like the well-known HTML format? I.e. a link is
internal if and only if it starts with '#'.
What do you think?
Benjamin
[0] http://maven.apache.org/doxia/references/apt-format.html
