Newsgroups: comp.os.linux
Path: sparky!uunet!ukma!darwin.sura.net!zaphod.mps.ohio-state.edu!rpi!batcomputer!theory.TC.Cornell.EDU!mdw
From: m...@theory.TC.Cornell.EDU (Matt Welsh)
Subject: Linux Documentation Project
Message-ID: <1992Nov13.030905.3415@tc.cornell.edu>
Sender: n...@tc.cornell.edu
Nntp-Posting-Host: theory.tc.cornell.edu
Organization: Cornell Theory Center
Date: Fri, 13 Nov 1992 03:09:05 GMT
Lines: 57
I'm sending this out to the newsgroup as well, to snag anyone who's
interested and not already on the mailing-list.
The following is a summary of the status of the Documentation work being
done on the DOC channel of the linux-activi...@niksula.hut.fi mailing list.
See the FAQ for instructions on how to join the list. :)
The Linux Documentation Project is currently underway. We are working in
concert to produce the "standard"/"official" set of Linux documentation
as per Lars Wirzenius' outline for the project, discussed on the DOC
channel of linux-activists.
The documentation will basically consist of a set of "Books" or individual
documents, each covering a different topic. The main documents in the series
that this point are the Installation and Setup Guide, the User's Manual,
and the System Administrator's Guide. Other documents, such as the Kernel
Hacker's Guide and a yet-to-be-written Programmer's Guide, will also be
incorporated into the project.
The DOC channel of linux-activists serves as the discussion group for this
project. We will all work together to write, edit, and review the documentation
associated with this project. Moreover, Lars Wirzenius
(wirzen...@cc.helsinki.fi)has been "appointed" as the main "coordinator" of
this project, and will help to mae sure that the individual efforts are in
synch and that everyone's happy.
In addition, each individual document in the series has its own coordinator.
The coordinator for the User's Guide is currently Larry Greenfield
(green...@guass.rutgers.edu) and the coordinator for the Installation and
Getting Started Guide is myself (m...@tc.cornell.edu). Other documents have
their own respective coordinators as well, but they will all be released
through one effort, with Lars overseeing. This organization is in an effort
to bring together and coordinate a standard, reliable, and up-to-date set of
Linux documentation.
The documentation I'm referring to here aren't man pages and other on-line
docs; that's a different ballgame altogether. However, we're hoping that the
docs produced through the Doc Project will be converted to online format
(the standard format will be LaTeX, which filters are being written for to
convert to other formats if needed).
Basically, anyone who wants to help write or work with this project in
any way is welcome to join the DOC channel of linux-activists. If you'd
like to contribute to a particular document, mail that document's coordinator.
We're always looking for more help, so don't be shy. :) It's a very open
project.
Lars should be sending out a summary copy of his Doc Project Outline, along
with the coordinators for the various sections, sometime soon (right, Lasu? :)).
Please feel free to ask any questions or make comments on the above. That's
just a summary of what's going on now.
Thanks,
mdw
m...@tc.cornell.edu
Newsgroups: comp.os.linux
Path: sparky!uunet!caen!batcomputer!theory.TC.Cornell.EDU!mdw
From: m...@theory.TC.Cornell.EDU (Matt Welsh)
Subject: DOC Channel Update
Message-ID: <1992Dec3.175932.7333@tc.cornell.edu>
Sender: n...@tc.cornell.edu
Nntp-Posting-Host: theory.tc.cornell.edu
Organization: Linux 'R' Us, Documentation Department
Date: Thu, 3 Dec 1992 17:59:32 GMT
Lines: 134
The following is a (long) message I sent out to the DOC channel of the
linux-activists mailing list last night, to keep the Linux world in general
caught up with what's going on in documentation. Please make comments!
None of this is set in stone, so if there's something you want to see in
the Linux documentation, please send suggestions or comments to me (or
even better, join the DOC channel so we can all see them :) ).
To join the DOC channel of the mailing list, send mail to the address
linux-activists-requ...@niksula.hut.fi with the line
X-Mn-Admin: join DOC
as the first line in your message body.
We want to hear your feedback!
mdw
-----
Hello everyone. This note is going out to keep you all 'up-to-date' on the
doings of the DOC channel, since we've been pretty quiet recently.
Essentially, we're all off hiding in our respective corners, trying to
churn something out. I imagine that it may be a while before we have anything
complete and proofread enough to 'distribute'. However, here's the status
of the 'Doc Project' as it now stands:
The main project is the 4 manuals. These will be the Installation/Setup/Getting
Started manual (coordinated by myself), the User's Manual (coordinated by
Larry Greenfield), the System Administrator's Guide (coordinated by Lars
Wirzenius), and the Kernel Hacker's Guide (Michael K. Johnson?). What we're
aiming for is to write and maintain the canonical set of Linux documents--
books that are well-written, well-formatted, and well-edited, and complete.
Since the Linux world is getting ready to expand far beyond the horizon of
the net (where anyone can get help via news or e-mail) with the advent of
CD-ROM releases and so on, I think we need good, complete manuals, and soon.
We've all pretty much agreed to format the manuals in LaTeX, using the
standards sent out by Michael K. Johnson. He's produced a LaTeX style format
that should be used for the manuals, and written a conventions page that
details how to use the macros. It's very simple, and they should be adhered
to if possible. LaTeX/TeX under Linux supports them quite well, if you don't
have access to LaTeX elsewhere. :)
Filters are being written to convert the LaTeX source to texinfo format.
Don't worry: These manuals will be available in one form or another in
online format.
Man pages and other documentation are also being discussed on this channel.
We'll talk more about that later, I suppose...
I don't know about the status of all of these manuals. Lars Wirzenius
(wirze...@cc.helsinki.fi) is 'in charge' of this Doc project as far as
coordinating everyone, making sure the manuals all fit together, don't have
conflicting information, and so on. Once we have something written, we'll
probably send it out over this channel and have everyone give feedback,
revisions, proofreading notes, and so on. Lars will also make sure the
manuals don't conflict in any way.
Lars sent out an overall outline of the project a few weeks ago. Maybe you
should send it out again? For my part of the project (the Install/Setup
Manual), I plan to post an outline sometime soon. I will need writers--
I have deferred some of you who've volunteered because I still need to get
the structure of the book worked out. Once that's done, I'll send out an
outline and ask for people to volunteer for sections that I'm not writing
myself. Then we'll "get crackin'". I plan to work heavily on the manual
during the winter break.
The Install/Setup manual will be the be-all-end-all of Linux installation
and getting started documents, as much as such a thing can exist in the
Linux world. It won't replace documents like the FAQ (which are composed of
many somewhat unrelated important pieces of information). The intended
audience is both for the complete UNIX newbie, as well as for seasoned
UNIX hacks who have just never installed Linux before. It will be VERY
complete, and I plan to maintain it, and keep up with changes in the Linux
world. A very general outline will look something like:
-- Introduction (What is UNIX? What is Linux?)
-- How do I get Linux (intro to the various releases, how to get them
from various sources)?
-- How do I install Linux (parallel of above; cover installation for
each release)?
-- Setting up the system; beginner's tutorial in UNIX
-- Beginner's Tutorial in System Administration (just the basics, may
serve as an intro to the System Admin guide... written by Lars).
-- How to upgrade/install new software, libs, GCC, kernel, and so on.
(*** This is technically 'Installation', but I imagine we should put this
in the system admin guide, no?).
-- Common problems, troubleshooting, and so on.
-- Appendices: other UNIX books to check out, introduction to FTP (for those
who will get Linux over the net), other rudimentary info.
A lot of this will be obvious to people who have worked with UNIX before, and
more 'advanced' topics will be seperated from the beginner's stuff. I don't
want UNIX gurus skipping through the entire manual, however. I may provide,
as an appendix, some kind of summary for those familiar with UNIX and the net
(for those who can read a 3-5 page doc on where to get Linux and how to
install it). This may be implemented as a seperate short document,
putting most of the info from section III of the FAQ into a more readable
format. You may have noticed that my instructions on how to install Linux
in the FAQ are rather sketchy: "To get Linux, FTP the images, rawrite them
to disks, and boot the boot disk. Voila!" I need to flesh this out a little
in another kind of document... things to be covered include making filesystems
and partitions, making a kernel floppy, etc... anything that a UNIX hack can
already do, but needs specific instructions on how to do under Linux.
The intended audience for the System Admin guide and User's Guide should
probably be more towards those who have done at least a little work with
UNIX before. I don't know if the writers of those manuals want to cover
all of the basics or if they only want to talk about the Linux-specifics.
They could probably compromise: write a good introduction, give some basic
information, then point to other well-written UNIX books for further starter's
hints, allowing the rest of the manual to be geared towards a detailed guide.
In short, if you want to write for the Linux Doc Project [tm], wait for
one of us to post an outline of what we're working on. Or, get in touch
with any of us directly. My address is m...@tc.cornell.edu. Other addresses of
note are:
Lars Wirzenius: wirze...@cc.helsinki.fi
Larry Greenfield: green...@gauss.rutgers.edu
Michael Johnson: johns...@stolaf.edu
Apologies to those I have missed, who have expressed an interest in
coordinating something. Please correct me.
I'll be posting a 'sign-up sheet' soon for the Install manual, once I
get the full outline done. Please let me know if you have any suggestions or
comments on the above!
I apologize that this is so long. In the time it took to write this, I could
have finished a chapter or two. Please make comments or suggestions, if you
made it all the way through. Thanks!
mdw
--
Matt Welsh m...@tc.cornell.edu Cornell Theory Center
"We're going away now. I fed the cat."
Newsgroups: comp.os.linux.announce
Path: sparky!uunet!usc!rpi!batcomputer!theory.TC.Cornell.EDU!mdw
From: lars.wirzen...@helsinki.fi (Lars Wirzenius)
Subject: Linux Documentation Project status
Message-ID: <1993Jan24.010627.365@tc.cornell.edu>
Followup-To: comp.os.linux
Originator: m...@theory.TC.Cornell.EDU
Keywords: documentation status
Sender: n...@tc.cornell.edu
Nntp-Posting-Host: theory.tc.cornell.edu
Organization: University of Helsinki
Date: Sun, 24 Jan 1993 01:06:27 GMT
Approved: linux-annou...@tc.cornell.edu (Matt Welsh)
Lines: 140
Here is a short summary of the state of the Linux Documentation
Project. Contact lars.wirzen...@helsinki.fi for more information.
About the time table: don't hold your breath. People are working on
it, but it takes some time. If you want more speed, you can help by
writing something.
* 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.
** Glossary
Definitions of Unix/Linux related words.
** 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.
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.
Note: this version only has the coordinators. I left out
people volunteering to do proof reading and such.
** lars.wirzen...@helsinki.fi (Lars Wirzenius)
Coordinator of the doc project in whole.
Intro to sysadmin in Getting Started
Administrator's Guide
** m...@tc.cornell.edu (Matt Welsh)
Coordinator of Getting Started
INFO-SHEET
** green...@gauss.rutgers.edu (Larry Greenfield)
Coordinator of User's Guide.
Tutorial on using Linux in Getting Started.
** johns...@stolaf.edu (Michael K Johnson)
Editor and co-author of the Kernel Hackers' Guide
Style guide and LaTeX .sty file for typesetting the docs
** dmi...@cs.umr.edu (Dan Miner)
Co-ordinator of the Kernel Hackers' Guide
** n...@nsis.cl.nec.co.jp (Gavin Thomas Nicol)
Coordinator of the Reference Manual.
Man page to Texinfo conversion program.
--
Lars.Wirzen...@helsinki.fi (finger wirze...@klaava.helsinki.fi)
MS-DOS, you can't live with it, you can live without it.
--
Send submissions for comp.os.linux.announce to: linux-annou...@tc.cornell.edu
Newsgroups: comp.os.linux,comp.os.linux.announce,news.answers
Path: sparky!uunet!nwnexus!ole!quick!sumax.seattleu.edu!news.u.washington.edu!usenet.coe.montana.edu!caen!batcomputer!theory.TC.Cornell.EDU!mdw
From: m...@theory.TC.Cornell.EDU (Matt Welsh)
Subject: [comp.os.linux.announce] Welcome to comp.os.linux.announce!
Message-ID: <1993Jan28.035352.24818@tc.cornell.edu>
Followup-To: poster
Keywords: intro announce
Sender: n...@tc.cornell.edu
Nntp-Posting-Host: theory.tc.cornell.edu
Organization: Jim's Burger Hut
Date: Thu, 28 Jan 1993 03:53:52 GMT
Approved: linux-annou...@tc.cornell.edu (Matt Welsh)
Lines: 52
Archive-name: linux-faq/announce/intro
Last-modified: 1 Jan 93
WELCOME TO COMP.OS.LINUX.ANNOUNCE!
Comp.os.linux.announce (which has a nifty acronym: "c.o.l.a") is a
newsgroup for announcements, important information, and software patches
for the Linux operating system, a free UNIX clone for i386 and i486 based
machines. This group is a moderated companion to comp.os.linux, which is
the group for discussions, questions, and general information about Linux.
This group has been created to provide a seperate group in which to crosspost
important information about Linux, since these postings are often lost in
the heavy bandwidth of comp.os.linux. In general, postings to c.o.l.a will
also be posted to comp.os.linux, for those who receive c.o.l over the FidoNet
gateway and other non-USENET sources.
The moderators for this group are myself (Matt Welsh, m...@tc.cornell.edu) and
Lars Wirzenius (wirze...@cc.helsinki.fi). We will be sharing the moderator
duty, and backing each other up to make sure that postings to this group will
be approved as soon as possible after they're submitted.
Submissions to this group should be mailed to the address:
linux-annou...@tc.cornell.edu
If you have any problems or questions about c.o.l.a, please send mail to the
moderators at
linux-announce-requ...@tc.cornell.edu
Or simply mail us directly.
A seperate posting details the guidelines for submitting to this group.
I plan to approve just about anything that's posted to this group, except for
questions or discussions about Linux. So, please, post away. :)
Plans are in the works for having this group archived at one or more of
the Linux FTP sites; more on that later.
There is a mailing list gateway of the comp.os.linux.announce newsgroup;
to join, send mail to
linux-activists-requ...@niksula.hut.fi
With the line
X-Mn-Admin: join ANNOUNCE
at the top of the body (not in the subject). Approved postings to c.o.l.a
will automatically be mailed to this mailing list channel.
Matt Welsh
Comp.os.linux.announce moderator
Submissions to: linux-annou...@tc.cornell.edu
--
Matt Welsh, m...@tc.cornell.edu
"Donuts. Is there anything they can't do?"
Newsgroups: comp.os.linux,comp.os.linux.announce
Path: sparky!uunet!portal!sdd.hp.com!caen!batcomputer!db.TC.Cornell.EDU!mdw
From: m...@db.TC.Cornell.EDU (Matt Welsh)
Subject: Linux Documentation Project
Message-ID: <1993Feb15.012844.19514@tc.cornell.edu>
Followup-To: comp.os.linux
Keywords: Doc project
Sender: n...@tc.cornell.edu
Nntp-Posting-Host: db.tc.cornell.edu
Organization: Linux. It's not just for breakfast anymore.
Date: Mon, 15 Feb 1993 01:28:44 GMT
Approved: linux-annou...@tc.cornell.edu (Matt Welsh)
Lines: 123
A couple of weeks ago, Lars decided to hand over coordination of the
"Linux Documentation Project" (actually the DOC channel of the mailing list).
And I, being the brainless gnat that I am, volunteered to take it over
for him. I suppose I have time for this, I guess we'll see. :)
Lars has asked me to make an announcement to this effect, and to let you all
know of the status of the Doc Project. So, as it stands now, I'm the
coordinator of the Doc Project, so if you have questions, comments, or want
to volunteer, you can mail me.
For the most part we're just waiting for the writers to finish their
respective docs, so that all of us on the Doc Project can proofread and
edit them into submission.
As always, to join the DOC channel of the mailing list, just send mail to
linux-activists-requ...@niksula.hut.fi
with the line
X-Mn-Admin: join DOC
at the top of the body (not the subject).
Printed below is an edited version of a "Doc project update" that I sent
out a little while ago. If you already know about the Doc Project then
you can hit "n" to skip this bit. :)
Cheers,
mdw
This note is going out to keep the masses informed of the current status
of the Linux Doc project, as we've all been pretty quiet recently.
Essentially, we're all off hiding in our respective corners, trying to
churn something out. I imagine that it may be a while before we have anything
complete and proofread enough to 'distribute'. However, here's the status
of the 'Doc Project' as it now stands:
The main project is the 4 manuals. These will be the Installation/Setup/Getting
Started manual (coordinated by myself), the User's Manual (coordinated by
Larry Greenfield), the System Administrator's Guide (coordinated by Lars
Wirzenius), and the Kernel Hacker's Guide (Michael K. Johnson?). What we're
aiming for is to write and maintain the canonical set of Linux documents--
books that are well-written, well-formatted, and well-edited, and complete.
Since the Linux world is getting ready to expand far beyond the horizon of
the net (where anyone can get help via news or e-mail) with the advent of
CD-ROM releases and so on, I think we need good, complete manuals, and soon.
We've all pretty much agreed to format the manuals in LaTeX, using the
standards sent out by Michael K. Johnson. He's produced a LaTeX style format
that should be used for the manuals, and written a conventions page that
details how to use the macros. It's very simple, and they should be adhered
to if possible. LaTeX/TeX under Linux supports them quite well, if you don't
have access to LaTeX elsewhere. :)
Filters are being written to convert the LaTeX source to texinfo format.
Don't worry: These manuals will be available in one form or another in
online format.
Man pages and other documentation are also being discussed on this channel.
We'll talk more about that later, I suppose...
I don't know about the status of all of these manuals. I'm waiting for
progress reports to filter in from the other writers, but from what I can tell
we're all happily writing along. The coordinator of the Doc Project as a whole
is myself (m...@tc.cornell.edu), and I'm going to (attempt to) make sure that
all of the manuals fit together, don't have conflicting information, don't
have teriblle mispelings [sic], and so on.
Once the individual writers have their alpha versions ready, anyone
on the DOC project will be able to edit/proof them so we can have them
ready for general distribution as soon as possible. The DOC channel will
be used for this purpose as well.
As far as the Linux Installation/Setup/Getting Started manual is concerned,
it will be the be-all-end-all of Linux installation and getting started
documents, as much as such a thing can exist in the Linux world. It won'
t replace documents like the FAQ (which are composed of many somewhat
unrelated important pieces of information). The intended audience is both for
the complete UNIX newbie, as well as for seasoned UNIX hacks who have just
never installed Linux before. It will be VERY complete, and I plan to maintain
it, and keep up with changes in the Linux world. A very general outline will
look something like:
-- Introduction (What is UNIX? What is Linux?)
-- How do I get Linux (intro to the various releases, how to get them
from various sources)?
-- How do I install Linux (parallel of above; cover installation for
each release)?
-- Setting up the system; beginner's tutorial in UNIX
-- Beginner's Tutorial in System Administration (just the basics, may
serve as an intro to the System Admin guide... written by Lars).
-- How to upgrade/install new software, libs, GCC, kernel, and so on.
(*** This is technically 'Installation', but I imagine we should put this
in the system admin guide, no?).
-- Common problems, troubleshooting, and so on.
-- Appendices: other UNIX books to check out, introduction to FTP (for those
who will get Linux over the net), other rudimentary info.
A lot of this will be obvious to people who have worked with UNIX before, and
more 'advanced' topics will be seperated from the beginner's stuff. I don't
want UNIX gurus skipping through the entire manual, however. I may provide,
as an appendix, some kind of summary for those familiar with UNIX and the net
(for those who can read a 3-5 page doc on where to get Linux and how to
install it). This may be implemented as a seperate short document,
putting most of the info from section III of the FAQ into a more readable
format. You may have noticed that my instructions on how to install Linux
in the FAQ are rather sketchy: "To get Linux, FTP the images, rawrite them
to disks, and boot the boot disk. Voila!" I need to flesh this out a little
in another kind of document... things to be covered include making filesystems
and partitions, making a kernel floppy, etc... anything that a UNIX hack can
already do, but needs specific instructions on how to do under Linux.
The intended audience for the System Admin guide and User's Guide should
probably be more towards those who have done at least a little work with
UNIX before. I don't know if the writers of those manuals want to cover
all of the basics or if they only want to talk about the Linux-specifics.
They could probably compromise: write a good introduction, give some basic
information, then point to other well-written UNIX books for further starter's
hints, allowing the rest of the manual to be geared towards a detailed guide.
I apologize that this is so long. In the time it took to write this, I could
have finished a chapter or two. Please make comments or suggestions, if you
made it all the way through. Thanks!
--
Matt Welsh, m...@tc.cornell.edu
"What are you doing, Dave?"
|