Return-Path: wirzeniu From: wirzeniu@klaava (Lars Wirzenius) Date: Tue, 5 Jan 1993 03:13:16 EET X-Mailer: Mail User's Shell (7.1.1 5/02/90) To: linux-activists@niksula.hut.fi Subject: Re: doc.status Status: RO X-Status: X-Mn-Key: doc doc.status -*-Outline-*- Status of the Linux Documentation Project Lars Wirzenius Version: $Id: doc.status,v 1.2 1993/01/05 02:58:08 liw Released liw $ E-mail to lars.wirzenius@helsinki.fi. * Ramblings A few comments on things that have cropped up on the DOC channel. Sorry about not responding to individual comments; I _hate_ the digesting. ** Book printing Some time ago arl suggested that cheap printers in China (I think it was) could be used to provide inexpensive hardcopies. The quality isn't going to be that great, but at least it is printed and bound (therefore probably often more convenient than a large binder), and should be cheaper than printing out everything on a laser; I think he's said something along the lines of about 5 dollars for a book of 500 pages to be possible. I'm not aware of the details, but the price price seems good. For that price, it might even be possible to print a new version every year or even every six months (we might not even have to wait until the whole doc project is finished until the first printing). What do you all think? Does anybody know of cheap printers? ** Version control Version control is unpleasant, but important, even necessary. I propose the following (natural) scheme: Each independent part of the documentation (see below for my standard list) has its own version number, and that part is released and its version number issued by its maintainer/coordinator. The whole documentation set also has its own version number, issued by the project coordinator (me). Basically, the version number of the whole set identifies a set of documents and their version number that form a coherent, integrated whole. The way I envision it, each independent document is written and maintained independently, but with feedback going from everybody to everybody so that all parts fit together. When the coordinator of a document so wishes, he puts out an "alpha" version for others to comment. This version gets a unique version number. He gets feedback, edits, and puts out a new version. This is iterated as necessary. When a version is considered "finished", it is released "for real". When enough "for real" versions of various documents are out, a "for real" version of the whole set is released, and given a version number. ** Copyrights Linux is copyrighted with the GNU Public License, as are most of the standard utilities, the compiler, and so on. Some stuff is from BSD, and uses their copyright. Other stuff has its own copyright. All in all, it is a bit of a mess, but everything still seems to be freely usable, modifyable, distributable (even for cost), and generally aren't troublesome for most people. [No flames about how the GPL is a pain in the ass for people who want to do commercial stuff.] The documentation set should, nay must also be just about as free. It would be nice if as much as possible used the same copyright, to reduce the legal complexities. I'm personally leaning towards something along the lines of what the UUCP document draft in nic.funet.fi:.../ALPHA/doc-project uses, that is the GPL with the relaxation that hardcopy distributors do not have to provide the source code. Or perhaps something like the BSD copyrights. This needs to be discussed. Another legalistic question is who should own the copyrights. Should we have one copyright holder for the whole set (except for stuff that is already copyrighted, for example existing man pages), or should each author own what he produced? I prefer the latter, and I doubt that there is much disagreement. ** Typesetting There was some discussion about supporting both letter and A4 size paper. This is important, but I think there are more sizes than that: for example, it might be convenient to use paper that is about half of those sizes since the book or binder (or whatever) is not as big. Also, if somebody wants to use ghostview to look at the documentation, it's probably nice to not have the whole screen taken over by it. However, I always thought that LaTeX took care of most of the details of adapting to different paper sizes: you just have a setting in one of the .sty (or whatever) files that specifies the paper size (explicitly or implicitly), and the formatting algorithm takes care of the rest. Well, I know there is more to it than that, some stuff has to be typeset and laid out by hand, but I always thought that was only a small part of it. If I'm right, then the important thing is for each writer to make certain that he doesn't make the document difficult to format for different paper sizes by embedding knowledge or assumptions to his LaTeX source code (or whatever he uses). Perhaps some of you who have more experience with typesetting (hopefully we have or can reach such people :) could comment on this? For whatever it's worth, I personally prefer the more restrictive and "calm" style as is used for example in K&R to the "hey-this-printer-has-*34*-different-fonts" style that has been used in at least some of Borland's manuals (I remember a paragraph where about every third or fourth word was in a different font than those surrounding it). * doc-project directories at nic.funet.fi Arl has kindly created two directories for the Doc project on nic.funet.fi. The first is /pub/OS/Linux/ALPHA/doc-project. This is meant as a place where unreleased stuff can be shared among the people who do the work. For example, when somebody has written something and wants people to comment on it, and feels that it is too big to send via mail, it can be uploaded to .../ALPHA/incoming, and arl will move it to .../ALPHA/doc-project (send him a note about it so that he is certain to know what it is and where it should go). I repeat, .../ALPHA/doc-project is not meant for public consumption. Don't encourage people not willing to work on the stuff there to grab things from there. The other directory, .../doc/doc-project, on the other hand, is explicitly meant for everybody. Stuff that is finished goes there. Actually, it doesn't even has to be finished: if the author thinks it is good enough to throw on unsuspecting people, it should be put to .../doc/doc-project. As far as I know, none of these directories are mirrored elsewhere. * Short outline of Linux docs ** Getting Started The be-all and end-all of Linux installation instructions. Covers installation and has brief tutorials on using and administering Linux. This book is all that a novice should have to read in order to get going. ** User's Guide The full story of how to use Linux, except for individual program usage. (That is, the UG covers usage in general, not specific program in particular. The Reference Manual is for that.) ** Administrator's Guide How to keep Linux up and running after it has been first installed. Installing new software, doing backups, etc. ** Programmer's Guide How to write programs under Linux. Not urgent. ** Local Guide This is mostly for systems with many users. Similar to the LaTeX Local Guide. Summarizes differences between the real system and the "generic" systems described in the rest of the documentation. Things like lists of hardware, local hacks, installed software, etc. ** FAQ This one everybody is hopefully at least vaguely familiar with. Idea: In addition to the Linux FAQ, include other FAQs as well, like those for Unix, C, PC hardware, UUCP, news, etc. ** Reference Manual Manuals for programs and so on. Man pages, texinfo documents, etc. ** Linux Kernel Hackers' Guide Kernel documentation. Essentially tells how the kernel works so that hackers can hack it easier. ** Linux Readings Miscellaneous other Linux related documents that don't fit into other books. Things like my interview with Linus in Linux News #3, a history of Linux (everybody urge Linus to write it, my urgings aren't working :), Who's Who of Linux, a Linux bibliography. ** Global Index An index that covers all other manuals, to make it easier to find things that are covered by many manuals. * Format of documents It seems that LaTeX is what most people favor. However, each writer should use whatever format he finds comfortable, although using the same thing everybody else uses creates less confusion. The important thing is not to flame about the format, but to get things done. Once we have good text in some format, we can convert it. Michael Johnson has a set of typesetting guidelines that writers are encouraged to follow. * Slaves (a.k.a. volunteers) The e-mail address and full name are followed by a list of the tasks the person has done, is doing, is committed to do, and/or has expressed an interest in doing. Status information is indicated in brackets. If somebody is mentioned as a coordinator for a document, that usually means they will probably write much of it as well. Except that I'm not going to write most the doc project as a whole :). For those parts that do not have their own coordinator, I will serve as one, but this probably means only that I'm looking for volunteers to take over that part of the job. ** lars.wirzenius@helsinki.fi (Lars Wirzenius) Coordinator of the doc project in whole. Intro to sysadmin in Getting Started [outlining]. Administrator's Guide [outlining]. ** mdw@tc.cornell.edu (Matt Welsh) Coordinator of Getting Started [outlining/writing]. INFO-SHEET [posting regularly]. ** greenfie@gauss.rutgers.edu (Larry Greenfield) Coordinator of User's Guide. Intro to using Linux in Getting Started. ** johnsonm@stolaf.edu (Michael K Johnson) Editor and co-author of the Kernel Hackers' Guide [working on it]. Style guide and LaTeX .sty file for typesetting the docs [working on it]. ** dminer@cs.umr.edu (Dan Miner) Co-ordinator of the Kernel Hackers' Guide [working on it]. ** nick@nsis.cl.nec.co.jp (Gavin Thomas Nicol) Coordinator of the Reference Manual. Man page to Texinfo conversion program. ** leblanc@mcc.ac.uk (Owen LeBlanc) Proofreading (spelling and grammar checking). [offering services] ** okir@mathematik.th-darmstadt.de "I could write some basic stuff ... on setting up uucp and/or mail". [offering services] ** kfogel@occs.cs.oberlin.edu (Karl Fogel) Intro to Unix for ex-DOS users (to be part of Getting Started). ** pdcawley@cix.compulink.co.uk (Piers Cawley) Proof reader [offering services]. .