Re: Suggestion: "man git clone"

(Sorry I didn't see this until now. HPA only CCed the maintainer of one of the two man packages popular on Linux-based systems; I'm the other one. I happened to find this thread while searching for something else.)

In article <48AE143C.8030704@acm.org>, Federico Lucifredi wrote:

I think this is a sensible enough compromise, especially given an option to disable it. The code would be a little ugly, but *shrug* not that bad. The extra stat is cheap enough.

Using a plain 'git' section for this in order to provoke the happenstance of 'man git clone' working is definitely wrong as far as the manual page hierarchy goes; it means that things like searching for just user commands (section 1) that contain some term will fail. Putting them in section '1git' (i.e. section 1 with a git "extension") would be more in line with how manual pages are typically laid out, and at least with man-db would not require any configuration file changes. However, I think both of these are suboptimal. Section extensions are typically used for things like functions or modules in other programming languages, or sometimes for cases where file names would otherwise clash. I'm not much of a git user myself, but I don't get the impression that most git users think of 'git clone' as analogous to a 'clone' command in a hypothetical 'git' programming language; it's closer to an ordinary user command.

The only case where I've seen subcommands given their own unprefixed manual pages with only the section extension to tell them apart is OpenSSL, with pages like x509(1ssl). IME, this is very confusing and not a good example to follow: firstly, you can't trivially find a list of all the subcommands with something like 'apropos openssl-'; secondly, it's easy to miss that you're dealing with an openssl subcommand unless you keep your eyes peeled.

Short of some mechanism for git to provide a plug-in to man to tell it where to find subpages (eek! potential overengineering alert!), a foo-bar lookup seems tolerable enough.

Would you like to suggest an option name for this, so that we can avoid unnecessary divergence? Perhaps something like --separate?

(I hope git@ will excuse the digression.)

Don't be confused by the name. Once upon a time the main feature of man-db was indeed its database; these days that's almost one of the least interesting features as far as I'm concerned (and I recommend GDBM for the database layer nowadays anyway, since Berkeley DB is overkill and has gone through an annoying number of disk format changes).

These days, much more relevant are things like the fact that man-db can handle encodings properly (both in manual pages and its own translated messages; *why* does man still use catgets?), and the effort put into process glue libraries so that it doesn't have to be audited carefully for unsafe shell code and so that it can be a lot more efficient when processing large numbers of manual pages (e.g. man -K).

Anyway, if you look at the history, what happened is that John W. Eaton wrote the original man way back in 1990/1 or so, then two different sets of people developed it in different directions into man and man-db. That was in the early 1990s when free software developers weren't communicating as often as they do now. Then, by the time it became obvious around 1995 that there'd been a fork, the two were already separate packages with different aims and it was now too hard for anyone to merge them. You could still see the common ancestry if you looked closely (indeed, you still can in places), but they're really much more like two completely separate implementations than a fork. It's a bit of a shame in some ways, but harmless enough.

Cheers,