Prime Time Freeware Manual: the Dossier Series

doom writes "There seems to be some interest just now in technical books based on freely licensed content, so I thought I would discuss the Dossier series from Rich Morin's Prime Time Freeware project." Doom has provided an overview of this series; read on below to find out for yourself why he says man pages and other free documentation are worth paying for in dead-tree format.

Prime Time Freeware Manual: the Dossier Series
author	(Various)
pages	(Various)
publisher	Dossier/Prime Time Freeware
rating	8
reviewer	doom
ISBN	(N/A)
summary	Free documentation worth paying for.

You're all of course aware that there's a huge quantity of excellent technical material on-line about the free/open software that you use ... but how much of it have you actually read? Computer's being what they are -- noisy glowing bulky contraptions with awkward physical controls and displays with a resolution a fraction of paper publications -- most of us aren't inclined to read long works on line. So the next step is where you resolve to do printouts of some of the manuals... and then you discover how long they really are. Many a project can fill multiple looseleaf binders with a single-sided printout of its docs. But if you spend about half a day on it you can probably figure out how to get a nice double-sided printout in a smallish typeface and squeeze it all into a single looseleaf binder... which turns out to *still* be too bulky to want to carry around with you. RTFM is easier said ...

The solution to this is of course professionally printed editions of the manuals. These have been easy to get for GNU software for some time -- the GNU Project standardized on documentation in 'texinfo' format which they use to generate both their online documentation and a very good series of books.

But all that is free is not GNU, and filling that gap is one of the goals of the Dossier series, which uses some semi-automated procedures to generate high-quality, up-to-date hardcopy-on-demand publication.

Thus far they've got books out on the following topics (available on-line through the BSD Mall):

• C, etc.: Essential Tools
• Email: Exim 3
• Email: Mail and Sendmail
• File Systems: FreeBSD
• File Systems: RedHat
• Kernel: FreeBSD
• PostgreSQL: Programming
• PostgreSQL: Reference Manual
• PostgreSQL: Use and Administration
• Processes: FreeBSD
• Processes: RedHat
• Python: Library Reference
• Python: Miscellanea
• Security: Local System
• Security: Remote Access
• Text Processing: Essential Tools
• User Commands: FreeBSD
• User Commands: RedHat

Some of the prices might seem a little high for works based on free content (usually $30 to $35 per volume), but on the other hand these are for small press runs without much in the way of economies of scale going for them. And it certainly beats messing with doing print-outs yourself. (Though if you want to go that route, Dossier can help take the sting out of that process: they offer online access to PDF versions of these works, which is much more inexpensive than paying them to ship you bound volumes.)

