Return-Path: mdw@cs.cornell.edu
Received: from kruuna.Helsinki.FI (kruuna.Helsinki.FI [128.214.4.112]) by keos.Helsinki.FI (8.6.4/H45) with ESMTP id BAA15789 for <wirzeniu@cs.Helsinki.FI>; Sat, 5 Feb 1994 01:24:09 +0200
Received: from thialfi.cs.cornell.edu (THIALFI.CS.CORNELL.EDU [128.84.254.220]) by kruuna.Helsinki.FI (8.6.5/8.6.5) with SMTP id BAA23519 for <wirzeniu@cc.helsinki.fi>; Sat, 5 Feb 1994 01:24:04 +0200
Received: from CLOYD.CS.CORNELL.EDU by thialfi.cs.cornell.edu (5.67/I-1.99E)
	id AA10999; Fri, 4 Feb 94 18:23:52 -0500
Received: from ROCKY.CS.CORNELL.EDU by cloyd.cs.cornell.edu (5.67/I-1.99D)
	id AA11070; Fri, 4 Feb 94 18:23:27 -0500
Message-Id: <9402042323.AA18577@rocky.cs.cornell.edu>
Received: by rocky.cs.cornell.edu (5.67/N-0.13)
	id AA18577; Fri, 4 Feb 94 18:23:17 -0500
Date: Fri, 4 Feb 1994 18:23:17 EST
X-Mn-Key: DOC
From: mdw@cs.cornell.edu (Matt Welsh)
X-Mailer: Mail User's Shell (7.2.0 10/31/90)
To: From:mdw@cs.cornell.edu (Matt Welsh), wirzeniu@cc.helsinki.fi (Lasu),
        okir@monad.swb.de (Olaf Kirch), johnsonm@calypso-2.oit.unc.edu,
        greenfie@gauss.rutgers.edu (Larry Greenfield),
        kfogel@occs.cs.oberlin.edu (Karl Fogel)
Subject: LDP documentation and the FSF
Cc: From:mdw@cs.cornell.edu (Matt Welsh), linux-activists@joker.cs.hut.fi,
        mdw@cs.cornell.edu
Status: RO
X-Status: 

I just got off the phone with Richard Stallman, discussing issues relevant
to Linux documentation with the upcoming FSF/GNU Linux CD-ROM, which will
contain the Debian distribution---as well as issues about Linux docs in
general. The major idea that got across was the fact that Linux really
is a "GNU" system---it's built up from GNU software, (excepting of course
the kernel), but supported and developed by a group of people that consider
themselves not part of the GNU project as a whole. Now that Linux is maturing
to the point where integration with GNU is a serious option, I think that
we should rethink some of the direction of the LDP.

The LDP was founded primarily to produce *printed* manuals for Linux
alone. And, at least in the case of the I&GS, manuals for non-UNIX users,
or users coming from an MS-DOS/PC background. That is why printed manuals
and plain ASCII are so important---we can't expect MS-DOS users to have
access to Info readers and the like.

However, Linux is now moving to the point where not only old MS-DOS users
are the primary audience. The GNU folks are aiming towards the UNIX
community at large---not to old PC users. If we'd like to sync our
efforts with the FSF and GNU, in terms of documentation, a few (small,
hopefully) changes should be made.

First of all, we never wanted to conflict or duplicate the efforts of the
GNU documentation. However, RMS wasn't even aware of the LDP until two
days ago. So far, I don't think that much effort has been duplicated---in
fact, we have been keeping GNU documentation as well as man pages in mind
when writing the LDP manuals.

The idea here is simple: We've been thinking of Linux in terms of an
isolated operating system, instead of an *implementation* of a complete
working system, which partially relies on GNU software. The only thing
that *really* makes Linux different than other UNIX implementations is
the kernel. So why have we (the Linux community, and the LDP specifically)
segregated ourselves from the FSF and GNU project? We should be working
together and synchronizing our efforts, I think. Our attitude so far
has been that of a UNIX software vendor, developing and supporting our
own product, withouth paying attention to the larger need, the need
for documentation that extends beyond just Linux. 

