Re: [RFC/PATCH] doc: git-foo was obsoleted several years ago

From: Jeff King <peff@peff.net>
Date: Oct 17, 2013, 01:18 UTC
Message-ID: <20131017011807.GA14759@sigill.intra.peff.net>
In-Reply-To: <xmqq7gdc7v70.fsf@gitster.dls.corp.google.com>

On Wed, Oct 16, 2013 at 02:38:27PM -0700, Junio C Hamano wrote:

Show 9 quoted lines

> >  Documentation/git-checkout.txt | 4 ++--
> [...]
> I recall that I wanted to see this change happen myself long time
> ago, and suspect that there may have been some reason that prevented
> us from doing so.  I might have found that AsciiDoc back then did
> not like the input if the headline name "git-checkout(1)" did not
> match the filename "git-checkout.txt" and the command in the NAME
> section "git-checkout", or links "linkgit:git-checkout[1]" from
> other pages couldn't have SP there, or something silly like that.

Yes, I think it is still broken. After applying Felipe's patch:

  $ cd Documentation
  $ make git-checkout.1
      GEN cmd-list.made
      SUBDIR ../
  make[1]: `GIT-VERSION-FILE' is up to date.
      ASCIIDOC git-checkout.xml
      XMLTO git-checkout.1

So far, so good...

  $ man -l git-checkout.1
  man: git-checkout.1: No such file or directory

Huh?

  $ ls git?checkout.1
  git_checkout.1

Oh.

There is similar asciidoc (actually, I think it is docbook) cleverness with:

  $ make gitignore.1
      GEN cmd-list.made
      SUBDIR ../
      make[1]: `GIT-VERSION-FILE' is up to date.
      XMLTO gitignore.1

  $ ls gitignore.[0-9]
  gitignore.5

Now obviously what I asked for is wrong (we do not actually know how to make gitignore.1), but I have certainly been confused by this in the past when working on pages outside of section 1.

In both cases, it would be nice if we could tell xmlto "no, really, put the output in this file". I'm not sure that is an option, though, because in theory docbook output may be multiple files (the "-o" option actually specifies an output directory).

Since we know our manpages are a much simpler case, we could probably work around it by teaching the Makefile that building "git-foo.txt" generates git_foo.1, and then moving that to git-foo.1.

-Peff