Re: [Groff] Eric Raymond on groff and TeX

[Meg McRoberts]

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
>
>
>