From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jeff King Subject: Re: Bad Man Page URLs Date: Thu, 5 Apr 2012 22:54:57 -0400 Message-ID: <20120406025457.GA23997@sigill.intra.peff.net> References: <2AC038A1-3D8D-425E-92B3-DADFD027761A@justatheory.com> <20120406023223.GB16264@sigill.intra.peff.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Cc: git@vger.kernel.org To: "David E. Wheeler" X-From: git-owner@vger.kernel.org Fri Apr 06 04:55:12 2012 Return-path: Envelope-to: gcvg-git-2@plane.gmane.org Received: from vger.kernel.org ([209.132.180.67]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1SFzKP-00028c-9T for gcvg-git-2@plane.gmane.org; Fri, 06 Apr 2012 04:55:09 +0200 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752673Ab2DFCzB (ORCPT ); Thu, 5 Apr 2012 22:55:01 -0400 Received: from 99-108-226-0.lightspeed.iplsin.sbcglobal.net ([99.108.226.0]:49528 "EHLO peff.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752383Ab2DFCzB (ORCPT ); Thu, 5 Apr 2012 22:55:01 -0400 Received: (qmail 30733 invoked by uid 107); 6 Apr 2012 02:55:04 -0000 Received: from sigill.intra.peff.net (HELO sigill.intra.peff.net) (10.0.0.7) (smtp-auth username relayok, mechanism cram-md5) by peff.net (qpsmtpd/0.84) with ESMTPA; Thu, 05 Apr 2012 22:55:04 -0400 Received: by sigill.intra.peff.net (sSMTP sendmail emulation); Thu, 05 Apr 2012 22:54:57 -0400 Content-Disposition: inline In-Reply-To: <20120406023223.GB16264@sigill.intra.peff.net> Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Archived-At: On Thu, Apr 05, 2012 at 10:32:23PM -0400, Jeff King wrote: > 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 , 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] {target}{0?({0})} endif::backend-xhtml11[] + +ifdef::generic-location[] +ifdef::backend-docbook[] +[link-inlinemacro] +{0={target}} +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