Subject: Linux-Activists - DOC Channel digest. 93-4-9-5:7
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Sun, 9 May 1993 10:22:26 +0300

Topics:
	 Re: Linux-Activists - DOC Channel digest. 93-4-9-0:39
	 Re: Another point to consider

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

From: "Vincent D. Skahan" <[email-masked]>
Subject: Re: Linux-Activists - DOC Channel digest. 93-4-9-0:39
Date: Sun, 9 May 1993 08:00:31 +0300

> From: Greg Naber <[email-masked]>
> So we are sending everyone to the docs to read them and they are again up
> against a blank wall, looking at a bunch of characters that are tossed in
> between/amongst text strings. 
> 
> Or, we refer them to the FAQ, which doesn't say anything about how to read
> this documentation either... let along attempt to print it...
> 

I might add (since I started this wave of the thread) that all I'm looking
for is a way to print the document, mark it up by hand, then kick my edits
*IN CONTEXT AND ELECTRONICALLY* to the person who wrote them.  

I *did* grab the networking guide in Postscript and print all 200 or so
pages and it looks like not only something I can use for Linux, but something
I can recommend to others at work as a general "everything you ever wanted
to know about *nix networking" guide.  At first glance, it looks great.
But we all don't have postscript available and that's not a good answer anyway.

I can't provide quality feedback to the author(s) without plain ascii
to quote...and edit/add/delete etc. to.

Also, I also grabbed the sysadm and getty docs and can't do a damn thing
with them to get them into anything readable (short of me spending my
unavailable time looking for format codes and writing a perl filter to
strip 'em all out...which is undoubtedly reinventing a wheel that MUST
exist somewhere already).  I'm certain that they're nice too, but when you're
talking a volunteer project here...I can't waste what little time I can
devote to adding to the effort all on just getting the darn thing into
a format that I can BEGIN to read.

The questions I gave earlier still are open.  How can I get those
documents in their MULTIPLE INCOMPATIBLE formats into *one* format
that I can review and kick edits back on?

Greg also quite accurately explained the catch-22 of not knowing something
and being unable to read the answer because the way you get the answer(s)
depend on you already having the first question solved.

Again, this was my major bitch with Taylor UUCP putting the docs in
info format.

What darn software from SLS do I need to do something with the stuff
you've already created and made available for review ?

Once I get a list of software I need...then what do I do to use it ?

How can I get the format (FORMAT(S)) into ascii to mail my comments to
the author ?

This is *NOT* intrinsically self-evident folks...

-- 
 ----------- Vince Skahan ------ [email-masked] -----------

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

From: [email-masked] (Matt Welsh)
Subject: Re: Another point to consider
Date: Sun, 9 May 1993 08:38:28 +0300

From: Greg Naber <[email-masked]>
> 
> How can I read this so called documentation? When I try to look at it with
> more/less or attempt to print it, alls I see is a bunch of garbage.

If you're referring to the alpha LDP manuals, they're all in LaTeX format.
Essentially, this means:

           via LaTeX            via dvips
  foo.tex  --------->  foo.dvi  ----------> foo.ps
 (LaTeX source)   (Device Independent)    (Postscript)

> When I see valid questions about various programs in comp.os.linux, the
> reply's always state, look at the documentation, that is what it's there for.
> 
> So we are sending everyone to the docs to read them and they are again up
> against a blank wall, looking at a bunch of characters that are tossed in
> between/amongst text strings. 

Unfortunately, "the documentation" that we're sending them to on c.o.l
is *not* the LDP documentation! Those are for development only.

> Or, we refer them to the FAQ, which doesn't say anything about how to read
> this documentation either... let along attempt to print it...

Of course not. The LDP docs aren't officially released yet. :)

> Is this still the intentions? Are we going to have ascii versions available?

Yes. The LameTeX program will probably be used to produce ASCII output from
the LaTeX sources. It may need some touching up, but it shouldn't be overly
difficult (esp. once LameTeX is expanded to handle some of these things).

> I think that an ascii version of some of the fine work that is being done
> would benefit the new Linux users, allowing them to become informed about
> the stuff they are using, before they connect up to the net.

I tend to agree with you, however: the LDP manuals are not written as
normal ASCII-based "README" files. They are quite long, in-depth, and 
structured like a real book---not at all like online documentation. In 
other words to truly benefit from this format you'll want to print the 
books out via LaTeX and converting the .dvi for your printer. 

Alternatively, for those without LaTeX formatting capabilities (or reasonable
printing resources), I'd like to provide inexpensive printed copies of 
our manuals for anyone who wants them. I might be able to do some share of
this personally---e.g., have someone send an SASE and a check to cover the
cost of paper, and I'll send them a photocopy of whatever LDP manual in the
mail. Of course, since the demand for this may be too high, I might not be
able to do this personally (instead, we could find a local copy shop to take
care of it for us). 

And of course there's always O'Reilly and Associates, who have expressed
interest in possibly publishing some of our docs professionally. We'll
see what happens down this road.

All of your points are valid, however just remember that the LDP docs are
not for general distribution. The only folks using/looking at these docs
now should be those who are editing/revising/writing them, therefore we
haven't made any kind of official release of the docs (or provided 
instructions on how to print them---if you're working on the docs it's 
assumed you know how to format and print them). 

Your concerns will of course be addressed when we make an official release
of any of these docs. :)

mdw

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

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