[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Groff] Eric Raymond on groff and TeX
From: |
Meg McRoberts |
Subject: |
Re: [Groff] Eric Raymond on groff and TeX |
Date: |
Thu, 3 May 2012 16:41:44 -0700 (PDT) |
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
>
>
>
- Re: [Groff] Eric Raymond on groff and TeX, (continued)
- Re: [Groff] Eric Raymond on groff and TeX, Eric S. Raymond, 2012/05/03
- Re: [Groff] Eric Raymond on groff and TeX, Meg McRoberts, 2012/05/03
- Re: [Groff] Eric Raymond on groff and TeX, Clarke Echols, 2012/05/03
- Re: [Groff] Eric Raymond on groff and TeX,
Meg McRoberts <=
- Re: [Groff] Eric Raymond on groff and TeX, Clarke Echols, 2012/05/03
- Re: [Groff] Eric Raymond on groff and TeX, Steve Izma, 2012/05/05
- Re: [Groff] Eric Raymond on groff and TeX, James K. Lowden, 2012/05/07
- Re: [Groff] Eric Raymond on groff and TeX, Steve Izma, 2012/05/08
- Re: [Groff] Eric Raymond on groff and TeX, Pierre-Jean, 2012/05/08
- Re: [Groff] Eric Raymond on groff and TeX, James K. Lowden, 2012/05/09
Re: [Groff] Eric Raymond on groff and TeX, James K. Lowden, 2012/05/03
Re: [Groff] Eric Raymond on groff and TeX, Larry Kollar, 2012/05/08