Re: Bad Man Page URLs

From: Jeff King <peff@peff.net>
Date: Apr 6, 2012, 02:54 UTC
Message-ID: <20120406025457.GA23997@sigill.intra.peff.net>
In-Reply-To: <20120406023223.GB16264@sigill.intra.peff.net>

On Thu, Apr 05, 2012 at 10:32:23PM -0400, Jeff King wrote:

Show 12 quoted lines

> That being said, it would be nice for the prebuilt manpages to have
> something more location-agnostic in them. These links are generated by
> asciidoc's "link:" directive. The HTML versions properly use relative
> links, but the links are expanded into full URLs for the manpages. Which
> makes sense, since there's no concept of a relative link here.
> 
> So we can tweak it by using a custom link macro (we already have
> "linkgit" for linking to actual commands). But what should the agnostic
> version say? Just saying "look at everday.html in the git documentation"
> is not as nice as a real URL, but we really don't have any more
> information than that. Maybe they should be pointing to some canonical
> version on the web?

I dug on this a little more. It seems that the "link" macro in asciidoc is overridable, so we could just redefine it as appropriate. However, the existing implementation actually generates a reasonable-looking docbook <ulink>, and it is docbook that is responsible for turning it into an absolute URL.

So I think technically the docbook part of the toolchain would be the right place to fix this. But it may be easier to hack around it at the asciidoc level.

Something like the code below would work:

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index aea8627..1edbabe 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -93,3 +93,10 @@ ifdef::backend-xhtml11[]
 [linkgit-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
+
+ifdef::generic-location[]
+ifdef::backend-docbook[]
+[link-inlinemacro]
+<ulink url="http://official-location/{target}">{0={target}}</ulink>
+endif::backend-docbook[]
+endif::generic-location[]

though it assumes that link targets are relative. There are a handful of
instances where that is not the case (we can either introduce a linkabs
for them, or leave them and switch most of the existing link: macros
over to linkrel: or something).

-Peff