Review Link Handling in APT

[Benjamin Bentmann]

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 

[Vincent Siveton]

Hi Benjamin,

2008/4/12, Benjamin Bentmann <benjamin.bentmann@...>:

> 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}}.

Not sure. Take a look to the renderer [1] and the source [2]. Link are
external for {{{guide-testing-releases.html} test releases}}

Cheers,

Vincent

[1] http://maven.apache.org/guides/development/guide-helping.html
[2] https://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/guides/development/guide-helping.apt

>  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
>

[ltheussl]

See my comment at http://jira.codehaus.org/browse/DOXIA-208

In short: yes it would be easier and it would have spared us a lot of
pain in the past if apt would handle links like everyone else. But
changing that now we would IMO risk more by confusing users and breaking
things than we gain by a more intuitive behavior.

However, given our history of breaking things (especially wrt
anchors/links) I am not categorically opposed to changing stuff. :) Just
if we decide to go for it then we should either do it now for beta-1, or
postpone it until after 1.0-final.

-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
>

[Benjamin Bentmann]

> Not sure. Take a look to the renderer [1] and the source [2]. Link are
> external for {{{guide-testing-releases.html} test releases}}

I just stumbled upon this in r647420 [0]. After some other tries I figured
out:
- {{{foo.html}baa}} is external
- {{{foo.txt}baa}} is internal
i.e. the linking behaviour depends on the file extension.

That's the kind of black magic for which Maven is blamed by users.


Benjamin


[0] http://svn.apache.org/viewvc?view=rev&revision=647420 

[ltheussl]

Vincent Siveton wrote:

> Hi Benjamin,
>
> 2008/4/12, Benjamin Bentmann <benjamin.bentmann@...>:
>
>>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}}.
>
>
> Not sure. Take a look to the renderer [1] and the source [2]. Link are
> external for {{{guide-testing-releases.html} test releases}}

That's just because html files are handled specially for backward-compat
reasons, links are external for files that end with ".html" (see the
isExternalHtml method in XhtmlBaseSink). In principle you should use
{{{./guide-testing-releases.html} test releases}} also for this case.

>
> Cheers,
>
> Vincent
>
> [1] http://maven.apache.org/guides/development/guide-helping.html
> [2] https://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/guides/development/guide-helping.apt
>
>
>
>> 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
>>
>
>

[Dennis Lundberg-2]

Vincent Siveton wrote:

> Hi Benjamin,
>
> 2008/4/12, Benjamin Bentmann <benjamin.bentmann@...>:
>> 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}}.
>
> Not sure. Take a look to the renderer [1] and the source [2]. Link are
> external for {{{guide-testing-releases.html} test releases}}

IIRC there is some special handling if the href part of a link ends with
".html". In such cases they are always treated as an external link.

>
> Cheers,
>
> Vincent
>
> [1] http://maven.apache.org/guides/development/guide-helping.html
> [2] https://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/guides/development/guide-helping.apt
>
>
>>  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
>>
>

--
Dennis Lundberg

[Vincent Siveton]

2008/4/12, Benjamin Bentmann <benjamin.bentmann@...>:

> > Not sure. Take a look to the renderer [1] and the source [2]. Link are
> > external for {{{guide-testing-releases.html} test releases}}
> >
>
>  I just stumbled upon this in r647420 [0]. After some other tries I figured
> out:
>  - {{{foo.html}baa}} is external
>  - {{{foo.txt}baa}} is internal
>  i.e. the linking behaviour depends on the file extension.
>
>  That's the kind of black magic for which Maven is blamed by users.
>

Same tricks that dev forgot ;)

Cheers,

Vincent

>
>  Benjamin
>
>
>  [0] http://svn.apache.org/viewvc?view=rev&revision=647420
>

[Benjamin Bentmann]

> See my comment at http://jira.codehaus.org/browse/DOXIA-208

Your proposal at
http://docs.codehaus.org/display/DOXIA/Proposed+Changes+to+the+APT+Format
already suggests to break compat with the original APT format. I beg you to
go this route down to its end and make APT a user-friendly format. If it
helps, call it N(ew)APT, B(etter)APT, D(oxia)APT or whatever ;-)

> However, given our history of breaking things (especially wrt
> anchors/links) I am not categorically opposed to changing stuff. :) Just
> if we decide to go for it then we should either do it now for beta-1, or
> postpone it until after 1.0-final.

I'm really in favor to get the link handling straight as soon as possible
and believe beta-1 is a good chance to do it. The more you wait, the more
users/docs will rely on the currently weird link handling such that the
penalty of breaking will increase.

It's always pity if backward-compat prevents one from fixing questionable
decisions in the past. Maybe the best way to come to conclusion for this
controversial topic is to call a simple vote on the mailing lists (I guess
user@maven will reach the most) and get a feel of the world's thoughts on
this.


Benjamin

[ltheussl]

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
>

[ltheussl]

Benjamin Bentmann wrote:
>> See my comment at http://jira.codehaus.org/browse/DOXIA-208
>
>
> Your proposal at
> http://docs.codehaus.org/display/DOXIA/Proposed+Changes+to+the+APT+Format
> already suggests to break compat with the original APT format. I beg you to
> go this route down to its end and make APT a user-friendly format. If it
> helps, call it N(ew)APT, B(etter)APT, D(oxia)APT or whatever ;-)

We have already implemented a number of enhancements/changes to the
original apt format:
http://svn.apache.org/viewvc/maven/doxia/site/src/site/apt/references/doxia-apt.apt

>
>> However, given our history of breaking things (especially wrt
>> anchors/links) I am not categorically opposed to changing stuff. :) Just
>> if we decide to go for it then we should either do it now for beta-1, or
>> postpone it until after 1.0-final.
>
>
> I'm really in favor to get the link handling straight as soon as possible
> and believe beta-1 is a good chance to do it. The more you wait, the more
> users/docs will rely on the currently weird link handling such that the
> penalty of breaking will increase.

As I said in my other mail, I don't quite see the necessity. It's a big
change with a big risk of breaking things for a little bit of more
intuitive behavior.

>
> It's always pity if backward-compat prevents one from fixing
> questionable decisions in the past. Maybe the best way to come to
> conclusion for this controversial topic is to call a simple vote on the
> mailing lists (I guess user@maven will reach the most) and get a feel of
> the world's thoughts on this.

I don't think adopting the apt format was a questionable decision. The
mistake that was made is that the AptParser was taken over from
aptconvert without modification and the XhtmlSink was adapted to its
behavior (since at the time, people were only interested in apt->html).
But this is something that can be corrected without user penalty.

I'm not sure about the vote, I could imagine that all people that are on
the user list now have gotten used to the current format already and so
wouldn't want to change it.

-Lukas

>
>
> Benjamin
>
>

[Benjamin Bentmann]

> Intuitive is probably a subjective concept

Agreed.

> 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, Sink.link() 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.


Benjamin