Solving links and anchors

[dennisl]

Hi

As you probably saw on dev@maven we had some problems yesterday with
links being rendered in the wrong way by doxia. I have made a temporary
fix for this, but I feel that we need to do more to get a stable solution.

The issues which are related to these problems are
- http://jira.codehaus.org/browse/DOXIA-47
- http://jira.codehaus.org/browse/DOXIA-131

My temporary fix reverses the logic. Instead of trying to see if a text
is an "external link", I try to determine if a text is *not* an
"internal link". With a few minor adjustments (see my comment on
DOXIA-131) I think that this would be a more stable solution.

What do you think?

--
Dennis Lundberg

[Vincent Siveton-2]

2007/8/11, Dennis Lundberg <[hidden email]>:

> Hi
>
> As you probably saw on dev@maven we had some problems yesterday with
> links being rendered in the wrong way by doxia. I have made a temporary
> fix for this, but I feel that we need to do more to get a stable solution.
>
> The issues which are related to these problems are
> - http://jira.codehaus.org/browse/DOXIA-47
> - http://jira.codehaus.org/browse/DOXIA-131
>
> My temporary fix reverses the logic. Instead of trying to see if a text
> is an "external link", I try to determine if a text is *not* an
> "internal link". With a few minor adjustments (see my comment on
> DOXIA-131) I think that this would be a more stable solution.
>
> What do you think?

Sounds goods.
IMHO, the ideal solution will be to not change the util encodeId()
(which respects HTML spec) to disallow dot.

Cheers,

Vincent


> --
> Dennis Lundberg
>

[ltheussl]

I also don't like disallowing dots in ids. Hhyphens ("-"), underscores
("_"), colons (":"), and periods (".") are perfectly legal in ids
according to the html specs, I don't see any reason why doxia should
replace them. Underscores where used in the m1 xdoc plugin to replace
any illegal characters, which I think is better than just stripping
them, for readability reasons (think section titles). However, the use
of automatically constructed ids from section titles was discouraged in
the last version of the xdoc plugin [1] as it only led to trouble (which
  btw very much reminds me of our current ones, see MPXDOC-158 and
MPPDF-40 for related discussions).

The root of the problem are the conventions used by aptconvert, and
apart from being undocumented, I don't really like them, so the question
is: how compatible do we want/have to stay with that?

