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]

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

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