libiberty docs are in

libiberty docs are in

[DJ Delorie]

I just checked in preliminary documentation for libiberty.  It is not
built by default; do "make info" or "make dvi" to build it.  Please
report any problems to me (and the usual places, of course ;)

At this time I would like to ask people who either maintain or have
recently contributed to still-undocumented parts of libiberty to
please consider submitting any needed documentation for those parts.
I can help with any editing or integration - even raw docs would help.

Many thanks to Phil Edwards for supplying the initial documentation
files, and for reminding me (many times ;) to get around to this.

Thanks,
DJ

Re: libiberty docs are in

[Eli Zaretskii]

> Date: Wed, 26 Sep 2001 14:56:24 -0400
> From: DJ Delorie <dj@redhat.com>
> 
> I just checked in preliminary documentation for libiberty.

Thanks!  It annoyed me for a long time that libiberty didn't have a
manual.

> It is not built by default; do "make info" or "make dvi" to build
> it.

Can we please have this annoyance go away?  AFAIK, no other project
requires you to say "make info" to produce the Info docs, nor say
"make install-info" to install the docs.  Why should sourceware
projects be different?

I understand that there's some history behind that, but the libiberty
docs, being newly born, doesn't have to drag that history into the
21st century, does it? ;-)

> Please
> report any problems to me (and the usual places, of course ;)

I hope the CC list in your original message lists all the ``usual
places'' I need to send this to.

Anyway, here goes:

    @c The edition date is written in three locations.  Search for 'thedate'.
    @ifinfo
    This manual describes the GNU @libib library of utility subroutines.
    This edition accompanies GCC 3, September 2001.

Isn't it better to use "@set thedate SOMETHING", and then just use
@value{thedate} in all the places?

I don't recommend using the full @node lines, like this:

    @node Using,Overview,Top,Top

This gets in the way when you need to add additional nodes later.  In
the patches below, I modified all the @node lines to name only the
name of the current node.


    @c bsearch.c:33
    @deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *))

    Performs a search over an array of @var{nmemb} elements pointed to by
    @var{base} for a member that matches the object pointed to by @var{key}.
    The size of each member is specified by @var{size}.  The array contents
    should be sorted in ascending order according to the @var{compar}
    comparison function.  This routine should take two arguments pointing to
    the @var{key} and to an array member, in that order, and should return an
    integer less than, equal to, or greater than zero if the @var{key} object
    is respecitively less than, matching, or greater than the array member.

This excerpt from functions.texi has a typo in the last line, but
bsearch.c in the CVS already has the typo fixed.  Did you forget to
regenerate functions.texi?

Patches to *.texi (or, where appropriate, to the *.c sources) follow.

[Repeat after me: "it's ``occurrence'', not ``occurance'' ;-)  May I
suggest "M-x ispell-comments-and-strings RET"?]

Index: src/libiberty/libiberty.texi
===================================================================
RCS file: /cvs/src/src/libiberty/libiberty.texi,v
retrieving revision 1.1
diff -u -p -r1.1 libiberty.texi
--- libiberty.texi	2001/09/26 18:45:49	1.1
+++ libiberty.texi	2001/09/27 10:13:58
@@ -6,6 +6,7 @@
 
 @syncodeindex fn cp
 @syncodeindex vr cp
+@syncodeindex pg cp
 
 @macro libib
 @code{libiberty}
@@ -85,7 +86,7 @@ This edition accompanies GCC 3, Septembe
 * Index::              Index of functions and categories.
 @end menu
 
-@node Using,Overview,Top,Top
+@node Using
 @chapter Using
 @cindex using libiberty
 @cindex libiberty usage
@@ -104,7 +105,7 @@ elsewhere on the system.
 
 Passing @option{--enable-install-libiberty} to the @command{configure}
 script when building @libib{} causes the header files and archive library
-to be installed when @samp{make install} is run.  This option also takes
+to be installed when @kbd{make install} is run.  This option also takes
 an (optional) argument to specify the installation location, in the same
 manner as @option{--prefix}.
 
