That brings back memories of 1989 when I battled HP's Unix labs. The
HP-UX reference was called "the brick" due to size and density, and I
became known as "the bricktator" thanks to my monarchical management
style. But I forced it through, and commands were in COURIER, not bold,
and variable arguments were italic. I eliminated all \f... strings and
converted the entire mess to man macros. It took about 10 minutes to do
after I spent 4 hours writing a shell script that ran vi
non-interctively from a commands file, then sent the buffer through sed
to do what vi couldn't do.
The result was beautiful!
Ah yes, many memories! And remember the hue and cry when we had to
split the man pages into two books!
And my detractors were silenced. :-) Including the ones who insisted
if a command name started a sentence, it had to have an initial cap, as
in "Cp copies files..." instead of "cp copies files..." Or worse, they
wanted "The cp utility copies files..."
Ah yes, and these battles rage on... Actually, I confess that,
outside of the
reference pages, I've warmed to the "The cp command copies files..."
syntax.
If you're on a page titled "cp(1)" it's reasonable to assume that
you can
figure out it's a command, but if you're in the middle of a manual
and the
sentence is "xxx defines <blah>", it is nice to give a little
mind-jogger as
to whether xxx is a command, a file, a struct, a database table, etc...
The problem is formal policies shouldn't over-rule good sense, however
uncommon it may be.
Except that "good sense" means different things to different people, and
when doing a large documentation set, many different people may be
contributing.
Which is not to say that I'm a stickler for style guides, especially
in a time when
the user's "complete" doc set includes all sorts of different books
and online files
from all sorts of different sources.
I know of no really practical methods of getting copy that looks good in
print, on screen (via nroff), AND online in XHTML, HTML, or whatever
else is wanted. And I'm not convinced obtaining such makes a lot of
sense. Identify the audience, then deliver it in a way that is easy
to use, easy to read, with writing and layout that is easy to read
and understand.
I've come to feel differently about this, at least for product
documentation. I had
to abandon the feeling that I had complete control of the aesthetics
of the output
a while ago -- as soon as the text is released in an online form,
you lose control of
it -- at the very least, users can resize at will -- so I now
advocate that one needs to
create documents that look good enough in a variety of formats. It's
more than
just print, screen, and online. For example, one might excerpt large
chunks of a
document onto slides for a training session. How nice to be able to
just create a
new style sheet but use the same raw content file -- so when the
material is updated,
you only have to update it in one place!
It also frustrates me when the only way to get "printed
documentation" is to print off
pages of HTML, which generally doesn't play out very well in print.
I'm noticing more
and more doc sets where one can view the online HTML doc but click a
button to
get a PDF file that has the same information in a similar (albeit
not identical) format
for printing.
If one is, for example, writing a novel or poetry, these practical
concerns are much
less compelling...
meg