Re: [Groff] The case against the case against .EX/.EE & .DS/.DE

[Clarke Echols]

Meg McRoberts wrote:

> > What else?
>
> Personally, what I really miss in the -man macros are the list macros from
> mm -- .VL, BL, .DL, et cetera.  .IP and .TP do work but are a bit awkward.
> I've not been able to get the old kludge for bullet lists to work:
>
> .IP "\(bu" 4

I don't understand the need for the .IP construct you show.  I have
always liked:

.RS    \" indent for bullet list
.TP 3  \" set bullet offset
\(bu   \" or other character such as dash or square
paragraph text here
.IP
second paragraph under same bullet
.TP
\(bu
next paragraph
...
.RE     \" restore indent

This was my standard method for handling bullet lists in the HP-UX
manpages when I was the "bricktator" in charge of the HP-UX Reference
from 1989 through 1992 (we called the manual "the brick" for obvious
reasons when you picked the 3-volume set up, and "tator" was derived
from my autocratic style of keeping the troops (software engineers)
in line -- especially the ones who occasionally disagreed with me
about grammar and sticking to the AT&T style.  :-)  The one that
really started the fur flying was when I started a sentence with
"cp" instead of "Cp" because any knot-head knows sentences start
with a capital letter, right?  True except for "legal terms"
(Chicago Manual of Style), so I treated commands as terms because
they had to be lowercase.  Users were very confused by CP in the
heading at the top of the page (uppercase Roman typeface), cp
in the SYNOPSIS (in bold), and "Cp" in the text (in italics).  What
a mess.  So the first thing I did was force *ALL* instances of a
command to be printed in upper/lowercase exactly as used in actual
system operation -- no exceptions nowhere nohow (and that's how the
title "bricktator" was born).  I have never used MS or MM macros; I
usually write my own for running text or published novels, business
documents, letters, etc.

I have always found the AT&T man macros quite adequate for my needs,
other than for specific typesetting features such as bleed tabs on
the page to show position in a section (A through Z tabs moving down
along the edge of the page toward the bottom), adding .CI, .IC, etc.
to support "computer" (Courier) fonts in syntax/usage sections such
as in the EXAMPLES and SYNOPSIS and a few other minor adaptations.

I went on to other assignments (online help for system administration
software, commonly called SAM) until I left in 1999, and DocBook was
just coming to be with the advancement of the OSF and their endorsement
of DocBook as the medium of choice, so I cannot claim any expertise
in that regard.

On thing I did do in 1989 was convert ALL HP-UX manpages to use
ONLY man macros, eliminating all instances of \fR \fB, etc. and using
\f1, \f2, \f3, and \f4 in the actual man macros so I could use the
.fp requests to specify the typeface (there was no such thing as a
specifier for "font family" back then).  Thus anyone working on the
files would see only .B, .I, .C, .IR, .BR, .IB, .IC, .CI, etc. for the
four fonts that were used throughout the printed manual.  Where
necessary to prevent white space, \c line endings were used, but not
particularly often because they were rarely needed.

In about 1993/94, I did a proof of concept using sed iteratively with
some other shell-script stuff (that I don't remember anymore) to
convert man page files to HTML, including inserting hyperlinks for
cross-references (such as in SEE ALSO).  It was about 95% accurate.
But not long after that, apparently the HP-UX reference pages were
converted to an SGML form (DocBook?) and troff was produced from
those files for typesetting and use by nroff and the man command.

From 1993 through 1998, I was using hyperlinks from the SAM online
help to access nroff'd manpages through a proprietary HP help
system, but in 1998/99 when I converted SAM help to HTML, the
persons responsible refused to commit any effort to adding code to
the manpage builder I wrote in 1989 to spit out all of the manpages
in HTML and deliver them side-by-side with the troff/nroff files that
were delivered with the system for use by the man command (HTML and
web browsers had no means for accessing formatted nroff files or the
system man command, especially using any information in the $PATH
environment variable).  I could have done the job in a week but
they wouldn't let me, presumably because I might expose them again
(I kept the manpages up to date myself for four years from 1989
through 1992, working only 30 hours per week and was never late.
They replaced me with 10 full-time engineers in 1993 who were
incapable of meeting schedules working a combined 400 hours per
week, so I made a public issue of it inside the company). For
3-1/2 years I asked them to provide that capability but they
couldn't find "the resources" to do the job.  I found the whole
situation so politically motivated and ridiculous that I confronted
the manager in charge of that activity.  When she complained that I
was being a "poor team player", I decided to leave the company --
especially because HP had a new CEO and I sensed the company was
about to hit the skids and come crashing down (which it came very
close to doing).  It took three full-time engineers to replace me
after I left, and I don't miss the job at all.

Sorry about the rant, but I'm a bit sensitive about manpages and I
have a low tolerance for corporate nonsense.  Manpages are not hard
to master if one simply understands why they are structured the way
they are and why it is important to keep the basic style intact
so experienced users can quickly work their way through them.

Until this discussion, I had never see .EX/.EE and .DS/.DE.  I use
Cygwin on my Win98 machine but I don't see a man page defining the
macros anywhere in the manpages, so I have no clue what they do.
I tend to resist the addition of other macros when existing macros
cover the subject and keep it simple.

Clarke