man pages

[Panu Matilainen]

On Tue, 2006-06-06 at 00:24 -0600, Vincent Danen wrote:
> * Panu Matilainen <pmatilai at laiskiainen.org> [2006-06-05 17:56:34 +0300]:
> 
> > > I changed this to work the rest, so the look is more consistent and also
> > > cleaned up a few other things so you can scrap the ones I gave you
> > > before and use the attached instead.
> > > 
> > > All the manpages are done now.  =)
> > 
> > Hmm, I'm curious why did you remove the bolding on the command names in
> > all manuals but then made the arguments bold? Eg in apt-get.8:
> > install [pkg(s)]
> > ..where "install" is normal text and "[pkg(s)]" bold, the traditional
> > way is the other way around looking at similar cases from other programs
> > manuals.
> 
> It actually depends on which program you look at... =)  I looked at a
> few, and this felt more right to my eye on the case of conditional input
> is what's bolded... the primary command (upgrade, install, remove, etc.)
> is fairly static, so I left it as is (unbolded), but the "pkg(s)" or
> "regex" or whatnot is the actual user "input" (if you will) to the
> command, which is why I elected to bold it.  Initially it was all bold,
> which just felt wrong (there should be some separation).
> 
> Either way, doesn't matter.  I can invert things so that the command is
> bold and the arguments not (and let's not even think about command bold
> and argument underlined as that's just plain wrong).

Of course it's just a matter of taste and such, to me the arguments in
bold and command in normal text just feels backwards :) Even both in
non-bold would feel less weird I suppose.

> > Btw, "source" and "build-dep" commands always require an argument, and
> > additionally "update" can take arguments (what source lists to update). 
> > Oh well, we'll need to comb through the content with some extra care
> > anyway, there are quite a few things that are simply wrong (for apt-rpm)
> > in the Debian originals and then varying degrees of nonsensibility,
> > unclearness and whatnot. 
> 
> Yeah... I tried to clean up what I felt was wrong and knew what was
> right, but being not completely familiar with apt yet, I didn't want to
> start making guesses and messing things up more than they already were.
> My first/initial job was to get the basics done and in such a way that
> you could expand on them, add new stuff as you add the code, get other
> eyes looking at it who know apt better than I and can easily adjust the
> manpages to make the more accurate.

Sure - the above wasn't a criticism to you, just commenting on the
current state of the doc contents. We'll clean the stuff up
eventually :)

> 
> > So, I'd be happier if you could "fix" the boldness in commands eg 
> > .TP
> > upgrade
> > 
> > -->
> > .TP
> > \fBupgrade\fR
> 
> Well, if you would still like me to change them after you've read my
> explanation above, I'd be happy to do so.

Others don't seem to have opinion about this (or at least strong
opinions) so .. I still personally prefer the commands in bold and
arguments in normal text.

	- Panu -