Subject: Linux-Activists - DOC Channel digest. 93-4-1-5:8
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Sat, 1 May 1993 11:31:19 +0300

Topics:
	  Linux Programmers' Guide
	 Linux-Activists - DOC Channel digest. 93-3-30-16:18

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

From: [email-masked] (Michael K Johnson)
Subject:  Linux Programmers' Guide
Date: Sat, 1 May 1993 05:32:25 +0300

   From: [email-masked] (Zeyd M. Ben-Halim)

   The programming manual should concern itself with the external API of
   Linux and refer to the KHG for internal details. I think the book
   'Advanced Programming in the UNIX environment' by W. Richard Stevens
   would serve as a good model as to what the PG would look like.

Not exactly, as we are facing different kinds of problems.  His book
attempts (and largely succeeds) in being platform-general, and the LPG
is intended to by explicitly platform-specific.  That's why it is the
*Linux* Programmers' Guide.  If someone else wants to write a free
POSIX programming guide, be my guest, but don't expect my help -- I'm
perfectly comfortable with supporting good authors like Stevens.
(BTW, Zeyd, I'm not suggesting that you are saying this, but I have
seen the suggestion elsewhere, and also yet another person who was
concerned that I might be duplicating work.  I have no need to do that
:-)  I have enough to do already without that.... ;-))

As you say, my intent is *exactly* to cover the Linux API, and not to
document kernel internals.  Where appropriate, some *library*
internals may mentioned.

   Due to my work with ncurses I guess I can contibute the chapter dealing
   with Terminal I/O and a chapter on curses.

That would be nice.  I can take ascii or LaTeX, and massage and edit
it into my book.  I'd like to talk first with *all* volunteers 1-1
before they start...  "talk" can of course mean email or any 1-1
communication...

   If people are unfamiliar with 'APitUE' I can post an outline, people can
   pick chapters or sections they wish to contribute to.

I have no desire to surplant APitUE.  It sits on my shelf as close to
the computer as possible, by Bach and K&R and the TeXbook and the
LaTeX manual.

I'd also rather not try to supplant Lewine's Posix programming guide,
which I haven't bought yet.

However, there are things about Linux that need to be documented.
POSIX specifies a compliance document.  I don't suggest that the
LPG look like more compliance documents, but I think that it should
serve the same purpose.  Even between different posix systems, there
are differences.  The /proc filesystem is not specified by posix, for
instance.  We have just now finally straightened out utmp handling,
and that ought to be documented.  Our library is really not very well
documented, and the GCC FAQ is brief and compact and hard to follow,
and could say much more.  There are a lot of things that just aren't
very well documented.

The section 2 and 3 man pages are a very important part of this
effort, and I imagine that an paper-published version of the LPG would
include the section 2 and 3 man pages as a large part, and an
important one.  I've run into certain issues while working on porting
emacs 19 to linux, where I would have been glad to be able to look
something up.  (And please, don't ask me when emacs 19 will be
available, I'm just a peon on the team and I don't ask questions like
that and so don't know.  All I care about is that emacs 19 support
linux when it is released by the FSF.)

Other things that would have to be documented:  If async IO and SIGIO
is implemented the way that Linus is talking about, by cloning the
process (really essentially spawning a light-wieght thread), then that
should be documented, as it is likely to be worth knowing about.

Another issue:  our stdio is based on iostream.  Unfortunately, some
programs rely on parts of the FILE structure.  We have different
parts.  Those need to be documented, and ways shown of converting.
Yes, I know it is ugly.  The fact remains that stdio has limitations
which sometimes make using it onerous, and which essentially require
such messing around in the FILE structure.  Such is life, and it
should be documented.

A explanation of exactly when which system calls will be restarted,
and when not, is also of great importance.  An explanation of the
mechanism here will be most useful to the programmer.

How to convert BSD terminal handling to termios would be another
important thing.

The fact that "linux" is defined by the C compiler, in addition to
__linux__, and in direct violation of POSIX, must at least be
documented.  If it is broken, and you are unwilling to fix it, at
least document it, right?

An explanation of AT&T-style 386 assembler would also be in order.

As 680x0 Linux becomes a viable platform (which it looks like it is
doing now with remarkable rapidity, after a few false starts), any
information about that platform that is different should be documented
as well.

These are the kinds of issues that I want to cover, in some organized
fashion.  Please, please, please, if you have any ideas about specific
issues that need to be addressed, mail them to me or the list, and I
will keep them and get things started.

This won't need to be terribly long -- As O'Reilly says, it's
information, not pages, that's important.  This book may be shorter
than the IS&GS guide, who knows?  However, the great thing is to find
issues to cover and to start writing.  I will start writing blurbs
about some of these, and if anyone else wants to pick up some blurbs,
please tell me.  I'd like to get several disjoint blurbs written
before I start working on a structure that will be easy to grok.

More coments, please!

michaelkjohnson

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

