Patchwork *ping* - Re: Fix some texinfo 5.0 warnings in gcc/doc + libiberty

login
register
mail settings
Submitter Tobias Burnus
Date March 1, 2013, 7:19 p.m.
Message ID <5130FF57.1080709@net-b.de>
Download mbox | patch
Permalink /patch/224433/
State New
Headers show

Comments

Tobias Burnus - March 1, 2013, 7:19 p.m.
Joseph S. Myers wrote:
> OK, though for the libiberty patch it would be good if someone can find
> the make-obstacks-texi.sh script referred to in libiberty.texi, check it
> in and get obstacks.texi exactly in sync with the output of that script
> run on current glibc sources.

I couldn't find it, but I created a Perl version of the unknown script.

Is the attached patch OK? (I tested it with "make info html pdf" using 
(only) texinfo-4.13a.)

Tobias
Joseph S. Myers - March 6, 2013, 2:06 a.m.
On Fri, 1 Mar 2013, Tobias Burnus wrote:

> Joseph S. Myers wrote:
> > OK, though for the libiberty patch it would be good if someone can find
> > the make-obstacks-texi.sh script referred to in libiberty.texi, check it
> > in and get obstacks.texi exactly in sync with the output of that script
> > run on current glibc sources.
> 
> I couldn't find it, but I created a Perl version of the unknown script.
> 
> Is the attached patch OK? (I tested it with "make info html pdf" using (only)
> texinfo-4.13a.)

OK, with 2013 used as copyright date instead of 2012.

Patch

contrib/
2012-03-01  Tobias Burnus  <burnus@net-b.de>

	* make-obstacks-texi.pl: New.

libiberty/
2012-03-01  Tobias Burnus  <burnus@net-b.de>

	* libiberty.texi: Update comment, remove lowersections.
	* obstacks.texi: Regenerate.

diff --git a/contrib/make-obstacks-texi.pl b/contrib/make-obstacks-texi.pl
new file mode 100755
index 0000000..8128dd6
--- /dev/null
+++ b/contrib/make-obstacks-texi.pl
@@ -0,0 +1,46 @@ 
+#!/usr/bin/perl -w
+
+# (C) 2012 Free Software Foundation
+# Contributed by Tobias Burnus
+#
+# This script is Free Software, and it can be copied, distributed and
+# modified as defined in the GNU General Public License.  A copy of
+# its license can be downloaded from http://www.gnu.org/copyleft/gpl.html
+
+use strict;
+use File::Basename;
+
+
+if ($#ARGV != 0 or $ARGV[0] eq "")  {
+   my $name = basename($0);
+
+   print "\nUSAGE: `$name` memory.texi\n\n";
+   print "Reads GLIBC's manual/memory.texi and extracts the obstacks section\n"
+        ."Redirect the output to update GCC's libiberty/obstacks.texi\n\n";
+   exit 1;
+}
+
+open (IN, "<$ARGV[0]") || die "Cannot open '$ARGV[0]': $!";
+my $data = join ("", <IN>);
+close (IN);
+
+$data =~ s/.*\@node Obstacks\n/\@node Obstacks\n/s;
+$data =~ s/\n\@node [^\n]+\n\@subsection.*/\n/s;
+
+# Add refs to GLIBC
+$data =~ s/(\@p?xref{[^}]*)}/$1, , , libc, The GNU C Library Reference Manual}/gs;
+
+
+# And undo the refs which are in this file
+my @nodes = grep /^\@node /, (split /\n/, $data);
+
+foreach my $node (@nodes) {
+  $node =~ s/\@node //;
+  $node =~ s/,.*//;
+  $node =~ s/ / *\n?/g;
+  chomp ($node);
+
+  $data =~ s/(\@p?xref{$node), , , libc, The GNU C Library Reference Manual}/$1}/gsi;
+}
+
+print $data;
diff --git a/libiberty/.obstacks.texi.swp b/libiberty/.obstacks.texi.swp
new file mode 100644
index 0000000..545bf97
Binary files /dev/null and b/libiberty/.obstacks.texi.swp differ
diff --git a/libiberty/libiberty.texi b/libiberty/libiberty.texi
index f1e4bdd..f4af66d 100644
--- a/libiberty/libiberty.texi
+++ b/libiberty/libiberty.texi
@@ -241,13 +241,8 @@  central location from which to use, maintain, and distribute them.
 * Obstacks::                     Stacks of arbitrary objects.
 @end menu
 
-@c This is generated from the glibc manual using a make-obstacks-texi.sh
-@c script of Phil's.  Hope it's accurate.
-@lowersections
-@lowersections
+@c This is generated from the glibc manual using contrib/make-obstacks-texi.pl
 @include obstacks.texi
-@raisesections
-@raisesections
 
 @node Functions
 @chapter Function, Variable, and Macro Listing.
diff --git a/libiberty/obstacks.texi b/libiberty/obstacks.texi
index 67780aa..adcd810 100644
--- a/libiberty/obstacks.texi
+++ b/libiberty/obstacks.texi
@@ -1,5 +1,5 @@ 
 @node Obstacks
-@chapter Obstacks
+@subsection Obstacks
 @cindex obstacks
 
 An @dfn{obstack} is a pool of memory containing a stack of objects.  You
@@ -15,25 +15,25 @@  the objects are usually small.  And the only space overhead per object is
 the padding needed to start each object on a suitable boundary.
 
 @menu
