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

[Jeff King <peff@peff.net>]

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

> >  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