Subject: Linux-Activists - DOC Channel digest. 94-1-6-17:42
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Mon, 7 Feb 1994 00:20:23 +0200

Topics:
	 Re: Linux-Activists - DOC Channel digest. 94-1-5-19:35
	 Re: Linux-Activists - DOC Channel digest. 94-1-5-13:25
	 Re: texinfo vs ...

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

From: [email-masked] (C. S. Hendrix)
Subject: Re: Linux-Activists - DOC Channel digest. 94-1-5-19:35
Date: Sun, 6 Feb 1994 19:20:17 +0200

> This would be an execellent idea in many ways, because it makes it easier
> to split up the documentation. (Say an "X Manual" and a "Shell Manual", or
> whatever.) The downside is, of course, you need more unwieldy hardcopy
> books. (Intro to Emacs? Nope... You get the whole manual...) This has to be
> done very carefully.

No need for a beginner's guide to things like Emacs when there are plenty
of inexpensive books from O'Reilly.  The ORA book on Emacs is better
than the GNU doc and easier for newbies.  Of course, it might be nice to
have a free Emacs manual of the same type as the ORA book.

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

-- 
csh
---------------------------------------------------------------------------
[email-masked] (UUCP)         | Cy486/40 LinuxOS system
[email-masked] (Internet)          | Christopher Newport University

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

From: [email-masked] (C. S. Hendrix)
Subject: Re: Linux-Activists - DOC Channel digest. 94-1-5-13:25
Date: Sun, 6 Feb 1994 19:37:35 +0200

 
> From: [email-masked] (Matt Welsh)
> Subject: Re: LDP documentation and the FSF
> Date: Sat, 5 Feb 1994 08:51:51 +0200
> 
> 
> ""Michael K. Johnson"" <[email-masked]> writes:
> > 
> > First, I won't write in texinfo.  html, maybe.
> 
> I'm not asking you to. I just want to be open-minded about the
> possibilities. Using texinfo just might give us many advantages
> which outweigh the initial trouble of using it.

What advantages are those?  I used Texinfo for a long time before
finally getting tired of the hassle.  LaTeX is easier, more powerful,
and does a LOT better job.  The *ONLY* thing Texinfo is good for is
making a Texinfo manual.  Texinfo seemed interesting at first but in
actual use I found a well indexed manual to be faster. 

> That's great. I'm not asking to get rid of Linux-specific docs. I'm
> asking to generalize where we can.

This seems good, given that Linux is mostly SysV/POSIX and it's 
utilities are available for most UNIX.  But there are things about
the Linux group that is different from GNU (i.e. better) that I
like.  I think it's good to have things separated for awhile.  

> > I agree, but I still argue that texinfo is a backwards,
> > not-terribly-friendly system.
> 
> Funny---that's what they used to say about UNIX. :)

But at least UNIX works good.  Texinfo is not an idea manual system.
It's just widely used because there is no alternative.

To explain what I mean about Linux stuff being better than GNU:  I find
that the LDP manuals are FAR better than most GNU stuff, especially for
beginners.  Everyone did a real good job on the LDP stuff.  GNU manuals
usually are a terrible read and appear almost deliberately hard to
understand.  Of course, if this will help GNU learn to write better...

> 
> 
> 
> ------------------------------
> 
> From: [email-masked] (Matt Welsh)
> Subject: Re: LDP documentation and the FSF
> Date: Sat, 5 Feb 1994 08:59:42 +0200
> 
> [email-masked] (Greenfie) writes:
> > 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.

YES, just like I was saying above.

> RMS says that this is the next thing that they want to work on---they're
> working on a UNIX tutorial/"user guide" that would possibly be coupled with
> the fileutils documentation. He said that you and Karl, working on the LUG,
> should get in touch with him BEFORE you write the whole thing, because you
> can help each other.

They definitely need this.
 
> I think that the manuals will be the same, but may include more
> "reference-based" material---good indexes and cross-references to other
> GNU manuals. In any case, I like the idea of looking at texify and/or
> LoTeX as a first step into texinfo, so we don't have to write it
> necessarily. (Maybe tweak by hand.)

I guess it depends on what our goal is.  If it's a huge hypertext based
manual system, fine.  But I still say LaTeX is far better for producing
truly usable manuals.  Unfortunately, what makes a good hypertext document
is not always what makes a good printed/online document.

> I'm not looking for anything big right now. Just a way to get our work
> to fit in place with what the GNU folks are doing.

It's a good idea of course, but a lot of what is done in the Linux 
community is better than GNU.  I mean, GNU still doesn't have the 
operating system it announced in 1986 running yet.  Let's make sure
that Linux documentation doesn't become like a lot of the GNU stuff.
It's better, let's keep it that way.

-- 
csh
---------------------------------------------------------------------------
[email-masked] (UUCP)         | Cy486/40 LinuxOS system
[email-masked] (Internet)          | Christopher Newport University

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

From: Phil Hughes LJ Editor <[email-masked]>
Subject: Re: texinfo vs ...
Date: Sun, 6 Feb 1994 20:11:24 +0200

> Topics:
> 	 Re: LDP documentation and the FSF

> From: [email-masked] (Olaf Kirch)
> Subject: Re: LDP documentation and the FSF
> Date: Sat, 5 Feb 1994 20:10:19 +0200

> Matt hath spoken:
> > 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
...

> That said, I definitely like the idea of targetting the LDP stuff at
> a not-only-Linux audience. Since releasig the NAG last summer,
...
> So, it _is_ already used in non-Linux environments. Therefore, I've had
...

> However, there's one problem about my book, and other administration-
> related books like Lars' SAG probably as well: scale. When writing the
> NAG, I had in mind the audience at which we originally targeted it,
> namely the former-DOS addict turned Unix admin. That is, the environments
> and examples discussed tend to lean much more toward the typical PC
> environment than the fifteen workstation-LAN you find at average
> Unix installations.

I have to agree here.  But not just the size of the book but also the
problems for the reader.  Although there is economy in larger press
runs there is the problem of attempting to solve too many "not quite
the same" problems in one book.  This isn't a problem for something
like a book on learing C but it becomes a serious problem with
something like systems administration--particularly if the background
of the target audience varies from DOS beginners to Unix systems
administrators.

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

> Nevertheless, I am not sure if anyone would really want to have
> the LDP docs in texinfo. I don't know if manuals are really
> suitable for turning into hypertext stuff. Info is good for
> reference-type documentation, but not for tutorials. Just compare
...

Not having done much with texinfo (in other words, got it to run but
never written anything with it) I don't say this from a position of
strength but, to me, it seems idea for reference material but,
personally, I would rather have the LDP stuff on paper where I can
read it on the bus, open it on the desk when the system is down and I
am attepting to fix something, ...  If tutorial material is written
right (and the LDP stuff I have seen is as far as I am concerned) the
context is very important.  I use the NAG as a reference but only
after I had read the whole book.  I'm not sure if a hypertext version
of the NAG is a better answer than having the NAG as is and having a
totally separate reference.

-- 
Phil Hughes, Editor, Linux Journal, P.O. Box 85867, Seattle, WA 98145-1867 USA
E-mail: [email-masked]   Phone: +1 206 524 8338 FAX: +1 206 526 0803

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

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