Date: Tue, 8 Apr 1997 13:49:20 +0300 (IDT)
From: Eli Zaretskii <eliz AT is DOT elta DOT co DOT il>
To: DJ Delorie <dj AT delorie DOT com>
cc: djgpp-workers AT delorie DOT com
Subject: Re: User's Guide and Mail Archives
In-Reply-To: <199704070216.WAA02102@delorie.com>
Message-ID: <Pine.SUN.3.91.970408134733.1046B-100000@is>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII


On Sun, 6 Apr 1997, DJ Delorie wrote:

> Comments are welcome, volunteers more so.

I think what's there is very clear and concise.  It would be good if
some newbie(s) reads the stuff and comments on it, though, as people
who know stuff are not the best to judge how it is described to
newbies.

Some minor comments:

  1) ug/intro/installing.html says:

	Note that you can use upper or lower case here, and either
	forward (unix) or backward (dos) slashes.  Most DJGPP
	programs, being unix ports, expect forward slashes.

     I think the last sentence might be misleading.  I suggest
     something like this instead:

	Note that you can use upper or lower case here, and either
	forward (unix) or backward (dos) slashes.  (Most DJGPP
	programs support both styles of slashes; however, being Unix
	ports, they might sometimes support forward slashes better.
	When in doubt, try forward slashes.)

  2) Descriptions of Unix programs (on installing.html):  I suggest to
     pick the short descriptions from the latest FAQ (section 4.5).
     Listing programs like head, join, fold, tac, etc. won't tell
     anything to people who aren't Unix users.  (Also, I don't think
     you should list the symlinks like `gdate' and `gmkdir', just list
     their usual names `date' and `mkdir'.)

  3) ug/basic/32bit.html says:

	All DJGPP programs are like "tiny" mode.  There is no such
	thing as a "far pointer" in DJGPP.

     This is not entirely true, as the Guide will explain elswhere
     (there's a chapter on farptr.h).  I suggest to say something like
     so:

        All DJGPP programs are like "tiny" model.  In DJGPP, you only
	use "far pointers" to access memory that is usually outside
	your address space, such as video RAM, memory-mapped devices,
	absolute addresses in the BIOS data area, etc.  See
	<a href=farptr.h section>blabla</a> for how this is done.

     There is also a typo above ("mode" instead of "model").

  4) Also, it seems like most of the 32bit.html's wording is
     negative: "this doesn't work in DJGPP, that you can't do", etc.
     This might scare people.  Perhaps saying something like "this
     guide will tell you how to do it so it works" or, better yet,
     including a link to the relevant chapter that explains it, will
     make a difference.

  5) ug/basic/copy-redistribute.html:

     It should mention libiostream.a as non-LGPL'ed, and libgxx.a is
     actually libgpp.a.

     There's a typo here ("implment").

     *every* should be done with HTML tags.

  6) ug/basic/protected.html should at least explain what a selector
     and descriptor are.

> Also, I did add djgpp-workers to the mail archive searcher at
> http://www.delorie.com/djgpp/mail-archives/

Thanks, this works, but sometimes (probably when it doesn't find anything)
it complains like so: 

  Couldn't read word, got 0 bytes djgpp-workers.lst: Invalid argument