@@ -121,7 +122,7 @@ necessary in the function descriptions.)
 add @option{-liberty} to your link command invocation.
 
 
-@node Overview,Functions,Using,Top
+@node Overview
 @chapter Overview
 
 Functions contained in @libib{} can be divided into three general categories.
@@ -138,7 +139,7 @@ Functions contained in @libib{} can be d
                                  or safety wrappers around existing code.
 @end menu
 
-@node Supplemental Functions,Replacement Functions,,Overview
+@node Supplemental Functions
 @section Supplemental Functions
 @cindex supplemental functions
 @cindex functions, supplemental
@@ -159,14 +160,14 @@ family of systems.
 Many such functions are provided in @libib{}.  They are quickly
 listed here with little description, as systems which lack them
 become less and less common.  Each function @var{foo} is implemented
-in @file{foo.c} but not declared in any @libib{} header file; more
+in @file{@var{foo}.c} but not declared in any @libib{} header file; more
 comments and caveats for each function's implementation are often
 available in the source file.  Generally, the function can simply
 be declared as @code{extern}.
 
 
 
-@node Replacement Functions,Extensions,Supplemental Functions,Overview
+@node Replacement Functions
 @section Replacement Functions
 @cindex replacement functions
 @cindex functions, replacement
@@ -196,7 +197,7 @@ functions may call one another.
 @subsection Memory Allocation
 @cindex memory allocation
 
