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