When I first heard about Prime Time Freeware/Dossier, I immediately ordered the Postgresql documentation, a set which fills three volumes. At that time the only Postgresql book out was Bruce Momjian's which only covered up to version 7.0. At the speed the postgresql development team was working, having docs more than one release behind was definitely a problem (outer joins weren't even supported in 7.0!). I really appreciated having some books I could flip through that discussed the actual state of the software (and man, there are some weird features in there I didn't know about ... graphical data types so that you can try and use postgres as a backend to a CAD system?).

Next I started looking at the volume on "Text" (now renamed "Text Processing" ... which is a shame, in my opinion. I thought it was really funny putting "Text" on the same level as "C" and "Python"). This is a book I would have liked to have some years ago when I needed to understand troff/nroff for man-page hacking (the only time I ever bought one of those 4-inch-wide junk books the 80s were buried under was to get a copy of "UNIX UNLEASHED" because it had a table of *roff commands ... it still bugs me that I had to do that).

One of the things that struck me immediately about this "Text" volume though, was that there were some utilities discussed here that I'd never heard of before, e.g. a2ps which has some decent features for formatting docs for postscript printers. I'd never run across it before, in part because it wasn't installed by default on my RedHat 7.x box. It's a pretty funky command that does a bunch of things automagically that are sometimes hard to predict, but if you need printouts of some docs, I recommend giving a2ps a try for double-column duplex output -- but only if you can't get them from some place like Dossier (yet).

Rich Morin has been working on the problem of making it easier for users of open systems to get information about them for some time, hence The Meta Project, which thus far has resulted in "Meta Demo," aka the FreeBSD Browser. The Dossier series is a spin-off of this research in documenting open systems... check-out the Meta Project sometime. (I'd like to see that system browser extended to cover Linux, myself).

---

Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.

Excuse me?

[gazbo]

How is this a book review? Saying that there is a series of books available doth not a review make.

Split Opinion

[wzm]

I'm of two minds about printed documentation. On more consumer oriented platforms, such as the Mac OS, and Windows, I've never had need to touch the printed stuff, and the built in help is rarely of use. With *NIX machines, I've always wanted to get full printed documentation, but once I get ahold of if for the stuff I'm using, I never pull it out. Man pages and online documentation are just to convenient.

I feel as though having printed documentation ought to help, but it doesnt. Do people who learned computing through batch systems find things to be different? I know that old DEC junkies typically have a few bookcases of documentation, is that because they learned the systems that way (and find it useful), or just because they are pack rats?

Re:dead tree is bad

[stratjakt]

It's more environmentally sound to produce paper than microchips. And paper books dont consume the ~150watts my PC and CRT do.

The paper industry by and large farms the trees they use, and ever larger portions are recycled. It really is time to update the Greenpeace pamphlets.

Re:dead tree is bad

[Mike Rucker]

The problem is that the electronic formats are not always as useful as the paper format. Electronic documentation describing how to fix your computer won't do you much good if your computer is malfunctioning.

ROI

[Anonymous Coward]

I asked 3 of my profs in business school if there was any way to make money from Open source except support. They all said NO! If book sales are significant, it might be another big incentive for software developers to join the cause.

ciao

Some nice things about paper

[phorm]

To name a few nice things about documentation on paper:

You can highlight it (a big plug)

You can tag/mark important pages

You can read the paper and the screen (fullscreen) at the same time without switching TTY's

You can have multiple pages open at ones (if looseleaf) and sometimes switching between is easier as well

You can take then with you when not at a PC

If you're in the loo and run out of TP... well...

The problem is the CONTENT

[Anonymous Coward]

Most *NIX man pages have a horrible interface and are poorly written. They do not have a tutorial style, and generally show you the commands and a brief definition, but nothing more.

But whether that's online or on paper, it's still going to suck. It's even worse on paper because it's not hyperlinked and has no search capability.

I have read manuals that were completely on the computer and also printed out. I shipped the printed copies back to my parent's home to occupy my old room; I exclusively use the online stuff. It's better, it's faster, and it's exactly the same well-written stuff.

Printing books is a step backwards. It's destructive to the environment. What is really needed? A) Better writers B) a devotion and committment to explaining concepts more thoroughly C) more examples.

Re:The problem is the CONTENT

[AJWM]

they do not have a tutorial style, and generally show you the commands and a brief definition

Uh, that's all they (man pages) are supposed to have. Back in the dawn of time, or at least of Unix, the documentation consisted of two "volumes" (several inches thick each if you printed it all out on looseleaf paper to put in a binder). Volume 1 consisted of man pages, with the different sections being numbered as we know the numbering today. Volume 2 -- rarely seen anymore -- consisted of white papers, users guides and other detailed documentation for the commands that weren't obvious from the man page. (For example, cp only needs a man page, even with all the bells and whistles added since the early days. Something like troff or yacc needs a bit more -- and you'd find that bit more in Volume 2.)

Online documentation (speaking in general here) is great (searchable, hyperlinks, etc) when you're looking for something specific. Paper documentation is wonderful when you just want to browse (in the old fashioned sense) to discover stuff you didn't know you needed -- especially if you want to do that in places where a computer isn't convenient.