man pages

[Panu Matilainen]

On Fri, 9 Jun 2006, Vincent Danen wrote:

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

Check out any manpage from coreutils, for example cp, mv and ls. 
That's my idea of "traditional" but ...

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

...you're right. For example I've certainly looked at gpg manual often 
enough yet I've never noticed it looked any different than others. Point 
taken, I've simply never paid any attention to the details until now 
apparently. :)

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

Ok.

>>> 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 {}?

Optional stuff has always been in [] everywhere I remember seeing, 
required varies.. I'm personally used to <> around required things.. or 
thought I was - now that I look for it I can't find that used anywhere. Oh 
well :) I'd say optional things in [] and required in normal text, which I 
think your updates already have basically.

Anyway, your list above for the style looks good to me. Well, 
'commands and command line switches in bold" but the cli switches are 
already in bold in your manuals so that's taken care of anyway. Just as 
long as we're consistent in our own manuals, comparing to others seems to 
be pretty futile :)

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

Right. Anybody else have opinions on how the matter?

 	- Panu -