For example---why write a Linux Users' Guide? What's different between
using Linux and using any other UNIX system that relies heavily on GNU
software? Hardware-specific issues aside, not many. If we are going to
move towards generality---and we are already getting a taste of that from
the m68k port of Linux---I think that LDP docs should be aiming towards a
more general, ultimate goal---seeing Linux as a certain implementation of
UNIX and GNU, but the documentation can be much broader than that.

I want to get comments and feedback about this idea. I'm not talking about
changing much about the LDP as a whole, right now, but instead trying to
work more closely with the FSF and helping each other. Linux-specific books
such as the I&GS, KHG, and (perhaps) the NAG make sense to continue working
on, but in the long run, can't we instead write a "GNU User's Guide" and
"GNU System Administrator's Guide"? Yes, Linux specifics are tangled up
in those two projects quite deeply, but the mess can be untangled.

In order to sync up with the rest of the GNU docs, it would be nice
to have texinfo. Now, I have the same qualms about texinfo as everyone
else---but from speaking with RMS I understand the philosophy behind it
much better. The problem is that not many of the node, menu, and
section-ordering facilities in texinfo can or should be automated. Why?
Because not only do you need section headings, but you need node headings,
which are meant to be quite terse---one or two words. And you need the
node and menu entries to be orthogonal enough so that they can be easily
selected (e.g., it doesn't make sense for all menu entries to begin with
the same word, such as "Using..."). RMS's take is that the system
needs to be as flexible as possible, but he does agree that SOME of these
things can be automated---but even with that there are things that you
need to do by hand to make it work right. For example, I'd like to
write a utility to take all of my "node" commands and produce menus,
which I can then edit by hand to make them orthogonal and take care of
special cases. (There might be an Emacs function for this already).
We could also do something that would take "chapter" and "section" commands
and make @node commands out of them, but RMS points out that you don't
always want the nodes to correspond to a chapter-section-subsection
ordering. So writing some of these automated conversion tools (like
Olaf's texify, LaTeX->texinfo processor) will get us at least halfway
there, but not all the way.

What do you think of this possible shift in direction? I still want the
LDP manuals to be available to UNIX newcomers---especially the I&GS---but
that needn't stop us from integrating somewhat with the GNU project.
If we think far, far down the road, I think it would be the best thing
if our manuals were applicable to software other than Linux---for example,
the KHG might be a start for a general UNIX hacker's guide, and the
NAG is a great start for a general GNU Network Admin Guide. This is
assuming, of course, that either a) Linux is ported to many other
systems (not likely) or that b) Hurd will one day be available. I'm not
saying that Hurd will ever replace Linux, but if it does, I think
that our work can be applicable there. Let's not let our efforts go
to waste. The GNU project needs documentation, and we can provide
that, but we're not very much in sync with what they're doing.

To clairfy one thing: For the FSF/Linux CD-ROM release, LaTeX documentation
will be acceptible, of course. The GNU folks aren't exclusively accepting
texinfo docs. But in the long run, we'll either want to move completely
to texinfo (with a set of tools to make life easier for the writer) or
expand on Olaf's LoTeX or texify tools for converting LaTeX to texinfo
for use in GNU releases.

I think that the documentation work that we have done can expand far beyond
Linux, if we allow it to do so. It just takes some generalization and
thinking in other directions. (After all, it makes much more sense, in the
free software world, to work on hypertext, online-browsable documents,
rather than manuals, which not many people can print for themselves!)
I'm not suggesting that we do anything to dismantle Linux or the LDP or
any of that---but at the very least we can keep the mindset that we *can*
contribute to the FSF, and in the end, I think we'll need to do so.

Thoughts?

mdw
