On 05/03/2012 05:41 PM, Meg McRoberts wrote:
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
Alas, the realities of life. But I have learned to accept the
inevitability of change. In 1973, I designed a computer system and
all peripherals for each of 2 test stations, and wrote all of the
software. Assembler. 60 instructions per page. Program listing
156 pages. Written using IBM punch cards after hand writing the
whole mess out on programming sheets. The machine had 32 Kbytes of
magnetic core memory.
Now I have an Ubuntu 11.4 Linux box with 64-bit, 3.3 Ghz Intel
Core I5 2500K processor (I don't need the I7 for what I do) with
8 Gb of RAM and two RAID1 (mirrored) disks. The processor has
1157 pins connecting it to the mother board!!!! I have no clue
how many billion transistors on the chip. The chips I tested
had up to 5000 transistors.
To buy that much disk storage and that much memory in the mid-1980s
would have cost between $600M and $800M! I built the entire thing,
processor and all for $800, US about 10 months ago. That bends
this old engineer's brain big-time.
I marvel at the skill and technology that makes this all possible.
Back in the 1980s, Bill Hewlett and Dave Packard were in an
annual Division Review here (Colorado) and were listening to some
engineers talk about a project they were working on. Bill or
Dave said to the other, "I think it's time to retire. I don't
even understand what these guys are talking about." I'm beginning
to feel the same way at times.
I wonder what it'll be like in another 35 years. I'm sure today's
engineers would have trouble imagining it.
Clarke
