Return-Path: owner-linux-activists@joker.cs.hut.fi Received: from joker.cs.hut.fi (root@joker.cs.hut.fi [130.233.40.32]) by keos.Helsinki.FI (8.6.4/H45) with SMTP id PAA19301 for ; Sat, 5 Feb 1994 15:53:59 +0200 Received: from joker.cs.hut.fi by niksula.hut.fi id <51137-3>; Sat, 5 Feb 1994 13:49:58 +0200 From: "Linux Activists" To: "Linux-Activists" Reply-To: "Linux-Activists" X-Note1: Remember to put 'X-Mn-Key: DOC' to your mail body or header Subject: Linux-Activists - DOC Channel digest. 94-1-5-2:13 X-Mn-Key: DOC Sender: owner-linux-activists@joker.cs.hut.fi Message-Id: <94Feb5.134958eet.51137-3@niksula.hut.fi> Date: Sat, 5 Feb 1994 13:49:52 +0200 Status: RO X-Status: Topics: LDP documentation and the FSF Re: LDP documentation and the FSF Re: LDP documentation and the FSF ---------------------------------------------------------------------- From: mdw@cs.cornell.edu (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: 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: greenfie@gauss.rutgers.edu (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 ***************** ------- .