Subject: Linux-Activists - DOC Channel digest. 94-1-5-2:13
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Sat, 5 Feb 1994 13:49:52 +0200

Topics:
	 LDP documentation and the FSF
	 Re: LDP documentation and the FSF 
	 Re: LDP documentation and the FSF

----------------------------------------------------------------------

From: [email-masked] (Matt Welsh)
Subject: LDP documentation and the FSF
Date: Sat, 5 Feb 1994 01:23:03 +0200

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

------------------------------

From: <[email-masked]>
Subject: Re: LDP documentation and the FSF 
Date: Sat, 5 Feb 1994 04:24:34 +0200

First, I won't write in texinfo.  html, maybe.

Matt Welsh writes:
>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

No.  Uh-uh.  Definitely not.  Linux and the HURD are about as
different as they come.  Essentially nothing in the KHG would apply to
the hurd.  Really.   The KHG is the one *essentially Linux* book in
our line-up.  The rest could be changed to document the hurd without
major surgery, to some extent.

Remember, though, that the hurd will add a *different way of thinking
about using a un*x system*, and that good documentation for it should
reflect that, and be written by people who understand it.

I can see that a "porting a Linux driver to the hurd" document could
be really useful...

>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.

Agreed.  I'd like this to change too.  However, I'm not going to sign
over documentation that I write the the FSF at this point.  I like
some of the differences between the LDP and the FSF.  We don't have to
be in the same boat to be on the same team.

>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'd vote for conversion tools, myself.  However, it's up to everyone
else what they want to do.

>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 agree, but I still argue that texinfo is a backwards,
not-terribly-friendly system.  I'd much rather see html, myself, with
a system for moving between formats as we were discussing earlier.

>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.

I guess I've always had the assumption that in the long run, that we
would be benefitting each other, but that we'd get more done by
focusing on our project, so that when the time comes, we have
something worth working with.  The time hasn't come for the KHG, and
really never will, but it probably will come sooner than later for the
NAG, and as the hurd comes out and gains in popularity, the I&GS will
be useful for the GNU project as well.

my \2

(\ is seen as the Yen sign in Japanese locales; I've been working very
hard on a japanese version of an application at work lately.)

michaelkjohnson

------------------------------

From: [email-masked] (Greenfie)
Subject: Re: LDP documentation and the FSF
Date: Sat, 5 Feb 1994 06:36:12 +0200

  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.

I agree. To the average user, Linux would not be much different than if I
took any Unix system and replaced all of the tools with their GNU
counterparts. (We'd still have a bunch of other tools, but if we include
all of free software, it would be fairly hard to tell Linux and a modified
Unix apart.) Then again, if I wrote a Mac-interface and replaced /etc/init
with it, we'd have a Mac.

[munch---printed manuals for DOS users]

   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.

Well, we have to remember that DOS folks aren't a bad community to aim
at---merely misguided. :^) Some of the FSF documentation is very good; an
example of this is the Emacs manual, IMHO. Some of the FSF documentation
could use some work. IMHO, an example of that is the GNU Calc manual, which
is very, very thick, fairly complete, but not the best of manuals.

   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.

Well, currently all the FSF documentation I've seen is geared towards a
specific product of the FSF---Emacs, or GCC, or the C library. The
integration of all of these tools is what the Linux operating system really
gets its character from.  I could read all of the FSF documentation and
still not understand how to accomplish I/O redirection, unless it's
documented in the bash manual, if such a thing exists.

[munch---documentation for only 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.

Well, I don't know if you've looked at the pre-alpha User's Guide... I
don't even know if it is out of incoming. (The file is named
"user-alpha-1.tar.gz" if you want it get it from incoming, BTW.) When
writing the manual, I was thinking about this. Why bother writing another
Unix manual? The world has a large number of Unix manuals, many of them
already bad---no need for me to contribute.  I've tried to customize it to
Linux, and since day one I've thought about the m68k port, too. Since it is
currently non-existant for people who need a Unix manual, I've mostly tried
structuring the manual so it doesn't imply Linux/i386. For instance, the
chapter "starting.tex" talks about how the average Intel box starts up, but
also what the Linux kernel does initially. It would be easy to add a m68k
part without changing most of the kernel part.

   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.

Then again, what would the "GNU User's Guide" be, besides a nice acronym.
(GUG?) From what little I know of the Hurd, it should be similiar in some
ways, but as different from Unix and Linux as Plan-9 is, and its manual
should reflect that. We could write a sequence of (the equivalent of) man
pages, and have a beautiful new edition of the classic AT&T manual, which
lives on in your /usr/man directory. But most people believe that the
manpages are insufficent to teach all of Unix---many like more examples and
a total problem solving approach.

[munch---TeXinfo, mostly]

This is a large problem. We encountered this problem when we first started
the project, and we'll continue to run into it. TeXinfo is a very nice
system, as is LaTeX. We decided on printed documentation, and we should
probably stick to it until we could decide on exactly what the new,
retargeted manuals should cover. Then we could decide whether it is
appropriate to make it in TeXinfo or not. Two formats of documentation
isn't the worst thing in the world.

[munch---more on retargetting]

Again, we need to know what we're writing before we decide what to call
them or where we could target them. The "kernel" of the Hurd and Linux are
dramtically different. Many books have been written about Mach, if you want
to be in the strict kernel part of the Hurd (modified Mach) but nothing on
the various servers. Linux is a more classical Unix design, which we have
Bach's nice book in addition to the KHG, which, as Michael Johnson pointed
out, will probably not be very applicable to the Hurd.

 I remain unconvinced that any of the other documents would be much more
relevant. If the Hurd lives up to being a new, different Unix, it won't be
installed the same, configured the same, and hopefully not used the same.
What good does a document on "ftp" do to an ideal Hurd system? What about
tar? Just as running programs remotely is a strange idea in a true
distributed system, why should our other 1970s ideas be equally applicable?

   Thoughts?

Naah. Well, maybe a few. First and foremost, define a purpose before
crossing the bridge. Find out what the Hurd will really be like from a
user's standpoint. (User is generalized to administrator here.) And see
above.

Larry Greenfield
greenfie(ld)@gauss.rutgers.edu
        ^^^^ for better mailing, delete these characters

------------------------------

End of DOC Digest
*****************
-------