the git-annex manpage is still pretty long. i wonder if work shouldn't be done to shorten it further.
what i'm thinking of is that this entry, for example, takes up three lines where it could take two, reducing the size by 30% since most commands have only one line explaining it:
* undo `[filename|directory] ...` Undo last change to a file or directory. See git-annex-undo(1) for details.
the git(1) manpage resolves this by putting the reference in the first line:
git-init(1)
Create an empty Git repository or reinitialize an existing one.
So i would think there are two options here:
- do like git, but preserving the usage:
* git-annex-undo(1) `[filename|directory]` Undo last change to a file or directory.
- Put the reference on the same line:
* undo `[filename|directory] ...` Undo last change to a file or directory. See git-annex-undo(1) for details.
Opinions? --anarcat
I don't like the "git-init" approach; git-init used to be in PATH, but no longer is, so the git man page is really a bit broken now. And of course, git-annex-undo is not actually a filename.
The second approach doesn't shorten it much and makes it harder to skip over the boilerplate in the links when reading since it's moved into the same paragraph as the description and will appear at differing positions depending on the description length.
I'd rather make the command name be a hyperlink. However, it's difficult to reconcile this with the limitations of man pages.
Maybe aim for something like this in the man page display, although I don't know if it can be accomplished:
right, that would be great. unfortunately, we use the
.IPmacro in the rendered groff output, which only has a leader and nothing on the right. i don't believe there's a macro that would answer the requirement, and i looked atman(7),mdoc(7),man-pages(7),groff_man(7),groff_mdoc(7)... which probably covers most of the man material i am aware of.there is the
\h'N'macro that allows movingNspaces to the right, but that wouldn't align the references, so we'd be better off with something like:... or something like that...
I'm not sure if it's clear enough that is a man-link and not some complexity added to the command line options.
Reviewing this, I think what we've shown is that there's no good way to shorten it, that does not have other tradeoffs!
And what's the real problem with the man page being a bit longer? Most users are probably not reading through all that, but are searching. And users who do read through it get to see around 5 commands summarized per page on their 25 line dumb terminal. Those of us with modern hardware can often see considerably more commands per page.