Re: [Groff] Draft paper: "Writing Effective Manual Pages"

[Clarke Echols]

It was 20 years ago, so my memory was a bit fuzzy.  I just looked at
the last edition of the HP-UX Reference I published in late 1992.

I discovered that I did, indeed use Courier Bold because the typeface
looked so thin and anemic adjacent to New Century Schoolbook, and I
dropped the size by one point because it had a taller x-height,
making it look too heavy next to the regular New Century Schoolbook.
The smaller size had a much nicer overall balance without losing
readability.

In making those decisions, I had one big advantage.  Every HP-UX
system went out with its own man macros, so I didn't need to concern
myself with transportability between operating systems.  Having
wrested autocratic authority to run the reference manual "my way"
also simplified things as well. :-)  [We called the manual "The
Brick" due to its density and size, and I was known as the
"bricktator", thanks to my management style in running a one-man
show while interacting with R&D engineers all over the world.]

A few "AT&T purists" objected, but my main focus was to make the
typography resemble then-current publishing practice for the computer
industry at that time, and I was recognized by management as fully
competent to make those decisions.  Of course, I selected others of
competent opinion to make sure I wasn't overlooking something
important.

Courier bold is definitely the way to go for a "C" font.

It seems to me that adding the "C" font to the man macros would be
reasonable if they went out with groff or if groff over-wrote the
macros used by the man command when it is installed.  It would
be better if they were in all versions of the man macros, even when
groff isn't installed.

That would work if the .C macros specified in man pages would default
to B font if no C macros are included in the man macros, but I think
a call to a non-existent macro is treated as a comment and the text
would get dropped.  That's not good.

That means I don't have a good suggestion beyond adding the C macros
to each page, which would work, but definitely isn't the right way to
do things.

Clarke

Tadziu Hoffmann wrote:
> I don't necessarily agree with the "1 point smaller" (and I'd use
> Courier Bold), but otherwise Clarke's suggestion is definitely
> the best way to go, namely to use macros "C", "CR", CB", "CI",
> etc. in analogy to the "B" and "I" (and combinations) macros
> already available in man.  Unfortunately, this only works if you
> know that the target system has these macros available.  A more
> portable solution would be to define the macros in the manpage,
> but that kind of defeats the purpose of having a standard "man"
> macro package.  I would definitely avoid explicitly doing the markup
> with "\f" escapes, this makes the manpage code far less readable.
> (Better include the macros, then.)
>
> (As an added bonus, these macros can map hyphen and minus both
> to minus, making everything appear "ASCII-teletype-like", so you
> wouldn't have to worry about typing "\-" vs. "-".)
>
> If this is not an option, I'd side with Ted, namely to use a
> format such as "\-\-dump-strings".  Using "minus" as option-prefix
> instead of hyphen is good, because some programs use options
> prefixed by "plus", and this looks bad if paired with "hyphen"
> instead of "minus".  (I don't think the two minus signs are
> too close together, but that's obviously a matter of taste.
> But it would look better in a monospaced font, I'd think.)