Re: Is there a need for a hard copy OpenBSD documentation project?

[Luke Seubert <lseubert@radix.net>]

chuck yerkes on 09/05/2000 1:12 PM scribbled:

> XML VS. 'ROFF?
> The compelling argument would be what?  The macros to convert
> all present 'roff docs to XML/SGML will be written by whom?
> 
Fredrik Henbjork and Andrew Shugg, if my memory serves correctly, have
tentatively volunteered to work on scripts for conversion to XML, etc.


> IS THERE A LOT OF VALUE IN PRINTING MANPAGES?
> Well, I own, and rarely reference, the OReilly 4.4BSD books
> which are pretty much that, for 4.4 lite.  I find that read
> once, I rarely need to see them again.  Driving past a heavily
> logged area of the mountains of california this weekend, and
> passing a large paper mill's stink doesn't motivate me more
> to print out 40 inches of paper for occasional possible
> reference, especially when I can print what I need on those
> rare occasions that I need to.
> 
You and others have raised this point.  Do we really want to waster yet more
paper.  One proposal is to duplicate all the documents we produce in
electronic format, XML, Postscript, and pdf, and put them all onto CD.
Those who want and need paper docs can get them.  Those who want electronic
docs can get those separately without cutting down trees, and only print out
those selected docs as needed.

Also, there is a proposal from Al Lipscomb to create a sort of introductory
workbook/tutorial on the web for OpenBSD and Unix newbies.  This would
complement the manual project quite well, and likewise save trees.

> On the other hand, filling in what's MISSING, the glue between
> the man pages requires good writing and solid OS skills.  The
> FreeBSD handbook covers it pretty well (bottom line, BSD is
> BSD for 98% of the user interface part).  And is out of date
> with FreeBSD 4.x after being on paper for a year.
> 
Agreed.  This would be a better project if it included more than just the
man, faq, and sysadmin documents.  That is part of the goal right now,
although just what all this encompasses is still a bit fuzzy.

> Perhaps some basic, detailed install instructions for various
> platforms (on RISK stations, I could give a rats ass about
> BIOS settings and multiple OS on one disk installs).  Cover
> disklabel (in words and examples), cover typical installs,
> and so forth.  Make it a 4-5 page setup manual.  Go through
> user setup and references to the (now 3rd edition) Nemeth/Hein/et
> al System Admin Handbook for a bonus 10 page setup.  Just
> don't be passing me books that expire in 6 months.
> 
Excellent suggestions.  I would like to see detailed install instructions
for every hardware platform, and definitely the all important afterboot man
page included in a very complete and easy to understand installation
section.

> Bottom line:  If you've got stuff to contribute, put it up.  PDF
> is nice for a (mostly) unalterable final form that can be printed
> without worrying about fonts/graphics issues.  PS is fine as long
> as you ONLY use fonts that everyone will have.  rtf may be a good
> vendor vague spec.  Whatever your religion, please off up some
> samples.  If it's just printing man pages, well, figure out costs,
> take some orders and print them for those that pony up some cash.
> Hell, charge a little more and pass it back to the OS fund.
>
I guess at this point, I am the guy who would be actually printing this
stuff.  My plan would be to sell the manuals at cost to either Theo
directly, or the Calgary computer store so that the profits would be
redirected back into OpenBSD.

-- 

Luke Seubert


4 out of 5 politicians prefer unarmed peasants.
The fifth one prefers voluptuous redheads.