Re: generated HTML contains broken links

From: Dan McGee <dpmcgee@gmail.com>
Date: Dec 29, 2007, 03:01 UTC
Message-ID: <4775B87D.4010507@gmail.com>
In-Reply-To: <87sl1mqt10.fsf@offby1.atm01.sea.blarg.net>

On 12/28/2007 05:49 PM, Eric Hanchrow wrote:

Show 12 quoted lines

> I'm just starting to play with git, and have checked it out (with "git
> clone git://git.kernel.org/pub/scm/git/git.git"), and built the
> documentation (cd Documentation; make), on Cygwin.  I notice that the
> generated HTML docs are full of broken links -- for example, my file
> C:/cygwin/usr/local/src/git/Documentation/git.html includes this:
> 
>         git<a href="git-instaweb">1</a>
> 
> but there is no document named "git-instaweb" on my disk; instead,
> it's named "git-instaweb.html".
> 
> I'm using asciidoc version 8.2.4, if it matters.

We noticed this with the upgrade from Asciidoc 8.2.2 -> 8.2.3 on our project. It is broken in both the manpages and the HTML generated documentation. I've included an example below. So far, I haven't had luck tracking down the reason but I am looking into trying to fix this tonight. If anyone else is better with this stuff, it would be great if you could take a look.

Relevant email on the pacman-dev list [1]:

On Nov 9, 2007 4:05 PM, Andrew Fyfe <andrew@neptune-one.net> wrote:

Show 8 quoted lines

> Did little digging, the breakage/change is in now asciidoc converts from asciidoc to xml (so it's 
> not docbook-xsl). In 8.2.2 manlink:pacman.conf[5] expands to
> 
> <citerefentry><refentrytitle>pacman.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
> 
> in 8.2.3 it expands to
> 
> man<ulink url="pacman.conf">5</ulink>,

Note that manlink is basically just a renamed gitlink, and can be found here: <http://projects.archlinux.org/git/?p=pacman.git;a=blob;f=doc/asciidoc.conf>

-Dan

[1] <http://archlinux.org/pipermail/pacman-dev/2007-November/009937.html>

Generated man pages from Junio:
HOOKS
       This command can run commit-msg, pre-commit, and post-commit hooks. See
       [1]hooks for more information.

SEE ALSO
       git-add(1), git-rm(1), git-mv(1), git-merge(1), git-commit-tree(1)

AUTHOR
       Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano
       <junkio@cox.net>

GIT
       Part of the git(7) suite

Man pages generated locally (with Asciidoc 8.2.3 or 8.2.5):
HOOKS
       This command can run commit-msg, pre-commit, and post-commit hooks. See
       hooks[5] for more information.

SEE ALSO
       git1[1], git1[2], git1[8], git1[6], git1[9]

AUTHOR
       Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano
       <junkio@cox.net>

GIT
       Part of the git7[10] suite