-* Creating Obstacks::           How to declare an obstack in your program.
-* Preparing for Obstacks::      Preparations needed before you can
-                                use obstacks.
+* Creating Obstacks::		How to declare an obstack in your program.
+* Preparing for Obstacks::	Preparations needed before you can
+				 use obstacks.
 * Allocation in an Obstack::    Allocating objects in an obstack.
 * Freeing Obstack Objects::     Freeing objects in an obstack.
-* Obstack Functions::           The obstack functions are both
-                                functions and macros.
+* Obstack Functions::		The obstack functions are both
+				 functions and macros.
 * Growing Objects::             Making an object bigger by stages.
-* Extra Fast Growing::          Extra-high-efficiency (though more
-                                complicated) growing objects.
+* Extra Fast Growing::		Extra-high-efficiency (though more
+				 complicated) growing objects.
 * Status of an Obstack::        Inquiries about the status of an obstack.
 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
 * Obstack Chunks::              How obstacks obtain and release chunks;
-                                efficiency considerations.
+				 efficiency considerations.
 * Summary of Obstacks::
 @end menu
 
 @node Creating Obstacks
-@section Creating Obstacks
+@subsubsection Creating Obstacks
 
 The utilities for manipulating obstacks are declared in the header
 file @file{obstack.h}.
@@ -74,7 +74,7 @@  directly or indirectly.  You must also supply a function to free a chunk.
 These matters are described in the following section.
 
 @node Preparing for Obstacks
-@section Preparing for Using Obstacks
+@subsubsection Preparing for Using Obstacks
 
 Each source file in which you plan to use the obstack functions
 must include the header file @file{obstack.h}, like this:
@@ -160,7 +160,7 @@  obstack_alloc_failed_handler = &my_obstack_alloc_failed;
 @end defvar
 
 @node Allocation in an Obstack
-@section Allocation in an Obstack
+@subsubsection Allocation in an Obstack
 @cindex allocation (obstacks)
 
 The most direct way to allocate an object in an obstack is with
@@ -233,7 +233,7 @@  Contrast this with the previous example of @code{savestring} using
 @code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}).
 
 @node Freeing Obstack Objects
-@section Freeing Objects in an Obstack
+@subsubsection Freeing Objects in an Obstack
 @cindex freeing (obstacks)
 
 To free an object allocated in an obstack, use the function
@@ -265,7 +265,7 @@  frees the chunk (@pxref{Preparing for Obstacks}).  Then other
 obstacks, or non-obstack allocation, can reuse the space of the chunk.
 
 @node Obstack Functions
-@section Obstack Functions and Macros
+@subsubsection Obstack Functions and Macros
 @cindex macros
 
 The interfaces for using obstacks may be defined either as functions or
@@ -321,7 +321,7 @@  various language extensions in GNU C permit defining the macros so as to
 compute each argument only once.
 
 @node Growing Objects
-@section Growing Objects
+@subsubsection Growing Objects
 @cindex growing objects (in obstacks)
 @cindex changing the size of a block (obstacks)
 
@@ -435,7 +435,7 @@  the current object smaller.  Just don't try to shrink it beyond zero
 length---there's no telling what will happen if you do that.
 
 @node Extra Fast Growing
-@section Extra Fast Growing Objects
+@subsubsection Extra Fast Growing Objects
 @cindex efficiency and obstacks
 
 The usual functions for growing objects incur overhead for checking
@@ -538,7 +538,7 @@  add_string (struct obstack *obstack, const char *ptr, int len)
 @end smallexample
 
 @node Status of an Obstack
-@section Status of an Obstack
+@subsubsection Status of an Obstack
 @cindex obstack status
 @cindex status of obstack
 
@@ -580,12 +580,13 @@  obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})
 @end deftypefun
 
 @node Obstacks Data Alignment
-@section Alignment of Data in Obstacks
+@subsubsection Alignment of Data in Obstacks
 @cindex alignment (in obstacks)
 
 Each obstack has an @dfn{alignment boundary}; each object allocated in
 the obstack automatically starts on an address that is a multiple of the
-specified boundary.  By default, this boundary is 4 bytes.
+specified boundary.  By default, this boundary is aligned so that
+the object can hold any type of data.
 
 To access an obstack's alignment boundary, use the macro
 @code{obstack_alignment_mask}, whose function prototype looks like
@@ -597,7 +598,9 @@  this:
 The value is a bit mask; a bit that is 1 indicates that the corresponding
 bit in the address of an object should be 0.  The mask value should be one
 less than a power of 2; the effect is that all object addresses are
-multiples of that power of 2.  The default value of the mask is 3, so that
+multiples of that power of 2.  The default value of the mask is a value
+that allows aligned objects to hold any type of data: for example, if
+its value is 3, any type of data can be stored at locations whose
 addresses are multiples of 4.  A mask value of 0 means an object can start
 on any multiple of 1 (that is, no alignment is required).
 
@@ -620,7 +623,7 @@  This will finish a zero-length object and then do proper alignment for
 the next object.
 
 @node Obstack Chunks
-@section Obstack Chunks
+@subsubsection Obstack Chunks
 @cindex efficiency of chunks
 @cindex chunks
 
@@ -676,7 +679,7 @@  if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
 @end smallexample
 
 @node Summary of Obstacks
-@section Summary of Obstack Functions
+@subsubsection Summary of Obstack Functions
 
 Here is a summary of all the functions associated with obstacks.  Each
 takes the address of an obstack (@code{struct obstack *}) as its first