Subject: Linux-Activists - DOC Channel digest. 93-4-9-20:53
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Mon, 10 May 1993 04:41:22 +0300

Topics:
	 ASCII documentation
	 LDP info in manuals
	 Linux-Activists - DOC Channel digest. 93-4-9-5:7
	 Linux-Activists - DOC Channel digest. 93-4-9-5:7
	 Re: Linux-Activists - DOC Channel digest. 93-4-9-15:13
	 Re: Linux-Activists - DOC Channel digest. 93-4-9-15:13
	 Document format
	 Re: Linux-Activists - DOC Channel digest. 93-4-9-15:13

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

From: [email-masked] (Michael K Johnson)
Subject: ASCII documentation
Date: Sun, 9 May 1993 22:41:56 +0300

(there is something reasonable after the following flame -- skip the
flame if you want, but read the section after it.  Search for
"#undef FLAME_MODE" if you don't want to read the flame.

#define FLAME_MODE

Can this please be the last time we have to explain this, at least to
you guys?  I seem to recall going through this with approximately the
same people some months ago, and it was just as painful then.  If it
was not you, I apologize, but I think that at least one of you has
been a member of this channel quite long enough to have seen the last
flame was about ascii documentation.

   > 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'll leave this alone, since Matt has already answered it quite effectively.

   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.

Well, if you had instead gotten the tar.z file *WITH THE SOURCE* (yes,
you yell, I'll yell back...), you would not have any problems
providing feedback.  The source is very readable LaTeX.  If you
haven't even looked at it, don't complain about it not being there.
And yes, when it was announced, the source was announced too.

My fianc\'{e}e learned to *write* LaTeX in a few hours.  You might be able
to grok it, at any rate, after a no more than reasonable amount of trial.

   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.

HUH? HUH?  What?
 1) You are really overreacting here.
 2) If you find that an occasional LaTeX command makes it ABSOLUTELY
    impossible to read, get detex.  It takes out the command words for
    you.  Use archie to find it, or look on any TeX archive.  It is
    small, too.

   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?

What formats besides LaTeX are being used?  Could you please
condescend to name these "MULTIPLE INCOMPATIBLE formats"?  I hope that
the only problem here is that your fingers are getting ahead of your brain.

   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.

Matt already pointed out, *as has been pointed out many times in this
forum now*, that when the docs are released there will be full
instructions for getting them and printing them.  Matt and I have
*both* publically volunteered to publish docs ourselves in paper
format if no other publishers want them.  Could you *please* explain
what more you want?

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

Oh, and raw info files are *so* hard to read.  NOT.

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

The 3 T-series disks will give you all that you need to format the
documents into .dvi files and then move them into .ps files if you
like.  Alternately, you can print out the postscript docs or dvi docs
provided, and work directly with the source for providing diffs.  It's
not hard to read, really.

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

cd <foo>
tar xf <tarfile>
latex <filename>

then
xdvi <filename.dvi>
or
dvips <filename.dvi> -o <filename.ps>
lpr -v <filename.ps>

If you need more help, ask *politely* for it.

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

It is in ascii, with some latex commands in it.  Edit the source and
sent context or unified diffs to the author.

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

Get off your high horse.  If you don't know, ask nicely.  I like
helping, when I am not first ridiculed for trying to do a decent job.
When the documents are released for public consumption, nice
meta-documentation in ascii will be provided.  Don't make us start
doing like H.J. Lu:

When the documents are released for public consumption, nice
meta-documentation in ascii will be provided.

When the documents are released for public consumption, nice
meta-documentation in ascii will be provided.

When the documents are released for public consumption, nice
meta-documentation in ascii will be provided.

When the documents are released for public consumption, nice
meta-documentation in ascii will be provided.

When the documents are released for public consumption, nice
meta-documentation in ascii will be provided.

We are also working on (and this also has been announced several
times) tools to provide the docs in many formats, including ascii.
The ascii docs will not be as nice, but they will be there.
Eventually, we would like to also provide info docs as well.

I have noticed that the only thing so far to come out of the ASCII
faction has been complaining.  I've noticed a strong lack of work from
that direction.  That's fine -- not everybody has time to do lots of
writing.  However, please remember that he who pays the piper calls
the tune, and at least don't rail against us for not doing what we
have already said we would do.

#undef FLAME_MODE

That was not a subtle hint, and perhaps I overreacted as well.
However, the next time I answer questions about ASCII, I'd rather the
question come from someone who has not already been told the answers.

Jonthan Monsarrat is re-writing LameTeX this summer, and as he would
like to help the project, he wants to make sure that his extensions
meet our documentation needs.  LameTeX can output text nicely, and
will get nicer yet.  I am already using it to format the INFO-SHEET
and META-FAQ, so that I can provide nice dvi versions as well for
those who would like nice-looking copy for various reasons, including
handing them out to friends and bringing to conferences, etc.

