From owner-freebsd-doc@FreeBSD.ORG Tue Feb 26 17:53:52 2013 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id F39F34B8 for ; Tue, 26 Feb 2013 17:53:51 +0000 (UTC) (envelope-from gkeramidas@gmail.com) Received: from mail-we0-x22e.google.com (mail-we0-x22e.google.com [IPv6:2a00:1450:400c:c03::22e]) by mx1.freebsd.org (Postfix) with ESMTP id 8D9981438 for ; Tue, 26 Feb 2013 17:53:51 +0000 (UTC) Received: by mail-we0-f174.google.com with SMTP id r6so3753801wey.5 for ; Tue, 26 Feb 2013 09:53:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=x-received:sender:date:from:to:cc:subject:message-id:references :mime-version:content-type:content-disposition:in-reply-to; bh=pM0UM0JR49Sy8PUREDQ1uN+aXdqlhtGFEnYtBHClXuE=; b=c1cNBetsv6xrw1IzKYKTHYtCEjGKUUYpBCQCU08XuhkoYB0NsI0fEuxULKLw5ADsgL krIbSCzT/O+++xS0yKDHDUN775U6Wb4m8Px7086QZl8uqduTziiwlFdXzldVgoCIle15 C8q+Qr/gVE2oh3jjFCEnSosoDbS1OjTacLq5nfTJwjgRMdCctXE/+dSlaUHlF2vADOhT Q41eWA0Sb2l68cwNzjgfYIvixmioP0L/3nNsbH04A20X1WYToDh1MwHSy7V7ZZgLjfm+ 3SYqkWrJID0oCogv+YdHJporm+jd5c7/YReGtON/yA7b/lkH5Psh8M8CGglfFG8byqVN ylIA== X-Received: by 10.194.158.198 with SMTP id ww6mr28174267wjb.44.1361901230508; Tue, 26 Feb 2013 09:53:50 -0800 (PST) Received: from saturn (217-162-217-29.dynamic.hispeed.ch. [217.162.217.29]) by mx.google.com with ESMTPS id m6sm3480715wic.2.2013.02.26.09.53.48 (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Tue, 26 Feb 2013 09:53:49 -0800 (PST) Sender: Giorgos Keramidas Date: Tue, 26 Feb 2013 18:53:45 +0100 From: Giorgos Keramidas To: Warren Block Subject: Re: Do we care for manpage links in elements? Message-ID: <20130226175343.GB10642@saturn> References: <20130226124932.GA7258@saturn> <20130226134414.GA8899@saturn> <20130226094528.6cff2a60.trhodes@FreeBSD.org> <20130226171905.GA10642@saturn> <alpine.BSF.2.00.1302261041560.46495@wonkity.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <alpine.BSF.2.00.1302261041560.46495@wonkity.com> 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:53:52 -0000 On 2013-02-26 10:45, Warren Block <wblock@wonkity.com> wrote: >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. 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).