From: [email-masked] (Michael K Johnson)
Subject: Linux-Activists - DOC Channel digest. 93-3-30-16:18
Date: Sat, 1 May 1993 06:19:10 +0300

       * Which books (or parts of books) are of general interest?  User's
	 and system administrator's guides sound like good candidates.
	 At first I assumed that we wouldn't have a reason to publish any
	 of the kernel hacker's guide, but I've been told that a lot of
	 people might be interested in a book like "Inside Linux" or "The
	 Design of the Linux Operating System."

I imagine that that can partly be determined by looking at ftp logs
and seeing how many people downloaded them, since the books will be
freely availble.  I have been told that the little bits of the KHG
that have been written so far have already been used in OS classes.  I
don't know if it will be an O'Reilly thing, but I think that the
demand is there.  I am working hard to keep it at a level that is
accessible to the newbie, but not demeaning to the hacker.  So far, I
think it succeeds, as far as it can.  But we will see whether it is
something that O'Reilly would want to publish when it is done.  It has
just begun.

       * How do we identify and isolate the parts of the books that
	 change fast?  These parts are not suitable for commercial
	 publication.  Matt Welsh has pointed out that installation (a
	 very important topic) should not be in an O'Reilly book because
	 it chagnes weekly.  As I suggested above, parts of the kernel
	 hacker's guide have the same problem, because they could change
	 from release to release.

The changes are becoming smaller and smaller, and coming in more
modular chunks, as Linux matures.  By the time that the LDP books are
ready for publication, even the KHG should be a relatively stable
document.  That is, I will probably keep expanding it, but little of
the content will change.  I think that when the time comes, it will be
obvious which docs change too rapidly, because they will be changing
rapidly.  An easy test.  :-)

       * Since we want to put out the books as fast as possible, and we
	 don't expect to make a lot of money on them, how can we get
	 commercial-quality books without putting in a lot of time and
	 effort at O'Reilly?

I will personaly provide them camera-ready copy if you wish.  Assuming
I find a job, I intend to have a HP 4 to print them out on, which
should be good enough.  With their RET, the quality approaches that of
a linotronic quite closely enough for our purposes.  If I don't buy
one, I know someone quite well who already has, and likely others on
the net have them as well.  Where there's a will, there's a way.

Alternately, and probably much preferably, we can easily provide .dvi
or .ps to O'Reilly.  I can also change the style to fit a book.  The
largest problem is code fragments, which may go to 80 columns.  Not a
big problem, but one of the biggest in several docs.  Another is large
filenames, but those can be dealt with as well.

	 Here again, I hope I can speak frankly without offending: our
	 books are popular because we have a lot of professional staff
	 spend a lot of time on them.  Your books are written mostly by
	 amateur writers in their spare time.  I expect they'll be full
	 of excellent content, but they won't be a lot of fun in terms of
	 organization and style.

Not as good as your best, perhaps, but I'll ask that you wait until
the NAG is released for alpha and take a look at it.  I am hoping that
this is soon.  I am running a quick proof on it right now to remove as
many spelling and grammatical errors as I can, and I think that Olaf
will do a release pretty soon now.  It is very well organized, clearly
written, and timely.

       * How can we distinguish the Linux Documentation Project books as
	 a separate series?  Even if the quality is excellent, these
	 books will reflect a different style and philosophy from ours --
	 and an important part of our image lies in people knowing what
	 to expect when they buy an O'Reilly book.  We'll have to show
	 through the cover design that this is not a typical O'Reilly
	 book.  We'd be happy to do that, but it's a new venture for us.

Well, the philosophy isn't *that* different: information, not paper.
But we can certainly design the books to be distinctly different.
Beleive it or not, I've been thinking about this.  But this issue can
be taken care of when the time comes and you have seen the documentation.

       * Where do royalties go?  That's not much of a problem, because
	 there will not be much in the way of royalties!  I should be
	 more optimistic.  Anyway, author royalties should go back into
	 the Linux project somehow.  Of course, the books will be under
	 the GPL.

I think that the main author of the book should get something, and
Linus should get something.  Perhaps some to the author, some to
Linus, and some to the Linux fund that was just established?  The
books aren't actually under the GPL: the GPL doesn't apply to books
very well, IMHO.  The KHG a sample of the kind of copyright we use, on
page ii.  Check it out, if you like:
ftp.stolaf.edu:/pub/linux-doc/khg.{tar,dvi,ps}.z (this is not the
latest version: for examply, the tour has been relegate to an appendix
where it belongs) This is the copyright that at least most of us
intend to use for our documents, with appropriate changes.  For
instance, the last condition only holds for docs that are written with
significant contributions from others.

We certainly can't and won't ask you to agree to publish books under
the O'Reilly name that you have not seen and whose quality you cannot
determine.  When you see publishable drafts, then you can make a
decision.  If you decide that you'd rather not have the O'Reilly name
on them, they will get published some other way.

We'll see.  In the meantime, we'll wait and work.  There's a lot to be
done before decisions like that are made.

Thanks for your comments,

michaelkjohnson

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

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