If I am not mistaken, the issue should be solved simply by requiring
that links to other documents have to start with './' or '../', as I
indicated at DOXIA-47. The only problem then is backward compatibility,
since currently this is rarely the case (eg the project reports page in
the site plugin [2] uses

sink.link( report.getOutputName() + ".html" );

where report.getOutputName() doesn't start with './').

However, in principle I think this is the way it should work (and always
should have in the first place), so maybe we try to clear that up and
document it for beta-1?

Cheers,
-Lukas

[1]
http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html#Referencing_sections_and_subsections
[2]
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/main/java/org/apache/maven/plugins/site/CategorySummaryDocumentRenderer.java?revision=519777&view=markup

Vincent Siveton wrote:

> 2007/8/11, Dennis Lundberg <[hidden email]>:
>
>>Hi
>>
>>As you probably saw on dev@maven we had some problems yesterday with
>>links being rendered in the wrong way by doxia. I have made a temporary
>>fix for this, but I feel that we need to do more to get a stable solution.
>>
>>The issues which are related to these problems are
>>- http://jira.codehaus.org/browse/DOXIA-47
>>- http://jira.codehaus.org/browse/DOXIA-131
>>
>>My temporary fix reverses the logic. Instead of trying to see if a text
>>is an "external link", I try to determine if a text is *not* an
>>"internal link". With a few minor adjustments (see my comment on
>>DOXIA-131) I think that this would be a more stable solution.
>>
>>What do you think?
>
>
> Sounds goods.
> IMHO, the ideal solution will be to not change the util encodeId()
> (which respects HTML spec) to disallow dot.
>
> Cheers,
>
> Vincent
>
>
>
>>--
>>Dennis Lundberg
>>

[dennisl]

Welcome back Lukas!

So, we seem to be in agreement that the handling of ids should be as it
is right now. That is we allow these characters -_:.

That should mean that DOXIA-131 is solved right?

I suggest that we publish snapshots of what we have in svn now, to make
sure that things are working OK. Then we release alpha-9 and decide how
to handle backward-compatibility issues before beta-1. WDYT?

Lukas Theussl wrote:

> I also don't like disallowing dots in ids. Hhyphens ("-"), underscores
> ("_"), colons (":"), and periods (".") are perfectly legal in ids
> according to the html specs, I don't see any reason why doxia should
> replace them. Underscores where used in the m1 xdoc plugin to replace
> any illegal characters, which I think is better than just stripping
> them, for readability reasons (think section titles). However, the use
> of automatically constructed ids from section titles was discouraged in
> the last version of the xdoc plugin [1] as it only led to trouble (which
>  btw very much reminds me of our current ones, see MPXDOC-158 and
> MPPDF-40 for related discussions).
>
> The root of the problem are the conventions used by aptconvert, and
> apart from being undocumented, I don't really like them, so the question
> is: how compatible do we want/have to stay with that?
>
> If I am not mistaken, the issue should be solved simply by requiring
> that links to other documents have to start with './' or '../', as I
> indicated at DOXIA-47. The only problem then is backward compatibility,
> since currently this is rarely the case (eg the project reports page in
> the site plugin [2] uses
>
> sink.link( report.getOutputName() + ".html" );
>
> where report.getOutputName() doesn't start with './').
>
> However, in principle I think this is the way it should work (and always
> should have in the first place), so maybe we try to clear that up and
> document it for beta-1?
>
> Cheers,
> -Lukas
>
> [1]
> http://maven.apache.org/maven-1.x/plugins/xdoc/reference/xdocs.html#Referencing_sections_and_subsections 
>
> [2]
> http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/main/java/org/apache/maven/plugins/site/CategorySummaryDocumentRenderer.java?revision=519777&view=markup 
>
>
> Vincent Siveton wrote:
>> 2007/8/11, Dennis Lundberg <[hidden email]>:
>>
>>> Hi
>>>
>>> As you probably saw on dev@maven we had some problems yesterday with
>>> links being rendered in the wrong way by doxia. I have made a temporary
>>> fix for this, but I feel that we need to do more to get a stable
>>> solution.
>>>
>>> The issues which are related to these problems are
>>> - http://jira.codehaus.org/browse/DOXIA-47
>>> - http://jira.codehaus.org/browse/DOXIA-131
>>>
>>> My temporary fix reverses the logic. Instead of trying to see if a text
>>> is an "external link", I try to determine if a text is *not* an
>>> "internal link". With a few minor adjustments (see my comment on
>>> DOXIA-131) I think that this would be a more stable solution.
>>>
>>> What do you think?
>>
>>
>> Sounds goods.
>> IMHO, the ideal solution will be to not change the util encodeId()
>> (which respects HTML spec) to disallow dot.
>>
>> Cheers,
>>
>> Vincent
>>
>>
>>
>>> --
>>> Dennis Lundberg
>>>
>

--
Dennis Lundberg

[ltheussl]

I agree. DOXIA-131 is solved and we should release alpha-9 asap so we
can concentrate on the changes that are scheduled for beta-1.

Cheers,
-Lukas

Dennis Lundberg wrote:

> Welcome back Lukas!
>
> So, we seem to be in agreement that the handling of ids should be as it
> is right now. That is we allow these characters -_:.
>
> That should mean that DOXIA-131 is solved right?
>
> I suggest that we publish snapshots of what we have in svn now, to make
> sure that things are working OK. Then we release alpha-9 and decide how
> to handle backward-compatibility issues before beta-1. WDYT?
>
>

[ltheussl]

FYI: I have just deployed new snapshots of doxia (core + modules +
sink-api + site-tools). For me, alpha-9 is release ready.

However, I have tried to build the current maven site, reverting Brett's
commit [1] to use site-plugin-2.0-SNAPSHOT again (so doxia-alpha-9 gets
picked up), and found a few links that need fixing, eg in
run-maven/index.apt, there is a link

{{{#Quick Start} Quick Start}}

which should be

{{{Quick_Start} Quick Start}}

and in guides/development/guide-helping.apt, there is

{{{guide-m2-development.html#Maven Code Style} Code Style}}

which should be

{{{guide-m2-development.html#Maven_Code_Style} Code Style}}


For me this seems rather natural as spaces are not legal in anchor names
(and never have been AFAIK, even for aptconvert), however, I'm wondering
if this might be considered a backward compat issue?

-Lukas


[1]
https://svn.apache.org/viewvc/maven/site/trunk/pom.xml?r1=549382&r2=564821&diff_format=h


Lukas Theussl wrote:

>
> I agree. DOXIA-131 is solved and we should release alpha-9 asap so we
> can concentrate on the changes that are scheduled for beta-1.
>
> Cheers,
> -Lukas
>
> Dennis Lundberg wrote:
>
>> Welcome back Lukas!
>>
>> So, we seem to be in agreement that the handling of ids should be as
>> it is right now. That is we allow these characters -_:.
>>
>> That should mean that DOXIA-131 is solved right?
>>
>> I suggest that we publish snapshots of what we have in svn now, to
>> make sure that things are working OK. Then we release alpha-9 and
>> decide how to handle backward-compatibility issues before beta-1. WDYT?
>>
>>

[dennisl]

Lukas Theussl wrote:
> FYI: I have just deployed new snapshots of doxia (core + modules +
> sink-api + site-tools). For me, alpha-9 is release ready.

I agree that it is time for a release.

> However, I have tried to build the current maven site, reverting Brett's
> commit [1] to use site-plugin-2.0-SNAPSHOT again (so doxia-alpha-9 gets
> picked up), and found a few links that need fixing, eg in
> run-maven/index.apt, there is a link
>
> {{{#Quick Start} Quick Start}}
>
> which should be
>
> {{{Quick_Start} Quick Start}}
>
> and in guides/development/guide-helping.apt, there is
>
> {{{guide-m2-development.html#Maven Code Style} Code Style}}
>
> which should be
>
> {{{guide-m2-development.html#Maven_Code_Style} Code Style}}
>
>
> For me this seems rather natural as spaces are not legal in anchor names
> (and never have been AFAIK, even for aptconvert), however, I'm wondering
> if this might be considered a backward compat issue?

Doxia is still in alpha. I think we can get away with fixing something
that was broken, even if it means that a few pages will not render in
the same way that they did in alpha-8.

>
> -Lukas
>
>
> [1]
> https://svn.apache.org/viewvc/maven/site/trunk/pom.xml?r1=549382&r2=564821&diff_format=h 
>
>
>
> Lukas Theussl wrote:
>>
>> I agree. DOXIA-131 is solved and we should release alpha-9 asap so we
>> can concentrate on the changes that are scheduled for beta-1.
>>
>> Cheers,
>> -Lukas
>>
>> Dennis Lundberg wrote:
>>
>>> Welcome back Lukas!
>>>
>>> So, we seem to be in agreement that the handling of ids should be as
>>> it is right now. That is we allow these characters -_:.
>>>
>>> That should mean that DOXIA-131 is solved right?
>>>
>>> I suggest that we publish snapshots of what we have in svn now, to
>>> make sure that things are working OK. Then we release alpha-9 and
>>> decide how to handle backward-compatibility issues before beta-1. WDYT?
>>>
>>>
>

--
Dennis Lundberg