man pages

[Vincent Danen]

* Panu Matilainen <pmatilai at laiskiainen.org> [2006-06-09 22:42:37 -0700]:

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

lol... never even bothered to look at the "basic" system command
manpages... oh well.

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

Yeah, I don't pay too much attention either...  as long as things are
consistent within a manpage, it's fairly easy to figure out the intended
use of whatever style is used.

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

Yup, it is.  Ok, I'll go ahead with the above stylistic changes and send
you a new tarball today to get this finally finished and dealt with.

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

Hopefully not... I'd rather not keep redoing stylistic changes and
concentrate on more meaningful things... =)

-- 
{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/20060610/8caf214d/attachment-0003.pgp>