-The functions beginning with the letter `x' are wrappers around
+The functions beginning with the letter @samp{x} are wrappers around
 standard functions; the functions provided by the system environment
 are called and their results checked before the results are passed back
 to client code.  If the standard functions fail, these wrappers will
@@ -223,7 +224,7 @@ contains a good deal of documentation fo
 @c signal stuff
 
 
-@node Extensions,,Replacement Functions,Overview
+@node Extensions
 @section Extensions
 @cindex extensions
 @cindex functions, extension
@@ -238,32 +239,30 @@ central location from which to use, main
 * Obstacks::                     Stacks of arbitrary objects.
 @end menu
 
-
-@node Functions,Obstacks,Overview,Top
-@chapter Function, Variable, and Macro Listing.
-@include functions.texi
-
 @c This is generated from the glibc manual using a make-obstacks-texi.sh
 @c script of Phil's.  Hope it's accurate.
 @include obstacks.texi
 
+@node Functions
+@chapter Function, Variable, and Macro Listing.
+@include functions.texi
 
-@node Licenses,Index,Obstacks,Top
+@node Licenses
 @appendix Licenses
 
 @menu
 
-* Library Copying::   The GNU Libary General Public License
+* Library Copying::   The GNU Library General Public License
 * BSD::               Regents of the University of California
 
 @end menu
 
 @c This takes care of Library Copying.  It is the copying-lib.texi from the
-@c GNU website, with its @node line altered to make makeinfo shut up.
+@c GNU web site, with its @node line altered to make makeinfo shut up.
 @include copying-lib.texi
 
 @page
-@node BSD,,,Licenses
+@node BSD
 @appendixsec BSD
 
 Copyright @copyright{} 1990 Regents of the University of California.
@@ -306,7 +305,7 @@ LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGE.
 
-@node    Index,,Licenses,Top
+@node    Index
 @unnumbered Index
 
 @printindex cp
Index: src/libiberty/index.c
===================================================================
RCS file: /cvs/src/src/libiberty/index.c,v
retrieving revision 1.2
diff -u -p -r1.2 index.c
--- index.c	2001/09/26 18:45:49	1.2
+++ index.c	2001/09/27 10:13:58
@@ -4,7 +4,7 @@
 
 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
 
-Returns a pointer to the first occurance of the character @var{c} in
+Returns a pointer to the first occurrence of the character @var{c} in
 the string @var{s}, or NULL if not found.  The use of @code{index} is
 deprecated in new programs in favor of @code{strchr}.
 
Index: src/libiberty/rindex.c
===================================================================
RCS file: /cvs/src/src/libiberty/rindex.c,v
retrieving revision 1.2
diff -u -p -r1.2 rindex.c
--- rindex.c	2001/09/26 18:45:50	1.2
+++ rindex.c	2001/09/27 10:13:58
@@ -4,7 +4,7 @@
 
 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
 
-Returns a pointer to the last occurance of the character @var{c} in
+Returns a pointer to the last occurrence of the character @var{c} in
 the string @var{s}, or NULL if not found.  The use of @code{rindex} is
 deprecated in new programs in favor of @code{strrchr}.
 
Index: src/libiberty/strchr.c
===================================================================
RCS file: /cvs/src/src/libiberty/strchr.c,v
retrieving revision 1.2
diff -u -p -r1.2 strchr.c
--- strchr.c	2001/09/26 18:45:50	1.2
+++ strchr.c	2001/09/27 10:15:02
@@ -5,7 +5,7 @@
 
 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
 
-Returns a pointer to the first occurance of the character @var{c} in
+Returns a pointer to the first occurrence of the character @var{c} in
 the string @var{s}, or NULL if not found.  If @var{c} is itself the
 null character, the results are undefined.
 
Index: src/libiberty/strerror.c
===================================================================
RCS file: /cvs/src/src/libiberty/strerror.c,v
retrieving revision 1.4
diff -u -p -r1.4 strerror.c
--- strerror.c	2001/09/26 18:45:50	1.4
+++ strerror.c	2001/09/27 10:15:04
@@ -608,8 +608,8 @@ strings will be the same as the ones use
 
 If the supplied error number is within the valid range of indices for
 the @code{sys_errlist}, but no message is available for the particular
-error number, then returns the string @samp{"Error NUM"}, where NUM is
-the error number.
+error number, then returns the string @samp{"Error @var{num}"}, where
+@var{num} is the error number.
 
 If the supplied error number is not a valid index into
 @code{sys_errlist}, returns NULL.
@@ -675,14 +675,14 @@ symbolic name of that error number, as f
 
 If the supplied error number is within the valid range of indices for
 symbolic names, but no name is available for the particular error
-number, then returns the string @samp{"Error NUM"}, where NUM is the
-error number.
+number, then returns the string @samp{"Error @var{num}"}, where @var{num}
+is the error number.
 
 If the supplied error number is not within the range of valid
 indices, then returns NULL.
 
 The contents of the location pointed to are only guaranteed to be
-valid until the next call to strerrno.
+valid until the next call to @code{strerrno}.
 
 @end deftypefn
 
Index: src/libiberty/strrchr.c
===================================================================
RCS file: /cvs/src/src/libiberty/strrchr.c,v
retrieving revision 1.2
diff -u -p -r1.2 strrchr.c
--- strrchr.c	2001/09/26 18:45:50	1.2
+++ strrchr.c	2001/09/27 10:15:04
@@ -5,7 +5,7 @@
 
 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
 
-Returns a pointer to the last occurance of the character @var{c} in
+Returns a pointer to the last occurrence of the character @var{c} in
 the string @var{s}, or NULL if not found.  If @var{c} is itself the
 null character, the results are undefined.
 
Index: src/libiberty/strstr.c
===================================================================
RCS file: /cvs/src/src/libiberty/strstr.c,v
retrieving revision 1.2
diff -u -p -r1.2 strstr.c
--- strstr.c	2001/09/26 18:45:50	1.2
+++ strstr.c	2001/09/27 10:15:45
@@ -6,8 +6,8 @@
 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
 
 This function searches for the substring @var{sub} in the string
-@var{string}, not including the terminating NUL characters.  A pointer
-to the first occurance of @var{sub} is returned, or NULL if the
+@var{string}, not including the terminating null characters.  A pointer
+to the first occurrence of @var{sub} is returned, or NULL if the
 substring is absent.  If @var{sub} points to a string with zero
 length, the function returns @var{string}.
 
Index: src/libiberty/strtol.c
===================================================================
RCS file: /cvs/src/src/libiberty/strtol.c,v
retrieving revision 1.5
diff -u -p -r1.5 strtol.c
--- strtol.c	2001/09/26 18:45:50	1.5
+++ strtol.c	2001/09/27 10:15:45
@@ -38,7 +38,7 @@ between 2 and 36 inclusive, or be the sp
 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
 to indicate bases 8 and 16, respectively, else default to base 10.
 When the base is 16 (either explicitly or implicitly), a prefix of
-@code{0x} is allowed.  The handling of endptr is as that of
+@code{0x} is allowed.  The handling of @var{endptr} is as that of
 @code{strtod} above.
 
 @end deftypefn
Index: src/libiberty/xatexit.c
===================================================================
RCS file: /cvs/src/src/libiberty/xatexit.c,v
retrieving revision 1.2
diff -u -p -r1.2 xatexit.c
--- xatexit.c	2001/09/26 18:45:50	1.2
+++ xatexit.c	2001/09/27 10:15:45
@@ -11,7 +11,7 @@
 @deftypefun int xatexit (void (*@var{fn}) (void))
 
 Behaves as the standard @code{atexit} function, but with no limit on
-the number of registered funtions.  Returns 0 on success, or -1 on
+the number of registered functions.  Returns 0 on success, or -1 on
 failure.  If you use @code{xatexit} to register functions, you must use
 @code{xexit} to terminate your program.
 
Index: src/libiberty/xexit.c
===================================================================
RCS file: /cvs/src/src/libiberty/xexit.c,v
retrieving revision 1.4
diff -u -p -r1.4 xexit.c
--- xexit.c	2001/09/26 18:45:50	1.4
+++ xexit.c	2001/09/27 10:16:11
@@ -22,7 +22,7 @@ Boston, MA 02111-1307, USA.  */
 @deftypefn Replacement void xexit (int @var{code})
 
 Terminates the program.  If any functions have been registered with
-the @code{xatexit} rpelacement function, they will be called first.
+the @code{xatexit} replacement function, they will be called first.
 Termination is handled via the system's normal @code{exit} call.
 
 @end deftypefn
Index: src/libiberty/xmalloc.c
===================================================================
RCS file: /cvs/src/src/libiberty/xmalloc.c,v
retrieving revision 1.7
diff -u -p -r1.7 xmalloc.c
--- xmalloc.c	2001/09/26 18:45:50	1.7
+++ xmalloc.c	2001/09/27 10:16:11
@@ -22,7 +22,8 @@ Boston, MA 02111-1307, USA.  */
 @deftypefn Replacement void* xmalloc (size_t)
 
 Allocate memory without fail.  If @code{malloc} fails, this will print
-a message to stderr (using the name set by @code{xmalloc_set_program_name},
+a message to @code{stderr} (using the name set by
+@code{xmalloc_set_program_name},
 if any) and then call @code{xexit}.  Note that it is therefore safe for
 a program to contain @code{#define malloc xmalloc} in its source.
 

Re: libiberty docs are in

[Eli Zaretskii]

Oops, forgot one file:

Index: src/libiberty/copying-lib.texi
===================================================================
RCS file: /cvs/src/src/libiberty/copying-lib.texi,v
retrieving revision 1.1
diff -u -p -r1.1 copying-lib.texi
--- copying-lib.texi	2001/09/26 18:45:49	1.1
+++ copying-lib.texi	2001/09/27 10:19:28
@@ -1,4 +1,4 @@
-@node Library Copying,,,Licenses
+@node Library Copying
 @appendixsec GNU LESSER GENERAL PUBLIC LICENSE
 
 @cindex LGPL, Lesser General Public License

Re: libiberty docs are in

[DJ Delorie]

> > It is not built by default; do "make info" or "make dvi" to build
> > it.
> 
> Can we please have this annoyance go away?

It is only temporary.  In case there were bugs, I didn't want to
burden everyone all at once.  When it's proven stable, I'll add it to
the default rules.

> > Please
> > report any problems to me (and the usual places, of course ;)
> 
> I hope the CC list in your original message lists all the ``usual
> places'' I need to send this to.

Yup.  I've put a query in to find out what the approved canonical
address should be, too.

> Isn't it better to use "@set thedate SOMETHING", and then just use
> @value{thedate} in all the places?

Yup.

> I don't recommend using the full @node lines, like this:
> 
>     @node Using,Overview,Top,Top

I couldn't get the auto-node logic to work right in all places.  If
you can, that's good!

> This excerpt from functions.texi has a typo in the last line, but
> bsearch.c in the CVS already has the typo fixed.  Did you forget to
> regenerate functions.texi?

Probably.

> Patches to *.texi (or, where appropriate, to the *.c sources) follow.
> 
> [Repeat after me: "it's ``occurrence'', not ``occurance'' ;-)  May I
> suggest "M-x ispell-comments-and-strings RET"?]

You may, but I was happy to get what was available in place...  :-)

> Index: src/libiberty/libiberty.texi

Changelog entry?

Re: libiberty docs are in

[Eli Zaretskii]

> Date: Thu, 27 Sep 2001 12:57:21 -0400
> From: DJ Delorie <dj@redhat.com>
> 
> It is only temporary.  In case there were bugs, I didn't want to
> burden everyone all at once.  When it's proven stable, I'll add it to
> the default rules.

Thank you!

> > I don't recommend using the full @node lines, like this:
> > 
> >     @node Using,Overview,Top,Top
> 
> I couldn't get the auto-node logic to work right in all places.  If
> you can, that's good!

I tested "make info" after applying the changes I sent, and it built
without any complaints.

The secret is that you need to lay out the subnodes in the same order
as they are listed in the menus.  One of the nodes was out of order,
so I moved it.  I'm guessing that this node is what gave you trouble.

> > [Repeat after me: "it's ``occurrence'', not ``occurance'' ;-)  May I
> > suggest "M-x ispell-comments-and-strings RET"?]
> 
> You may, but I was happy to get what was available in place...  :-)

Oops, sorry, I didn't realize you've written the text in the *.c files
as well.  I should have looked in the Changelog before releasing silly
jokes.

> > Index: src/libiberty/libiberty.texi
> 
> Changelog entry?

Here:

2001-09-27  Eli Zaretskii  <eliz@is.elta.co.il>

	* libiberty.texi: (Top level): Add syncodeindex pg.
	(many nodes): Lose the next,prev,up pointers on the @nide line.
	(Using, Supplemental Functions, Replacement Functions): Fix
	markup.
	(Functions): Move around, to allow makeinfo to build the manual
	without next,prev,up pointers in thye node lines.
	(Licenses): Fix typos.

	* index.c, rindex.c, strchr.c, strerror.c, strrchr.c, strstr.c,
	strtol.c, xatexit.c, xexit.c, xmalloc.c: Fix spelling and markup.

	* copying-lib.texi: Lose the next,prev,up pointers on the @node
	line.

Re: libiberty docs are in

[Phil Edwards]

On Thu, Sep 27, 2001 at 12:19:05PM +0200, Eli Zaretskii wrote:
> [Repeat after me: "it's ``occurrence'', not ``occurance'' ;-)  May I
> suggest "M-x ispell-comments-and-strings RET"?]

Certainly you may, but it won't cause me to start using Emacs...

I take responsibilty for the original state of comments, and I wasn't
about to try and run a texinfo file through any of the spell checkers I had
available to me at the time.  There used to be a DVI-to-plaintext converter
for just this sort of situation, but it never worked quite right and seems
to have become unsupported since the last time I used it.

The solution, of course, is for me to learn how to spell.  :-)

Thanks for the fixes,
Phil

-- 
"You have to wonder what kind of life you have when your list of personal
rules begins with, '#3:  No drowning in your own mucus,' and '#4:  Don't
ask what happened to rules 1 and 2.'"

Re: libiberty docs are in

[Eli Zaretskii]

Here's some more goodies:

2001-09-27  Eli Zaretskii  <eliz@is.elta.co.il>

	* libiberty.texi: (Top level): Add @dircategory and @direntry
	directives.  Add @finalout.


Index: src/libiberty/libiberty.texi
===================================================================
RCS file: /cvs/src/src/libiberty/libiberty.texi,v
retrieving revision 1.1
diff -u -r1.1 libiberty.texi
--- libiberty.texi	2001/09/26 18:45:49	1.1
+++ libiberty.texi	2001/09/27 19:00:23
@@ -2,11 +2,20 @@
 @c %**start of header
 @setfilename libiberty.info
 @settitle @sc{gnu} libiberty
-@c %**end of header
 
 @syncodeindex fn cp
 @syncodeindex vr cp
+@syncodeindex pg cp
+
+@finalout
+@c %**end of header
 
+@dircategory GNU libraries
+@direntry
+* Libiberty: (libiberty).          Library of utility functions which
+                                   are missing or broken on some systems.
+@end direntry
+

Re: libiberty docs are in

[DJ Delorie]

I combined your patches and committed them.  Thanks!

> The secret is that you need to lay out the subnodes in the same
> order as they are listed in the menus.  One of the nodes was out of
> order, so I moved it.  I'm guessing that this node is what gave you
> trouble.

Ok, although this rearranges the chapters also, putting obstacks
before the reference to libiberty-specific functions.  I guess it
doesn't matter.

> Oops, sorry, I didn't realize you've written the text in the *.c
> files as well.

Half the docs came from Phil's libiberty.texi.  I broke out the bits
and put them in *.c.  The other half were manually converted from the
man-like plain text documentation already in *.c.


2001-09-27  Eli Zaretskii  <eliz@is.elta.co.il>

	* libiberty.texi: (Top level): Add syncodeindex pg.  Add
	@dircategory and @direntry directives.  Add @finalout.
	(many nodes): Lose the next,prev,up pointers on the @nide line.
	(Using, Supplemental Functions, Replacement Functions): Fix
	markup.
	(Functions): Move around, to allow makeinfo to build the manual
	without next,prev,up pointers in thye node lines.
	(Licenses): Fix typos.

	* index.c, rindex.c, strchr.c, strerror.c, strrchr.c, strstr.c,
	strtol.c, xatexit.c, xexit.c, xmalloc.c: Fix spelling and markup.
	* functions.texi: Regenerate.

	* copying-lib.texi: Lose the next,prev,up pointers on the @node
	line.

Re: libiberty docs are in

[DJ Delorie]

> and I wasn't about to try and run a texinfo file through any of the
> spell checkers I had available to me at the time.

cat libiberty.info* | ispell -l | sort -u

Although it spits out lots of false hits.  Maybe I'll add a local
dictionary and a "spell-check" rule...

Re: libiberty docs are in

[Phil Edwards]

On Thu, Sep 27, 2001 at 04:12:12PM -0400, DJ Delorie wrote:
> 
> > and I wasn't about to try and run a texinfo file through any of the
> > spell checkers I had available to me at the time.
                                         ^^^^^^^^^^^
                                         ^^^^^^^^^^^
                                         ^^^^^^^^^^^

> cat libiberty.info* | ispell -l | sort -u

No ispell installed.  And a corrupted RPM database (thanks to up2date).
So no more RPMs could be installed.

After a long and hard system reinstall, /now/ I have a spellchecker,
as well as a whole bunch of other useful tools.  :-)

-- 
"You have to wonder what kind of life you have when your list of personal
rules begins with, '#3:  No drowning in your own mucus,' and '#4:  Don't
ask what happened to rules 1 and 2.'"

Re: libiberty docs are in

[Eli Zaretskii]

> Date: Thu, 27 Sep 2001 15:02:00 -0400
> From: Phil Edwards <pedwards@disaster.jaj.com>
> 
> On Thu, Sep 27, 2001 at 12:19:05PM +0200, Eli Zaretskii wrote:
> > [Repeat after me: "it's ``occurrence'', not ``occurance'' ;-)  May I
> > suggest "M-x ispell-comments-and-strings RET"?]
> 
> Certainly you may, but it won't cause me to start using Emacs...
> 
> I take responsibilty for the original state of comments, and I wasn't
> about to try and run a texinfo file through any of the spell checkers I had
> available to me at the time.

The latest version of Ispell comes with a deformatter program that
strips everything except comments and strings from a C source.  So you
could use Ispell as a stand-alone speller, if you don't want Emacs.