michaelkjohnson

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

From: [email-masked] (Michael K Johnson)
Subject: LDP info in manuals
Date: Sun, 9 May 1993 23:00:25 +0300

   Comments? Is it too cheesy?

   mdw

   --
   % blurb.tex
   The Linux Documentation Project is a loose team of writers, proofreaders, 
   and editors who have decided that ``enough is enough'' as far as Linux
   documentation is concerned.

I'm really not sure what ``enough is enough'' is supposed to refer to.

   The overall coordinator of the project is
   Matt Welsh, aided heavily by Lars Wirzenius and Michael K. Johnson.

   This manual is one in a set of several being distributed
   by the Linux Doc Project, including a Linux User's Guide, System
   Administrator's Guide, and Kernel Hacker's Guide. These manuals are all 

"Hackers'",  plural possesive.  Nobody gets it right ;-(
Just to get back, I've put all the titles into the plural possesive
below. ;-)

   available in \LaTeX\ source format and Postscript output for anonymous FTP
   from {\tt nic.funet.fi}, in the directory {\tt /pub/OS/Linux/doc/doc-project}.

   We encourage anyone with a penchant for writing or editing to join us in
   improving Linux documentation. If you have Internet e-mail access, you can
   join the {\tt DOC} channel of the {\tt Linux-Activists} mailing list by 
   sending mail to 
   \begin{tscreen}
   [email-masked]
   \end {tscreen}
   with the line
   \begin{tscreen}
   X-Mn-Admin: join DOC
   \end{tscreen} 
   as the top of the message body. 

How about the following?

% blurb.tex
The \Linux\ Documentation Project, or LDP, is a loose team of writers,
proofreaders, and editors who are working together to provide complete
documentation for the \linux\ operating system.  The overall
coordinator of the project is Matt Welsh, who is heavily aided by Lars
Wirzenius and Michael~K.\ Johnson.

This manual is one in a set of several being distributed by the LDP,
including a Linux Users' Guide, System Administrators' Guide, Network
Administrators' Guide, and Kernel Hackers' Guide. These manuals are
all available in \LaTeX\ source format, .dvi format, and postscript
output by anonymous FTP from {\tt nic.funet.fi}, in the directory
/pub/OS/Linux/doc/doc-project, and from {\tt tsx-11.mit.edu}, in the
directory /pub/linux/docs/guides.

We encourage anyone with a penchant for writing or editing to join us in
improving Linux documentation. If you have Internet e-mail access, you can
join the {\tt DOC} channel of the {\tt Linux-Activists} mailing list by 
sending mail to 
\begin{tscreen}
[email-masked]
\end {tscreen}
with the line
\begin{tscreen}
X-Mn-Admin: join DOC
\end{tscreen} 
in the header or as the first line of the message body. 
% end blurb.tex

michaelkjohnson

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

From: [email-masked] (Michael K Johnson)
Subject: Linux-Activists - DOC Channel digest. 93-4-9-5:7
Date: Sun, 9 May 1993 23:16:24 +0300

   If you have problems printing the docs, it's not that difficult to mail the
   author and ask them to produce a PostScript file from the .dvi's. Perhaps
   we should put Postscript up on ftp.stolaf.edu as well, for those who don't
   have LaTeX and/or dvips. Michael?

At least the KHG and the NAG have both postscript and dvi files, as
well as source.  I imagine that that will continue.  I think that all
the rest of the docs there only have source, but as things progress,
more compiled files will be available, in multiple formats.

   Any changes you make to the docs should be made on the LaTeX source, and
   you can send the author(s) cdiffs against this source. If you don't
   know LaTeX, get "LaTeX: A Document Preparation System" by Leslie Lamport.
   It should be quite obvious from there on in. :)

It shouldn't be that hard to read even without buying the manual --
after all, one of the first sections in the manual is "how to avoid
reading this book", and I *wrote* latex source before I got the
manual.  I imagine that reading it should not be that difficult for
most people able to grok, oh, say, sendmail configuration files... ;-)

   It is to those of us who have used LaTeX before. We assume that if you
   don't recognize *.tex or *.dvi then you haven't used it before. Early
   on we specified that everything was going to be done in LaTeX; the LDP
   "Manifesto" mentions this as well.

Also, we assume that if you don't recognize *.tex and *.dvi, that you
will ask what they are and how to deal with them before flaming us...
Perhaps we shouldn't assume so much.

michaelkjohnson

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

