Re: [Groff] Is there a good man page style guide somewhere?

[Clarke Echols]

> H'm... the use of Courier rather than bold is certainly a departure.
> It certainly is commonly used for "literal" text, so it's hardly
> a bad thing, but I think it would be a bit discordant in if I were
> to use it in just one place.

The reason I implemented Courier macros was because the entire computer
industry was moving toward Courier for literals being typed in by the user
with italics to represent variables or user-selected values such as in:

.CI cp " filename"

where double quotes are required to force space between the command "cp"
and the argument "filename".

The bold-for-commands was an albatross from AT&T, but there was more to the
problem than that.  In the SYNOPSIS, literals (commands, function names,
option letters, etc.) were in bold, yet command names in the DESCRIPTION text
were in italics, for cryin' out loud, and not only that, but if the literal
was at the start of a sentence, the first letter was capitalized.

Look at the non-UNIX-Guru user who looks at such a screwed up manpage,
and you see a user who is totally confused.  The top line across the top
of the page says "CP(1)" in the upper left- and right-hand corners. The
SYNOPSIS says:

cp file1 file2

where cp is in bold and file1 and file2 are italics.  Then he reads the
description where it says:

Cp copies a file to another file...

where Cp is in italics.  I recall a customer inquiry where the guy said
"I typed in "Cp file1 file2" and I got an error message that said, "Command
not found".  So what does the user do?  Type "cp", "Cp", or "CP"?

At that time, cp, ln, and mv were all on the same man page, and the
DESCRIPTION line said:

cp, mv, ln - copy, move, or link files

Run that through a permuted index generator (ptx), and you get a hideous
mess.  Look in that mess for "rename a file", and you get the rename(2)
system call.  Now how is a user supposed to figure out that you use the
mv command to rename a file at the keyboard from that mess?

With that in mind, take a look at the URL:

http://docs.hp.com/hpux/onlinedocs/B2355-90128/B2355-90128.html

Click on Section 1: Commands, then "C" to get a list of entries, then
select cp(1) to see what I did with the original mess from AT&T.  You
can also look at ln(1) and mv(1) to see how I split them out.

These are in HTML, not in the original troff, but they were generated from
my original text, and show my approach to writing man pages.

These pages are from the HP-UX 10.0 Reference.  The last version I worked
on was for HP-UX 9.0, but the bulk of that manual represents my work.

The point behind my thinking is simple:  man pages are written for USERS,
not to satisfy the preferences of software developers.  I started a real
war at HP when I abandoned the "old way", but management backed my 100%
because I was moving to the same conventions that were ALREADY fully
adopted by the rest of the industry for PCs, and other computer documents.
The time is long past to carry baggage from AT&T conventions when the
conventions are not consistent with current industry practice.

> >> Should there be a space (\ , or something different?) between the option
> >> brackets and the option inside?  Again, groff(1) includes these spaces,
> >> but man(1) and man(7) omit them.
> >
> > \(space) is too wide.  That's why I used \| instead.
> 
> I agree.  But groff(1) takes the opposite view.  It's confusing to the
> poor newbie.

Manual pages are not written so the source-file text is not confusing to the
newbie man page writer -- they're written so they look good to the end
user.  At least that was my paradigm because I was the only one responsible
for the source files and I was paid by money coming from customers who needed
something they could read and understand clearly with a reasonably artistic
visual presentation.

So the big question:  Why did I retire 2 years ago?  Because a certain
manager at HP didn't "have the time and resources" to deliver the entire
HP-UX man page content in troff AND HTML so I could link HTML manpages into
my online help that was being delivered in HTML at HP-UX 11.0, and without
HTML manpages I had no way to link reference materials into my help system
for sam(1M) system administration software.  It was a job that I could have
done in less than a week -- they already had 95% or more of the software
needed to do the job, but they didn't want me doing it (corporate turf
battles).  When I hammered the manager responsible about needing a change
in point of view (I'd been asking for HTML manpages for over 3 years, and
did a feasability demo in 1994) that focused on delivering what customers
need and want instead of complaining about not having time and resources,
I was confronted with that manager's desire to "punish" me for being a poor
team player.  What I don't understand is they didn't even realize they had
already created HTML man pages and posted them to the external web site
noted by the above URL PRIOR to my insistence that they change their
approach.

Retirement is GREAT!  No boss for over 2 years!

If you want to see the work I did on configurable kernel parameters
documentation, take a gander at:

http://docs.hp.com/hpux/onlinedocs/os/KCparams.OverviewAll.html

(This information was being discarded by the creators of the printed manuals
which would have been disastrous, so I resurrected the information, placed
it inside of the SAM online help system, then put it on the corporate
customer-accessible site for further accessibility.  The info is very
HP-UX specific, but demonstrates good documentation structure and content
from a usefulness and usability point of view.)