From owner-freebsd-doc@FreeBSD.ORG  Tue Feb 26 17:45:37 2013
Return-Path: <owner-freebsd-doc@FreeBSD.ORG>
Delivered-To: freebsd-doc@freebsd.org
Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115])
 by hub.freebsd.org (Postfix) with ESMTP id 2651021B;
 Tue, 26 Feb 2013 17:45:37 +0000 (UTC)
 (envelope-from wblock@wonkity.com)
Received: from wonkity.com (wonkity.com [67.158.26.137])
 by mx1.freebsd.org (Postfix) with ESMTP id CEAF11254;
 Tue, 26 Feb 2013 17:45:36 +0000 (UTC)
Received: from wonkity.com (localhost [127.0.0.1])
 by wonkity.com (8.14.6/8.14.6) with ESMTP id r1QHjZsJ046544;
 Tue, 26 Feb 2013 10:45:35 -0700 (MST)
 (envelope-from wblock@wonkity.com)
Received: from localhost (wblock@localhost)
 by wonkity.com (8.14.6/8.14.6/Submit) with ESMTP id r1QHjZYe046541;
 Tue, 26 Feb 2013 10:45:35 -0700 (MST)
 (envelope-from wblock@wonkity.com)
Date: Tue, 26 Feb 2013 10:45:35 -0700 (MST)
From: Warren Block <wblock@wonkity.com>
To: Giorgos Keramidas <keramida@FreeBSD.org>
Subject: Re: Do we care for manpage links in <title> elements?
In-Reply-To: <20130226171905.GA10642@saturn>
Message-ID: <alpine.BSF.2.00.1302261041560.46495@wonkity.com>
References: <20130226124932.GA7258@saturn> <20130226134414.GA8899@saturn>
 <20130226094528.6cff2a60.trhodes@FreeBSD.org> <20130226171905.GA10642@saturn>
User-Agent: Alpine 2.00 (BSF 1167 2008-08-23)
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7
 (wonkity.com [127.0.0.1]); Tue, 26 Feb 2013 10:45:35 -0700 (MST)
Cc: freebsd-doc@freebsd.org
X-BeenThere: freebsd-doc@freebsd.org
X-Mailman-Version: 2.1.14
Precedence: list
List-Id: Documentation project <freebsd-doc.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/options/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-doc>
List-Post: <mailto:freebsd-doc@freebsd.org>
List-Help: <mailto:freebsd-doc-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-doc>,
 <mailto:freebsd-doc-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Tue, 26 Feb 2013 17:45:37 -0000

On Tue, 26 Feb 2013, Giorgos Keramidas wrote:

> On 2013-02-26 09:45, Tom Rhodes <trhodes@FreeBSD.org> wrote:
>> On Tue, 26 Feb 2013 14:44:15 +0100 Giorgos Keramidas <keramida@FreeBSD.org> wrote:
>>> On 2013-02-26 13:49, Giorgos Keramidas <keramida@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.