From: [email-masked] (Michael K Johnson)
Subject: Linux-Activists - DOC Channel digest. 93-4-9-5:7
Date: Sun, 9 May 1993 23:23:12 +0300

   O.K., this helps somewhat, but just for grins (since I deleted TeX off the
   BBS system, to make more room for the Linux archive), I went to the SLS
   t-series disks and seeing a texdoc.tgz, I took it apart to read the doc's,
   and imagine my surprize, when I found out that I need to have TeX
   installed BEFORE I could read the manual on it;) and the file name of this
   documentation is called Gentle.Tex, I hope this isn't what you had in
   mind when you stated the LDP's would be made available in simple format's...

Not at all.  We *do* mean what we say.  The gentle intro to tex is
usually printed by TeX-savvy people and given to their non-TeX-savvy
friends. 

   I could point you to a message of yours talking about the wonders of the
   LDP docs that you posted on comp.os.linux, then point you to the message
   from you about where the docs are stored, the point being, that you have
   made them readily available in your own posts.

Um, I don't think that Matt has posted the ftp.stolaf.edu directory on
c.o.l.  I think that you should dig up the posts you mention before
saying that.

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

   Which brings us back full circle to the catch-22 situation of having TeX
   installed before being able to read the TeX manual;(

No, it doesn't.  We will have META_DOCUMENTATION explaining how to
print the docs.

   > assumed you know how to format and print them). 

   By virtue of default, they *are* available to anyone who takes the time to
   find out *where* they are stored. 

Sure, and sensitive government documents are "available" to anyone who
breaks security.  If people are determined enough to take the time to
find out where they are stored, they can darn well take the effort to
figure out how to format them.  When they are *announced*, we will
document that.  REALLY.  PLEASE BELIEVE US!  We don't enjoy lying, OK?

   I really didn't & don't intend to start a 'flame' war over this issue in
   this channel, I am getting enough of that in my mailbox;), 

If you don't want to start a flame war, start out by not flaming.

   Increase the potential of having 100's of proof-readers and editor's
   before the LDP is made available in the 'final' version, by having more
   avenue's for people to look at, you may just be surprised at the amount of
   support that could possibly be generated.....

In good time, as has been said many times.

michaelkjohnson

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

From: [email-masked] (Matt Welsh)
Subject: Re: Linux-Activists - DOC Channel digest. 93-4-9-15:13
Date: Sun, 9 May 1993 23:30:34 +0300

> From: Greg Naber <[email-masked]>

> and imagine my surprize, when I found out that I need to have TeX
> installed BEFORE I could read the manual on it;) and the file name of this
> documentation is called Gentle.Tex, I hope this isn't what you had in
> mind when you stated the LDP's would be made available in simple format's...

LaTeX is not that difficult; you're just looking in the wrong place.
One of the several books on LaTeX should help you to get started, and
installing it on your system should be a snap. 

The "Gentle.tex" and other TeX/LaTeX docs that you're going to find
mostly tell you how to *write* in TeX, not how to format it. There should
be man pages telling you how to use the programs themselves. It's
really easy, just
	$ latex foo.tex

> I could point you to a message of yours talking about the wonders of the
> LDP docs that you posted on comp.os.linux, then point you to the message
> from you about where the docs are stored, the point being, that you have
> made them readily available in your own posts.

Probably an accident. I don't think I posted the version of the Manifesto
which has (buried deep within it) the location of the alpha doc-project
directory. In any case, everyone on this mailing list knows, anyway, so 
it's not a big deal.

But we never said that these docs were available and ready for general
redistribution. Just telling you where they are does not imply that.

> Which brings us back full circle to the catch-22 situation of having TeX
> installed before being able to read the TeX manual;(

There are man pages. See above.

> By virtue of default, they *are* available to anyone who takes the time to
> find out *where* they are stored. 

Yes, but not intended for general redistribution.

> Also, as Vince pointed out, by having formats that are easily read, edited,
> and printed, it *MAY* increase the chances of some of us who can help
> contribute to the project. 

LaTeX is used all over the world. Hell, you can even run it under DOS.
And it's free, and it'll produce great-looking output for tons of printer
types. And what could be easier to edit than a plain text file? That's
all that LaTeX source is.

I'm sorry that some of you haven't done any work with LaTeX yet. That's
not my fault; it's really not too difficult to get started.

> I am attempting to point out that there are people who can contribute to
> the documentation project, either by writing something themselves, or by
> reading and submitting changes to the documentation already available, but
> may not have the time or interest in setting up the 'so far' required
> programs to manipulate these documents.

If someone is going to take the time to edit our docs carefully and
completely, and not do a sloppy job with it, I imagine they can take 15
minutes to install LaTeX on their machine, or find somewhere to run it
from. Or they can simply print out the PostScript and edit the sources...
you don't need to set up any software at all to proofread or edit these docs.

I don't feel like sacrificing quality for ease of formatting. Anyone serious
about working on the LDP docs can learn the minimal amount of LaTeX needed
to proofread and edit them. :)

