Do we care for manpage links in <title> elements?

[Giorgos Keramidas]

On 2013-02-26 10:45, Warren Block <wblock at wonkity.com> wrote:
>On Tue, 26 Feb 2013, Giorgos Keramidas wrote:
>>On 2013-02-26 09:45, Tom Rhodes <trhodes at FreeBSD.org> wrote:
>>>On Tue, 26 Feb 2013 14:44:15 +0100 Giorgos Keramidas <keramida at FreeBSD.org> wrote:
>>>>On 2013-02-26 13:49, Giorgos Keramidas <keramida at FreeBSD.org> wrote:
>>>>>Hi everyone,
>>>>>I just noticed that in all the places where a chapter <title> includes a
>>>>>&an.xxx.section; entity the rendering in HTML output sucks a bit.  Note
>>>>>how there are two separate links in the 'Using rc(8) Under FreeBSD'
>>>>>title in the following screenshot:
>>>>>
>>>>>    http://people.freebsd.org/~keramida/rc8-title-link.png
>>>>
>>>>This sort of diff fixes the title-link rendering:
>>>>http://bitbucket.org/keramida/doc-work/commits/d44757193d819f1c950f0236801a37ef77d4711a
>>>>
>>>>But this is admittedly a "hack", and the optimal solution would be to
>>>>conditionally render &man.foo.N; differently in <title> elements.
>>>
>>>Change the title "Using Run Control (RC)"
>>
>>This is not the only case where <title> embeds a &man.xxx.N; link, so I
>>think we need a more general plan for all of them :-)
> 
> Agreed.  If valid markup produces broken output, it's the
> toolchain's fault and should be fixed.
> 
> Should man page or other entities be used in titles?  Sure.  Using a
> different term in the title than in the text only makes things less
> consistent for the reader.

The 'naive' thing to do is to manually remove the &man.xxx.1; links from
title elements:

http://people.freebsd.org/~keramida//patch-no-title-man-links.diff

Replacing the double nested <a>...</a> element does indeed fix the
rendered output.

I'm gonig to dig into the DSSSL code that renders <email> elements to
see if I can selectively disable this when <email>'s parent element is
a <title>.  "It shouldn't be so hard" (famous last words).