man pages

[Vincent Danen]

* Panu Matilainen <pmatilai at laiskiainen.org> [2006-06-09 10:39:36 -0700]:

> >>> A new apt-get.8 is attached.  The rest are ok?
> >>
> >> That looks ok, now just convert the rest to this style :) One minor thing
> >> though - I wonder does it make sense to have those []'s around command
> >> arguments in bold either?
> >
> > Oh come on... don't nitpick... =)  Besides, it looks better visually (it
> > adds some "reverse highlighting" to the user-input stuff (ie. "pkg(s)").
> 
> The point is not so much to nitpick, it's more about following tradition I 
> suppose. Typically the brackets and such are not bolded but the command / 
> option is, and the user input part is underlined.

I have *never* seen user-input underlined.  At least I don't think I
have.  I often see user-input bolded (or inverse-bold as is the case
with the apt-get manpage now), but never underlined.  Underlined is
usually reserved for filenames and paths.

Anyways, doing some looking here and there isn't much of a constant
here.  For instance:

man gpg -- user-input in bold, commands unbolded (including the []'s)
man httpd -- commands in bold, input underlined (well, i see it now!);
  stupidly enough, the paths are bolded
man vim -- nothing is bolded (commands nor user input)
man kadmind -- commands in bold, input underlined
man launchd -- commands in bold, files not underlined

So it's pretty much an every-man-for-himself thing, I think, as long as
it remains constant within the manpage itself.

Personally, I've always done my manpages the way the gpg folks have done
theirs: commands in normal text, input bolded, configuration directives
and paths underlined.

I think you'd be hard-pressed to say there is a "typical" manpage out
there.  =)

> > The rest need to be done the same way?  Hmm... will have to check
> > that... I thought that apt-get.8 was the exception.
> 
> All the other commands have similar internal commands as well, I don't see 
> why apt-get would be exceptional in any way.

No no... I meant in terms of how I had formatted them, but looking at
apt-cache.8 I see that the commands are normal and the input is bolded
(the inverse of what you want).

> > I'll try to look at that and finish them today.
> 
> Excellent. Let's get the first update in, then we can start nitpicking for 
> real ;)

Very true, but I think we should define what will be consistent across
the manpages, then I'll fix them up and you can do the initial import.
What I'd like to do is this (and I'll wait for some consensus or nod
before doing it to save myself changing things yet again):

- commands in bold
- user input in normal text
- files and paths underlined
- configuration directives underlined
- required directives in normal text (ie. "install pkg")
- optional directives enclosed in [] (ie. "install pkg [pkg(s)]")

So, for instance, the synopsis at the top of apt-get.8 would look like:

apt-get [options] [-o config=string] [-c=cfgfile] command [pkg(s)]

Or maybe required directives should be in [] and optional in {}?

Not sure which would look best.  If we can settle on this, I'll make the
required changes.  The required/optional directives would only be used
for the SYNOPSIS and COMMANDS sections (ie. when describing "update" or
"install pkg(s)", etc.).

-- 
{FEE30AD4 : 7F6C A60C 06C2 4811 FA1C  A2BC 2EBC 5E32 FEE3 0AD4}
mysql> SELECT * FROM users WHERE clue > 0;
Empty set (0.00sec)
:: Annvix - Secure Linux Server: http://annvix.org/ ::
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 186 bytes
Desc: not available
URL: <http://lists.laiskiainen.org/pipermail/apt-rpm-laiskiainen.org/attachments/20060609/22587fed/attachment-0003.pgp>