From: Myknees AT aol DOT com
Message-ID: <a3cc10f.34d654e6@aol.com>
Date: Mon, 2 Feb 1998 18:21:08 EST
To: eliz AT is DOT elta DOT co DOT il
Cc: dj AT delorie DOT com, djgpp AT delorie DOT com
Mime-Version: 1.0
Subject: Re: Documentation [was Re: Random implementation]
Content-type: text/plain; charset=US-ASCII
Content-transfer-encoding: 7bit
Precedence: bulk

In a message dated 98-02-02 12:02:27 EST, you write:
>  On Sun, 1 Feb 1998 Myknees AT aol DOT com wrote:
>  
>  > Everything below the equals line is output from diff.
>  
>  You don't need to tell this.  `patch' (the program used to apply the
>  diffs to source files) knows how to find the place where the diffs
>  begin.

OK

>  
>  > *** rand.txh	Mon Jul 10 01:39:56 1995
>  > --- rand3.txh	Sun Feb  1 16:15:10 1998
>  
>  Please run diff so that the file names begin from the top-level DJGPP
>  directory.  For example:
>  
>    diff -c src/libc/ansi/stdlib/rand.old src/libc/ansi/stdlib/rand.txh
>  
>  This makes applying the diffs easier.  The way you did it requires to
>  find the directory where rand.txh lives and chdir there, before
>  running `patch'.

Yes, well, I have the sources compressed, and on a different drive, so I will
unpack them and then do that.  I suppose that they will need to be unpacked &
in their proper place eventually.

>  Also please note that it is best to name the *new* version with the
>  correct name, not the old one (it makes the operation of `patch' less
>  error-prone).  See the example above.

OK

>  
>  > ! n AT subheading Syntax
>      ^
>  I presume this `n' is a typo.

I sure didn't type anything up there on purpose.  Probably, I was hitting
CTRL-n in emacs.  Thanks for the correction.

>  
>  > + This function has its own default seed but may also be seeded with the
>  > + function @code{srand} (found in the @code{rand} source file).
>                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>  There's no need to tell where in the sources is `srand'; the libc docs
>  doesn't discuss sources at all.

OK

>  
>  If you want to refer to another function, use cross-references, like
>  this:
>  
>    This function has its own default seed but may also be seeded with the
>    function @code{srand} (@pxref{srand}).
>  
>  This generates a hyper-link to the documentation of `srand'.

But the reason that I didn't do that, referring to the source instead, is that
there is not yet any documentation for srand(), so there is nothing for the
hypertext to link to.  I do agree that some kind of cross reference would be
helpful.

>  
>  > + @example
>  > + /* seed @code{rand} with current time */
>  > + srand(time(0));
>  >   @end example
>  
>  You don't need to use the @code{} tag here, since everything inside
>  @example is typeset with the same font as @code invokes.

OK.  I will implement these changes soon.

--Ed (Myknees)