mdw

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

From: Greg Naber <[email-masked]>
Subject: Re: Linux-Activists - DOC Channel digest. 93-4-9-15:13
Date: Mon, 10 May 1993 00:21:43 +0300

> > From: "Vincent D. Skahan" <[email-masked]>
> > 
> > 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
> 
> If you have problems printing the docs, it's not that difficult to mail the
> author and ask them to produce a PostScript file from the .dvi's. Perhaps
> we should put Postscript up on ftp.stolaf.edu as well, for those who don't
> have LaTeX and/or dvips. Michael?

> They're all in the same format: LaTeX source. I'm sorry if this was not 
> made clear enough. You format the source using LaTeX, then produce Postscript
> the resulting .dvi with dvips. 

So now alls I have to do is go buy a postscript printer, good, I can
certainly afford to do that to support this hobby I have here.

> > Once I get a list of software I need...then what do I do to use it ?
> 
> Get the SLS t1-t3 disks and install it. You probably don't need MetaFont
> but it can't hurt. xdvi is an X11 previewer for .dvi files, if you don't
> want to do all of that printing. dvips converts .dvi to PostScript, as 
> explained above. 

X11 and TeX are both items I can do without running this 'free' access
Linux site. What is the software needed to convert the TeX source to plain
ascii format or at the least, to be able to use this rather old 9-pin
printer I have here. 

Something along the lines of program file >/dev/lp2 and have a rather
resonable chance of getting it printed without a lot of useless
underlining or bold face being done to the poor printer? 

> > How can I get the format (FORMAT(S)) into ascii to mail my comments to
> > the author ?
> 
> See above; send changes to the LaTeX source.

Again, you are cutting out the pssibilty of having many proofreaders
available to you by having just one format. And making it a requirement
that anyone who wants to help is required to know and use more hardware
than they may be willing to give room or time for.

> It is to those of us who have used LaTeX before. We assume that if you don't
> recognize *.tex or *.dvi then you haven't used it before. Early on we
> specified that everything was going to be done in LaTeX; the LDP "Manifesto" 
> mentions this as well.

Early on it was mentioned that ascii was to be available also.

> I really didn't & don't intend to start a 'flame' war over this issue in
> this channel, I am getting enough of that in my mailbox;), 
> 
> I am attempting to point out that there are people who can contribute to
> the documentation project, either by writing something themselves, or by
> reading and submitting changes to the documentation already available, but
> may not have the time or interest in setting up the 'so far' required
> programs to manipulate these documents.
> 
> Increase the potential of having 100's of proof-readers and editor's
> before the LDP is made available in the 'final' version, by having more
> avenue's for people to look at, you may just be surprised at the amount of
> support that could possibly be generated.....

---
               S'Qually Holler's BBS  +1-206-235-0270
                   Another WaffleIron on Linux!
         For anonymous uucp access, login: nuucp word: nuucp
           uucp squally!/sc2/bbs/filelist.z  filelist.z

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

From: [email-masked] (Gavin Thomas Nicol)
Subject: Document format
Date: Mon, 10 May 1993 02:33:16 +0300

Well, a lot of people seem to be worried about the format of
documents. I though we had all agreed that LaTeX would be used for
book-like stuff, man for man pages, and texinfo for GNU stuff.

A long time ago we had a discussion about document formats, and at
that time I argued for texinfo, and I lost. However, I offered to
write a man->texinfo, and a LaTeX->texinfo converter, along with an
online browsing system similar/based on GNU info. I am still doing
this. To date, I have been working mostly on the browser (in
particular, I have been working on a UI library which will work across
MSDOS/X/TTY, and a SCHEME extension language), and I have also got a
basic man->texinfo Flex filter done (though it still needs more work).
Things are progressing, but I have only so much time....

Anyway, eventually, I hope to be able to offer a unified system for
documentation, which will allow online browsing, and printing, and
conversion from various formats. Don't hold your breath for it though.

To the fellow from ORA (sorry I forgot your name). I noted that you
were interested in the Freelore project as well, so it seems that you
have a large interest in the tools needed for online documentation.
Perhaps we could discuss this?

BTW. It might be a good idea to update my entry in the LDP guide to
reflect the work I am doing. I am listed as doing a "reference
manual", though in fact, most of that will come from GNU.

nick

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

From: [email-masked] (John Henders)
Subject: Re: Linux-Activists - DOC Channel digest. 93-4-9-15:13
Date: Mon, 10 May 1993 03:15:19 +0300

	On my Atari ST, there were several TeX to ascii programs and
even a few dvi to ascii converters. Most stuff like this for the
ST were unix ports, yet in looking around, I have not seen any programs
like this for linux. Has no one ported one of these? If not, I
can try to get source for one and make it available, as it seems
to be what is needed here.

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

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