Changed all @example to @smallexample; misc changes for formatting.
authorroland <roland>
Mon, 21 Jun 1993 02:09:05 +0000 (02:09 +0000)
committerroland <roland>
Mon, 21 Jun 1993 02:09:05 +0000 (02:09 +0000)
manual/math.texi
manual/mbyte.texi
manual/memory.texi
manual/pattern.texi
manual/pipe.texi
manual/search.texi
manual/setjmp.texi
manual/signal.texi
manual/socket.texi
manual/startup.texi
manual/stdio.texi

index 6c41a47..a97d76c 100644 (file)
@@ -99,9 +99,9 @@ that pi radians equals 180 degrees.
 The math library doesn't define a symbolic constant for pi, but you can
 define your own if you need one:
 
-@example
+@smallexample
 #define PI 3.14159265358979323846264338327
-@end example
+@end smallexample
 
 @noindent
 You can also compute the value of pi with the expression @code{acos
index ff48b27..75cdc54 100644 (file)
@@ -380,19 +380,20 @@ is less than @var{size}.
 Here is an example showing how to convert a string of multibyte
 characters, allocating enough space for the result.
 
-@example
+@smallexample
 wchar_t *
-mbstowcs_alloc (char *string)
+mbstowcs_alloc (const char *string)
 @{
-  int size = strlen (string) + 1;
-  wchar_t *buffer = (wchar_t) xmalloc (size * sizeof (wchar_t));
+  size_t size = strlen (string) + 1;
+  wchar_t *buf = xmalloc (size * sizeof (wchar_t));
 
-  size = mbstowcs (buffer, string, size);
-  if (size < 0)
+  size = mbstowcs (buf, string, size);
+  if (size == (size_t) -1)
     return NULL;
-  return (wchar_t) xrealloc (buffer, (size + 1) * sizeof (wchar_t));
+  buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
+  return buf;
 @}
-@end example
+@end smallexample
 
 @end deftypefun
 
@@ -535,7 +536,7 @@ stored shift state @emph{as well as} storing the multibyte character
 @end deftypefun
 
 @node Example of Conversion, Shift State, Converting One Char, Extended Characters
-@section Example of Character-by-Character Conversion
+@section Character-by-Character Conversion Example 
 
 Here is an example that reads multibyte character text from descriptor
 @code{input} and writes the corresponding wide characters to descriptor
@@ -544,7 +545,7 @@ example because @code{mbstowcs} is unable to continue past a null
 character, and cannot cope with an apparently invalid partial character
 by reading more input.
 
-@example
+@smallexample
 int
 file_mbstowcs (int input, int output)
 @{
@@ -619,7 +620,7 @@ file_mbstowcs (int input, int output)
 
   return 1;
 @}
-@end example
+@end smallexample
 
 @node Shift State,  , Example of Conversion, Extended Characters
 @section Multibyte Codes Using Shift Sequences
@@ -660,7 +661,7 @@ processing of different strings.
 
 Here is an example of using @code{mblen} following these rules:
 
-@example
+@smallexample
 void
 scan_string (char *s)
 @{
@@ -685,7 +686,7 @@ scan_string (char *s)
       length -= thischar;
     @}
 @}
-@end example
+@end smallexample
 
 The functions @code{mblen}, @code{mbtowc} and @code{wctomb} are not
 reentrant when using a multibyte code that uses a shift state.  However,
index 98f1c6f..2ea915e 100644 (file)
@@ -103,7 +103,7 @@ declare a variable of pointer type @code{struct foobar *} and assign it the
 address of the space.  Then you can use the operators @samp{*} and
 @samp{->} on this pointer variable to refer to the contents of the space:
 
-@example
+@smallexample
 @{
   struct foobar *ptr
      = (struct foobar *) malloc (sizeof (struct foobar));
@@ -111,7 +111,7 @@ address of the space.  Then you can use the operators @samp{*} and
   ptr->next = current_foobar;
   current_foobar = ptr;
 @}
-@end example
+@end smallexample
 
 @node Unconstrained Allocation
 @section Unconstrained Allocation
@@ -167,13 +167,13 @@ that you want to store in the block.  Here we show an example of doing
 so, and of initializing the space with zeros using the library function
 @code{memset} (@pxref{Copying and Concatenation}):
 
-@example
+@smallexample
 struct foo *ptr;
 @dots{}
 ptr = (struct foo *) malloc (sizeof (struct foo));
 if (ptr == 0) abort ();
 memset (ptr, 0, sizeof (struct foo));
-@end example
+@end smallexample
 
 You can store the result of @code{malloc} into any pointer variable
 without a cast, because ANSI C automatically converts the type
@@ -186,11 +186,11 @@ Remember that when allocating space for a string, the argument to
 because a string is terminated with a null character that doesn't count
 in the ``length'' of the string but does need space.  For example:
 
-@example
+@smallexample
 char *ptr;
 @dots{}
 ptr = (char *) malloc (length + 1);
-@end example
+@end smallexample
 
 @noindent
 @xref{Representation of Strings}, for more information about this.
@@ -205,7 +205,7 @@ error if the value is a null pointer, returning only if the value is
 nonzero.  This function is conventionally called @code{xmalloc}.  Here
 it is:
 
-@example
+@smallexample
 void *
 xmalloc (size_t size)
 @{
@@ -214,13 +214,13 @@ xmalloc (size_t size)
     fatal ("virtual memory exhausted");
   return value;
 @}
-@end example
+@end smallexample
 
 Here is a real example of using @code{malloc} (by way of @code{xmalloc}).
 The function @code{savestring} will copy a sequence of characters into
 a newly allocated null-terminated string:
 
-@example
+@smallexample
 char *
 savestring (const char *ptr, size_t len)
 @{
@@ -229,7 +229,7 @@ savestring (const char *ptr, size_t len)
   value[len] = 0;
   return value;
 @}
-@end example
+@end smallexample
 
 The block that @code{malloc} gives you is guaranteed to be aligned so
 that it can hold any type of data.  In the GNU system, the address is
@@ -277,7 +277,7 @@ the block after freeing it.}  Copy whatever you need out of the block before
 freeing it!  Here is an example of the proper way to free all the blocks in
 a chain, and the strings that they point to:
 
-@example
+@smallexample
 struct chain
   @{
     struct chain *next;
@@ -295,7 +295,7 @@ free_chain (struct chain *chain)
       chain = next;
     @}
 @}
-@end example
+@end smallexample
 
 Occasionally, @code{free} can actually return memory to the operating
 system and make the process smaller.  Usually, all it can do is allow a
@@ -345,7 +345,7 @@ message.  Often it is convenient to write and use a subroutine,
 conventionally called @code{xrealloc}, that takes care of the error message
 as @code{xmalloc} does for @code{malloc}:
 
-@example
+@smallexample
 void *
 xrealloc (void *ptr, size_t size)
 @{
@@ -354,7 +354,7 @@ xrealloc (void *ptr, size_t size)
     fatal ("Virtual memory exhausted");
   return value;
 @}
-@end example
+@end smallexample
 
 You can also use @code{realloc} to make a block smaller.  The reason you
 would do this is to avoid tying up a lot of memory space when only a little
@@ -381,7 +381,7 @@ cleared to zero before @code{calloc} returns.
 
 You could define @code{calloc} as follows:
 
-@example
+@smallexample
 void *
 calloc (size_t count, size_t eltsize)
 @{
@@ -391,7 +391,7 @@ calloc (size_t count, size_t eltsize)
     memset (value, 0, size);
   return value;
 @}
-@end example
+@end smallexample
 
 We rarely use @code{calloc} today, because it is equivalent to such a
 simple combination of other features that are more often used.  It is a
@@ -508,9 +508,9 @@ The value of this variable is a pointer to function that @code{malloc}
 uses whenever it is called.  You should define this function to look
 like @code{malloc}; that is, like:
 
-@example
+@smallexample
 void *@var{function} (size_t @var{size})
-@end example
+@end smallexample
 @end defvar
 
 @comment malloc.h
@@ -520,9 +520,9 @@ The value of this variable is a pointer to function that @code{realloc}
 uses whenever it is called.  You should define this function to look
 like @code{realloc}; that is, like:
 
-@example
+@smallexample
 void *@var{function} (void *@var{ptr}, size_t @var{size})
-@end example
+@end smallexample
 @end defvar
 
 @comment malloc.h
@@ -532,9 +532,9 @@ The value of this variable is a pointer to function that @code{free}
 uses whenever it is called.  You should define this function to look
 like @code{free}; that is, like:
 
-@example
+@smallexample
 void @var{function} (void *@var{ptr})
-@end example
+@end smallexample
 @end defvar
 
 You must make sure that the function you install as a hook for one of
@@ -546,7 +546,7 @@ Here is an example showing how to use @code{__malloc_hook} properly.  It
 installs a function that prints out information every time @code{malloc}
 is called.
 
-@example
+@smallexample
 static void *(*old_malloc_hook) (size_t);
 static void *
 my_malloc_hook (size_t size)
@@ -566,7 +566,7 @@ main ()
   __malloc_hook = my_malloc_hook;
   ...
 @}
-@end example
+@end smallexample
 
 The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
 installing such hooks.
@@ -749,9 +749,9 @@ These matters are described in the following section.
 Each source file in which you plan to use the obstack functions
 must include the header file @file{obstack.h}, like this:
 
-@example
+@smallexample
 #include <obstack.h>
-@end example
+@end smallexample
 
 @findex obstack_chunk_alloc
 @findex obstack_chunk_free
@@ -766,10 +766,10 @@ Usually these are defined to use @code{malloc} via the intermediary
 @code{xmalloc} (@pxref{Unconstrained Allocation}).  This is done with
 the following pair of macro definitions:
 
-@example
+@smallexample
 #define obstack_chunk_alloc xmalloc
 #define obstack_chunk_free free
-@end example
+@end smallexample
 
 @noindent
 Though the storage you get using obstacks really comes from @code{malloc},
@@ -789,21 +789,21 @@ Initialize obstack @var{obstack_ptr} for allocation of objects.
 Here are two examples of how to allocate the space for an obstack and
 initialize it.  First, an obstack that is a static variable:
 
-@example
+@smallexample
 static struct obstack myobstack;
 @dots{}
 obstack_init (&myobstack);
-@end example
+@end smallexample
 
 @noindent
 Second, an obstack that is itself dynamically allocated:
 
-@example
+@smallexample
 struct obstack *myobstack_ptr
   = (struct obstack *) xmalloc (sizeof (struct obstack));
 
 obstack_init (myobstack_ptr);
-@end example
+@end smallexample
 
 @node Allocation in an Obstack
 @subsection Allocation in an Obstack
@@ -825,7 +825,7 @@ requires you to specify an @var{obstack_ptr} as the first argument.
 For example, here is a function that allocates a copy of a string @var{str}
 in a specific obstack, which is the variable @code{string_obstack}:
 
-@example
+@smallexample
 struct obstack string_obstack;
 
 char *
@@ -836,7 +836,7 @@ copystring (char *string)
   memcpy (s, string, strlen (string));
   return s;
 @}
-@end example
+@end smallexample
 
 To allocate a block with specified contents, use the function
 @code{obstack_copy}, declared like this:
@@ -859,13 +859,13 @@ The @code{obstack_copy0} function is convenient for copying a sequence
 of characters into an obstack as a null-terminated string.  Here is an
 example of its use:
 
-@example
+@smallexample
 char *
 obstack_savestring (char *addr, size_t size)
 @{
   return obstack_copy0 (&myobstack, addr, size);
 @}
-@end example
+@end smallexample
 
 @noindent
 Contrast this with the previous example of @code{savestring} using
@@ -894,9 +894,9 @@ uninitialized obstack.  To free all storage in an obstack but leave it
 valid for further allocation, call @code{obstack_free} with the address
 of the first object allocated on the obstack:
 
-@example
+@smallexample
 obstack_free (obstack_ptr, first_object_allocated_ptr);
-@end example
+@end smallexample
 
 Recall that the objects in an obstack are grouped into chunks.  When all
 the objects in a chunk become free, the obstack library automatically
@@ -921,9 +921,9 @@ Calling the macros requires a special precaution: namely, the first
 operand (the obstack pointer) may not contain any side effects, because
 it may be computed more than once.  For example, if you write this:
 
-@example
+@smallexample
 obstack_alloc (get_obstack (), 4);
-@end example
+@end smallexample
 
 @noindent
 you will find that @code{get_obstack} may be called several times.
@@ -937,7 +937,7 @@ function without calling it.  An ordinary call uses the macro definition by
 default, but you can request the function definition instead by writing the
 function name in parentheses, as shown here:
 
-@example
+@smallexample
 char *x;
 void *(*funcp) ();
 /* @r{Use the macro}.  */
@@ -946,7 +946,7 @@ x = (char *) obstack_alloc (obptr, size);
 x = (char *) (obstack_alloc) (obptr, size);
 /* @r{Take the address of the function}.  */
 funcp = obstack_alloc;
-@end example
+@end smallexample
 
 @noindent
 This is the same situation that exists in ANSI C for the standard library
@@ -1043,9 +1043,9 @@ After it is finished, @code{obstack_object_size} will return zero.
 If you have started growing an object and wish to cancel it, you should
 finish it and then free it, like this:
 
-@example
+@smallexample
 obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
-@end example
+@end smallexample
 
 @noindent
 This has no effect if no object was growing.
@@ -1113,7 +1113,7 @@ start using the fast growth functions again.
 
 Here is an example:
 
-@example
+@smallexample
 @group
 void
 add_string (struct obstack *obstack, char *ptr, size_t len)
@@ -1136,7 +1136,7 @@ add_string (struct obstack *obstack, char *ptr, size_t len)
     @}
 @}
 @end group
-@end example
+@end smallexample
 
 @node Status of an Obstack
 @subsection Status of an Obstack
@@ -1175,9 +1175,9 @@ returns the same value as @code{obstack_base}.
 This function returns the size in bytes of the currently growing object.
 This is equivalent to
 
-@example
+@smallexample
 obstack_next_free (@var{obstack_ptr}) - obstack_base (@var{obstack_ptr})
-@end example
+@end smallexample
 @end deftypefun
 
 @node Obstacks Data Alignment
@@ -1205,9 +1205,9 @@ on any multiple of 1 (that is, no alignment is required).
 The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
 so you can alter the mask by assignment.  For example, this statement:
 
-@example
+@smallexample
 obstack_alignment_mask (obstack_ptr) = 0;
-@end example
+@end smallexample
 
 @noindent
 has the effect of turning off alignment processing in the specified obstack.
@@ -1242,10 +1242,10 @@ These two must be defined (as macros) or declared (as functions) in each
 source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
 Most often they are defined as macros like this:
 
-@example
+@smallexample
 #define obstack_chunk_alloc xmalloc
 #define obstack_chunk_free free
-@end example
+@end smallexample
 
 Note that these are simple macros (no arguments).  Macro definitions with
 arguments will not work!  It is necessary that @code{obstack_chunk_alloc}
@@ -1278,10 +1278,10 @@ smaller, but making it larger might improve efficiency if you are
 allocating many objects whose size is comparable to the chunk size.  Here
 is how to do so cleanly:
 
-@example
+@smallexample
 if (obstack_chunk_size (obstack_ptr) < @var{new_chunk_size})
   obstack_chunk_size (obstack_ptr) = @var{new_chunk_size};
-@end example
+@end smallexample
 
 @node Summary of Obstacks
 @subsection Summary of Obstack Functions
@@ -1414,7 +1414,7 @@ As an example of use of @code{alloca}, here is a function that opens a file
 name made from concatenating two argument strings, and returns a file
 descriptor or minus one signifying failure:
 
-@example
+@smallexample
 int
 open2 (char *str1, char *str2, int flags, int mode)
 @{
@@ -1423,13 +1423,13 @@ open2 (char *str1, char *str2, int flags, int mode)
   strcat (name, str2);
   return open (name, flags, mode);
 @}
-@end example
+@end smallexample
 
 @noindent
 Here is how you would get the same results with @code{malloc} and
 @code{free}:
 
-@example
+@smallexample
 int
 open2 (char *str1, char *str2, int flags, int mode)
 @{
@@ -1443,7 +1443,7 @@ open2 (char *str1, char *str2, int flags, int mode)
   free (name);
   return desc;
 @}
-@end example
+@end smallexample
 
 As you can see, it is simpler with @code{alloca}.  But @code{alloca} has
 other, more important advantages, and some disadvantages.
@@ -1478,7 +1478,7 @@ jumps out to the command level of your program using @code{longjmp}.
 Let's change @code{open2} (@pxref{Alloca Example}) to use this
 subroutine:@refill
 
-@example
+@smallexample
 int
 open2 (char *str1, char *str2, int flags, int mode)
 @{
@@ -1487,7 +1487,7 @@ open2 (char *str1, char *str2, int flags, int mode)
   strcat (name, str2);
   return open_or_report_error (name, flags, mode);
 @}
-@end example
+@end smallexample
 
 @noindent
 Because of the way @code{alloca} works, the storage it allocates is
@@ -1527,7 +1527,7 @@ is available for use on systems with this deficiency.
 In GNU C, you can replace most uses of @code{alloca} with an array of
 variable size.  Here is how @code{open2} would look then:
 
-@example
+@smallexample
 int open2 (char *str1, char *str2, int flags, int mode)
 @{
   char name[strlen (str1) + strlen (str2) + 1];
@@ -1535,7 +1535,7 @@ int open2 (char *str1, char *str2, int flags, int mode)
   strcat (name, str2);
   return open (name, flags, mode);
 @}
-@end example
+@end smallexample
 
 But @code{alloca} is not always equivalent to a variable-sized array, for
 several reasons:
index 0056700..47d5c3e 100644 (file)
@@ -252,9 +252,9 @@ nonzero, then @code{glob} doesn't give up right away when it can't read
 a directory; instead, it calls @var{errfunc} with two arguments, like
 this:
 
-@example
+@smallexample
 (*@var{errfunc}) (@var{filename}, @var{error-code})
-@end example
+@end smallexample
 
 @noindent
 The argument @var{filename} is the name of the directory that
@@ -563,8 +563,7 @@ The pattern didn't match the string.  This isn't really an error.
 @end table
 
 @node Regexp Subexpressions
-@c !!! I think this title is awkward -rm 
-@subsection Subexpressions Match Results
+@subsection Match Results with Subexpressions
 
 When @code{regexec} matches parenthetical subexpressions of
 @var{pattern}, it records which parts of @var{string} they match.  It
@@ -650,13 +649,14 @@ actually matches is near the end of the first word.  But it is
 @emph{considered} again in the second word, and fails to match there.
 @code{regexec} reports nonuse of the ``na'' subexpression.
 
-Another place where this rule applies is when @samp{\(ba\(na\)*s
-\|nefer\(ti\)* \)*} matches @samp{bananas nefertiti}.  The ``na''
-subexpression does match in the first word, but it doesn't match in the
-second word because the other alternative is used there.  Once again,
-the second repetition of the outer subexpression overrides the first,
-and within that second repetition, the ``na'' subexpression is not used.
-So @code{regexec} reports nonuse of the ``na'' subexpression.
+Another place where this rule applies is when the regular expression
+@w{@samp{\(ba\(na\)*s \|nefer\(ti\)* \)*}} matches @samp{bananas nefertiti}.
+The ``na'' subexpression does match in the first word, but it doesn't
+match in the second word because the other alternative is used there.
+Once again, the second repetition of the outer subexpression overrides
+the first, and within that second repetition, the ``na'' subexpression
+is not used.  So @code{regexec} reports nonuse of the ``na''
+subexpression.
 
 @node Regexp Cleanup
 @subsection POSIX Regexp Matching Cleanup
@@ -702,8 +702,10 @@ store the entire error message.  If this is less than @var{length}, then
 the error message was not truncated, and you can use it.  Otherwise, you
 should call @code{regerror} again with a larger buffer.
 
-@c !!! i wrote this example of how to do it right (i think) -- intro it. -rm
-@example
+Here is a function which uses @code{regerror}, but always dynamically
+allocates a buffer for the error message:
+
+@smallexample
 char *get_regerror (int errcode, regex_t *compiled)
 @{
   size_t length = regerror (errcode, compiled, NULL, 0);
@@ -711,7 +713,7 @@ char *get_regerror (int errcode, regex_t *compiled)
   (void) regerror (errcode, compiled, buffer, length);
   return buffer;
 @}
-@end example
+@end smallexample
 @end deftypefun
 
 @c !!!! this is not actually in the library....
@@ -767,19 +769,19 @@ from left to right:
 @item
 @cindex variable substitution
 @cindex substitution of variables and commands
-@dfn{Variable substitution}: The substitution of environment variables
-for references such as @samp{$foo}.
+@dfn{Variable substitution}: Environment variables are substituted for
+references such as @samp{$foo}.
 
 @item
 @cindex command substitution
-@dfn{Command substitution}: Replacement of constructs such as 
-@samp{`cat foo`} or @samp{$(cat foo)} with the output from the inner
-command.
+@dfn{Command substitution}: Constructs such as @w{@samp{`cat foo`}} and
+the equivalent @w{@samp{$(cat foo)}} are replaced with the output from
+the inner command.
 
 @item
 @cindex arithmetic expansion
-@dfn{Arithmetic expansion}: Replacement of constructs such as
-@samp{$(($x-1))} with the result of the arithmetic computation.
+@dfn{Arithmetic expansion}: Constructs such as @samp{$(($x-1))} are
+replaced with the result of the arithmetic computation.
 @end itemize
 
 @item
@@ -978,7 +980,7 @@ and use the results to run a shell command.  It also shows the use of
 @code{WRDE_APPEND} to concatenate the expansions and of @code{wordfree}
 to free the space allocated by @code{wordexp}.
 
-@example
+@smallexample
 int
 expand_and_execute (const char *program, const char *options)
 @{
@@ -1027,7 +1029,7 @@ expand_and_execute (const char *program, const char *options)
   wordfree (&result);
   return status;
 @}
-@end example
+@end smallexample
 
 In practice, since @code{wordexp} is executed by running a subshell, it
 would be faster to do this by concatenating the strings with spaces
index 4b07f90..ed5a402 100644 (file)
@@ -82,9 +82,9 @@ uses the @code{fork} function (@pxref{Creating a Process}) to create
 a child process.  The parent process writes data to the pipe, which is
 read by the child process.
 
-@example
+@smallexample
 @include pipe.c.texi
-@end example
+@end smallexample
 
 @node Pipe to a Subprocess
 @section Pipe to a Subprocess
@@ -138,9 +138,9 @@ Here is an example showing how to use @code{popen} and @code{pclose} to
 filter output through another program, in this case the paging program
 @code{more}.
 
-@example
+@smallexample
 @include popen.c.texi
-@end example
+@end smallexample
 
 @node FIFO Special Files
 @section FIFO Special Files
index 3ffcb4b..ed6e3fd 100644 (file)
@@ -34,7 +34,7 @@ is ``greater''.
 Here is an example of a comparison function which works with an array of
 numbers of type @code{double}:
 
-@example
+@smallexample
 int
 compare_doubles (const double *a, const double *b)
 @{
@@ -46,7 +46,7 @@ compare_doubles (const double *a, const double *b)
   else
     return 0;
 @}
-@end example
+@end smallexample
 
 The header file @file{stdlib.h} defines a name for the data type of
 comparison functions.  This is a GNU extension and thus defined only if
@@ -55,9 +55,9 @@ you request the GNU extensions.
 @comment stdlib.h
 @comment GNU
 @tindex comparison_fn_t
-@example
+@smallexample
 int comparison_fn_t (const void *, const void *);
-@end example
+@end smallexample
 
 @node Array Search Function, Array Sort Function, Comparison Functions, Searching and Sorting
 @section Array Search Function
@@ -130,14 +130,14 @@ Here is a simple example of sorting an array of doubles in numerical
 order, using the comparison function defined above (@pxref{Comparison
 Functions}):
 
-@example
+@smallexample
 @{
   double *array;
   int size;
   @dots{}
   qsort (array, size, sizeof (double), compare_doubles);
 @}
-@end example
+@end smallexample
 
 The @code{qsort} function derives its name from the fact that it was
 originally implemented using the algorithm ``quick sort''.
@@ -152,14 +152,14 @@ by comparing their @code{name} fields with the @code{strcmp} function.
 Then, we can look up individual objects based on their names.
 
 @comment This example is dedicated to the memory of Jim Henson.  RIP.
-@example
+@smallexample
 @include search.c.texi
-@end example
+@end smallexample
 
 @cindex Kermit the frog
 The output from this program looks like:
 
-@example
+@smallexample
 Animal, the animal
 Beaker, the human
 Camilla, the chicken
@@ -180,6 +180,6 @@ Zoot, the human
 Kermit, the frog
 Gonzo, the whatever
 Couldn't find Janice.
-@end example
+@end smallexample
 
 
index 954457c..2732b6f 100644 (file)
@@ -57,9 +57,9 @@ statement.
 
 Here is how the example program described above might be set up:  
 
-@example
+@smallexample
 @include setjmp.c.texi
-@end example
+@end smallexample
 
 The function @code{abort_to_main_loop} causes an immediate transfer of
 control back to the main loop of the program, no matter where it is
@@ -77,14 +77,14 @@ of @code{-1}.
 @need 250
 So, the general pattern for using @code{setjmp} looks something like:
 
-@example
+@smallexample
 if (setjmp (@var{buffer}))
   /* @r{Code to clean up after premature return.} */
   @dots{}
 else
   /* @r{Code to be executed normally after setting up the return point.} */
   @dots{}
-@end example
+@end smallexample
 
 @node Non-Local Details, Non-Local Exits and Signals, Non-Local Intro, Non-Local Exits
 @section Details of Non-Local Exits
index 62bbac2..6a3af57 100644 (file)
@@ -897,9 +897,9 @@ This is the type of signal handler functions.  Signal handlers take one
 integer argument specifying the signal number, and have return type
 @code{void}.  So, you should define handler functions like this:
 
-@example
+@smallexample
 void @var{handler} (int @code{signum}) @{ @dots{} @}
-@end example
+@end smallexample
 
 The name @code{sighandler_t} for this data type is a GNU extension.
 @end deftp
@@ -978,7 +978,7 @@ a handler for @code{SIGKILL} or @code{SIGSTOP}.
 Here is a simple example of setting up a handler to delete temporary
 files when certain fatal signals happen:
 
-@example
+@smallexample
 #include <signal.h>
 
 void
@@ -1002,7 +1002,7 @@ main (void)
     signal (SIGTERM, SIG_IGN);
   @dots{}
 @}
-@end example
+@end smallexample
 
 @noindent
 Note how if a given signal was previously set to be ignored, this code
@@ -1150,7 +1150,7 @@ In @ref{Basic Signal Handling}, we gave an example of establishing a
 simple handler for termination signals using @code{signal}.  Here is an
 equivalent example using @code{sigaction}:
 
-@example
+@smallexample
 #include <signal.h>
 
 void
@@ -1184,7 +1184,7 @@ main (void)
     sigaction (SIGTERM, &new_action, NULL);
   @dots{}
 @}
-@end example
+@end smallexample
 
 The program just loads the @code{new_action} structure with the desired
 parameters and passes it in the @code{sigaction} call.  The usage of
@@ -1198,7 +1198,7 @@ lets us examine the current action without specifying a new one.
 Here is another example.  It retrieves information about the current
 action for @code{SIGINT} without changing that action.
 
-@example
+@smallexample
 struct sigaction query_action;
 
 if (sigaction (SIGINT, NULL, &query_action) < 0)
@@ -1209,7 +1209,7 @@ else if (query_action.sa_handler == SIG_IGN)
   /* @r{@code{SIGINT} is ignored.} */
 else
   /* @r{A programmer-defined signal handler is in effect.} */
-@end example
+@end smallexample
 
 @node Flags for Sigaction
 @subsection Flags for @code{sigaction}
@@ -1296,7 +1296,7 @@ own signal handlers.
 Here is an example of how to establish a handler for @code{SIGHUP}, but
 not if @code{SIGHUP} is currently ignored:
 
-@example
+@smallexample
 @group
 @dots{}
 struct sigaction temp;
@@ -1310,7 +1310,7 @@ if (temp.sa_handler != SIG_IGN)
     sigaction (SIGHUP, &temp, NULL);
   @}
 @end group
-@end example
+@end smallexample
 
 @node Defining Handlers
 @section Defining Signal Handlers
@@ -1384,9 +1384,9 @@ the loop until it has noticed that a @code{SIGALRM} signal has arrived.
 This technique is useful because it allows the iteration in progress
 when the signal arrives to complete before the loop exits.
 
-@example
+@smallexample
 @include sigh1.c.texi
-@end example
+@end smallexample
 
 @node Termination in Handler
 @subsection Handlers That Terminate the Process
@@ -1399,7 +1399,7 @@ The cleanest way for a handler to terminate the process is to raise the
 same signal that ran the handler in the first place.  Here is how to do
 this:
 
-@example
+@smallexample
 volatile sig_atomic_t fatal_error_in_progress = 0;
 
 void
@@ -1431,7 +1431,7 @@ fatal_error_signal (int sig)
   raise (sig);
 @}
 @end group
-@end example
+@end smallexample
 
 @node Longjmp in Handler
 @subsection Nonlocal Control Transfer in Handlers
@@ -1458,7 +1458,7 @@ handler, or make their values consistent.
 Here is a rather schematic example showing the reinitialization of one
 global variable.
 
-@example
+@smallexample
 @group
 #include <signal.h>
 #include <setjmp.h>
@@ -1506,7 +1506,7 @@ read_data ()
   @}
 @}
 @end group
-@end example
+@end smallexample
 
 
 @node Signals in Handler
@@ -1565,7 +1565,7 @@ the fact that the number of signals recieved may not equal the number of
 child processes generate them.  It assumes that the program keeps track
 of all the child processes with a chain of structures as follows:
 
-@example
+@smallexample
 struct process
 @{
   struct process *next;
@@ -1582,21 +1582,21 @@ struct process
 @};
 
 struct process *process_list;
-@end example
+@end smallexample
 
 This example also uses a flag to indicate whether signals have arrived
 since some time in the past---whenever the program last cleared it to
 zero.
 
-@example
+@smallexample
 /* @r{Nonzero means some child's status has changed}
    @r{so look at @code{process_list} for the details.}  */
 int process_status_change;
-@end example
+@end smallexample
 
 Here is the handler itself:
 
-@example
+@smallexample
 void
 sigchld_handler (int signo)
 @{
@@ -1645,11 +1645,11 @@ sigchld_handler (int signo)
        @r{that have something to tell us.}  */
   @}
 @}
-@end example
+@end smallexample
 
 Here is the proper way to check the flag @code{process_status_change}:
 
-@example
+@smallexample
 if (process_status_change) @{
   struct process *p;
   process_status_change = 0;
@@ -1658,7 +1658,7 @@ if (process_status_change) @{
       @dots{} @r{Examine @code{p->status}} @dots{}
     @}
 @}
-@end example
+@end smallexample
 
 @noindent
 It is vital to clear the flag before examining the list; otherwise, if a
@@ -1686,7 +1686,7 @@ previous check.  The advantage of this method is that different parts of
 the program can check independently, each part checking whether there
 has been a signal since that part last checked.
 
-@example
+@smallexample
 sig_atomic_t process_status_change;
 
 sig_atomic_t last_process_status_change;
@@ -1703,7 +1703,7 @@ sig_atomic_t last_process_status_change;
       @}
   @}
 @}
-@end example
+@end smallexample
 
 @node Nonreentrancy
 @subsection Signal Handling and Nonreentrant Functions 
@@ -1852,14 +1852,14 @@ block all signals around any access that had better not be interrupted
 @end menu
 
 @node Non-atomic Example
-@subsubsection Example of Problems with Non-Atomic Access
+@subsubsection Problems with Non-Atomic Access
 
 Here is an example which shows what can happen if a signal handler runs
 in the middle of modifying a variable.  (Interrupting the reading of a
 variable can also lead to paradoxical results, but here we only show
 writing.)
 
-@example
+@smallexample
 #include <signal.h>
 #include <stdio.h>
 
@@ -1887,7 +1887,7 @@ main (void)
      @}
 @}
 @end group
-@end example
+@end smallexample
 
 This program fills @code{memory} with zeros, ones, zeros, ones,
 alternating forever; meanwhile, once per second, the alarm signal handler
@@ -2086,7 +2086,7 @@ before stopping.  You might set this up like this:
 @comment the example is written, the signal that is raise'd will be delivered
 @comment as soon as the SIGTSTP handler returns, which is fine.
 
-@example
+@smallexample
 #include <signal.h>
 
 /* @r{When a stop signal arrives, set the action back to the default
@@ -2121,7 +2121,7 @@ main (void)
   @dots{}
 @}
 @end group
-@end example
+@end smallexample
 
 @strong{Portability note:} @code{raise} was invented by the ANSI C
 committee.  Older systems may not support it, so using @code{kill} may
@@ -2184,11 +2184,12 @@ for some special system processes.  Otherwise, send the signal to all
 processes with the same effective user ID.
 @end table
 
-A process can send a signal to itself with @w{@code{kill (getpid(),
-@var{signum});}}.  If @code{kill} is used by a process to send a signal to
-itself, and the signal is not blocked, then @code{kill} delivers at
-least one signal (which might be some other pending unblocked signal
-instead of the signal @var{signum}) to that process before it returns.
+A process can send a signal @var{signum} to itself with a call like
+@w{@code{kill (getpid(), @var{signum})}}.  If @code{kill} is used by a
+process to send a signal to itself, and the signal is not blocked, then
+@code{kill} delivers at least one signal (which might be some other
+pending unblocked signal instead of the signal @var{signum}) to that
+process before it returns.
 
 The return value from @code{kill} is zero if the signal can be sent
 successfully.  Otherwise, no signal is sent, and a value of @code{-1} is
@@ -2269,9 +2270,9 @@ for the child to complete its initialization.  The child process tells
 the parent when it is ready by sending it a @code{SIGUSR1} signal, using
 the @code{kill} function.
 
-@example
+@smallexample
 @include sigusr.c.texi
-@end example
+@end smallexample
 
 This example uses a busy wait, which is bad, because it wastes CPU
 cycles that other programs could otherwise use.  It is better to ask the
@@ -2531,7 +2532,7 @@ You can prevent additional @code{SIGALRM} signals from arriving in the
 meantime by wrapping the critical part of the code with calls to
 @code{sigprocmask}, like this:
 
-@example
+@smallexample
 /* @r{This variable is set by the SIGALRM signal handler.} */
 volatile sig_atomic_t flag = 0;
 
@@ -2562,7 +2563,7 @@ main (void)
     @}
 @}
 @end group
-@end example
+@end smallexample
 
 @node Blocking for Handler
 @subsection Blocking Signals for a Handler
@@ -2589,7 +2590,7 @@ structure.
 
 Here is an example:
 
-@example
+@smallexample
 #include <signal.h>
 #include <stddef.h>
 
@@ -2610,7 +2611,7 @@ install_handler (void)
   setup_action.sa_flags = 0;
   sigaction (SIGTSTP, &setup_action, NULL);
 @}
-@end example
+@end smallexample
 
 This is more reliable than blocking the other signals explicitly in the
 code for the handler.  If you block signals explicity in the handler,
@@ -2651,7 +2652,7 @@ that signal is not blocked is almost certainly bad design.
 
 Here is an example.
 
-@example
+@smallexample
 #include <signal.h>
 #include <stddef.h>
 
@@ -2673,7 +2674,7 @@ if (sigismember (&waiting_mask, SIGINT)) @{
 else if (sigismember (&waiting_mask, SIGTSTP)) @{
   /* @r{User has tried to stop the process.} */
 @}
-@end example
+@end smallexample
 
 Remember that if there is a particular signal pending for your process,
 additional signals of that same type that arrive in the meantime might
@@ -2691,7 +2692,7 @@ Instead of blocking a signal using the library facilities, you can get
 almost the same results by making the handler set a flag to be tested
 later, when you ``unblock''.  Here is an example:
 
-@example
+@smallexample
 /* @r{If this flag is nonzero, don't handle the signal right away.} */
 volatile sig_atomic_t signal_pending;
 
@@ -2723,7 +2724,7 @@ update_mumble (int frob)
   if (defer_signal == 0 && signal_pending != 0)
     raise (signal_pending);
 @}
-@end example
+@end smallexample
 
 Note how the particular signal that arrives is stored in
 @code{signal_pending}.  That way, we can handle several types of
@@ -2747,11 +2748,11 @@ It is absolutely vital to decrement @code{defer_signal} before testing
 @code{signal_pending}, because this avoids a subtle bug.  If we did
 these things in the other order, like this,
 
-@example
+@smallexample
   if (defer_signal == 1 && signal_pending != 0)
     raise (signal_pending);
   defer_signal--;
-@end example
+@end smallexample
 
 @noindent
 then a signal arriving in between the @code{if} statement and the decrement
@@ -2842,14 +2843,14 @@ and then resume real work.  Even if you arrange for the signal handler
 to cooperate by setting a flag, you still can't use @code{pause}
 reliably.  Here is an example of this problem:
 
-@example
+@smallexample
 /* @r{@code{usr_interrupt} is set by the signal handler.}  */
 if (!usr_interrupt)
   pause ();
 
 /* @r{Do work once the signal arrives.}  */
 @dots{}
-@end example
+@end smallexample
 
 @noindent
 This has a bug: the signal could arrive after the variable
@@ -2860,14 +2861,14 @@ You can put an upper limit on the excess waiting by using @code{sleep}
 in a loop, instead of using @code{pause}.  (@xref{Sleeping}, for more
 about @code{sleep}.)  Here is what this looks like:
 
-@example
+@smallexample
 /* @r{@code{usr_interrupt} is set by the signal handler.}
 while (!usr_interrupt)
   sleep (1);
 
 /* @r{Do work once the signal arrives.}  */
 @dots{}
-@end example
+@end smallexample
 
 For some purposes, that is good enough.  But with a little more
 complexity, you can wait reliably until a particular signal handler is
@@ -2907,7 +2908,7 @@ The return value and error conditions are the same as for @code{pause}.
 With @code{sigsuspend}, you can replace the @code{pause} or @code{sleep}
 loop in the previous section with something completely reliable:
 
-@example
+@smallexample
 sigset_t mask, oldmask;
 
 @dots{}
@@ -2923,7 +2924,7 @@ sigprocmask (SIG_BLOCK, &mask, &oldmask);
 while (!usr_interrupt)
   sigsuspend (&oldmask);
 sigprocmask (SIG_UNBLOCK, &mask, NULL);
-@end example
+@end smallexample
 
 This last piece of code is a little tricky.  The key point to remember
 here is that when @code{sigsuspend} returns, it resets the process's
@@ -3081,10 +3082,10 @@ This macro returns a signal mask that has the bit for signal @var{signum}
 set.  You can bitwise-OR the results of several calls to @code{sigmask}
 together to specify more than one signal.  For example,
 
-@example
+@smallexample
 (sigmask (SIGTSTP) | sigmask (SIGSTOP)
  | sigmask (SIGTTIN) | sigmask (SIGTTOU))
-@end example
+@end smallexample
 
 @noindent
 specifies a mask that includes all the job-control stop signals.
@@ -3093,16 +3094,16 @@ specifies a mask that includes all the job-control stop signals.
 @comment signal.h
 @comment BSD
 @deftypefun int sigblock (int @var{mask})
-This function is the equivalent of @code{sigprocmask} (@pxref{Process
-Signal Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the
-signals specified by @var{mask} to the calling process's signal mask.
-The return value is the previous set of blocked signals.
+This function is equivalent to @code{sigprocmask} (@pxref{Process Signal
+Mask}) with a @var{how} argument of @code{SIG_BLOCK}: it adds the
+signals specified by @var{mask} to the calling process's set of blocked
+signals.  The return value is the previous set of blocked signals.
 @end deftypefun
 
 @comment signal.h
 @comment BSD
 @deftypefun int sigsetmask (int @var{mask})
-This function is the equivalent of @code{sigprocmask} (@pxref{Process
+This function equivalent to @code{sigprocmask} (@pxref{Process
 Signal Mask}) with a @var{how} argument of @code{SIG_SETMASK}: it sets
 the calling process's signal mask to @var{mask}.  The return value is
 the previous set of blocked signals.
index 51eaed8..dc11e8e 100644 (file)
@@ -292,7 +292,7 @@ identifies the format of the data which follows.
 
 @item char sa_data[14]
 This is the actual socket address data, which is format-dependent.  Its
-length is also format-dependent, and may well be more than 14.  The
+length also depends on the format, and may well be more than 14.  The
 length 14 of @code{sa_data} is essentially arbitrary.
 @end table
 @end deftp
@@ -343,7 +343,7 @@ implemented.  We will document those that really work, as we receive
 information about how to use them.
 
 @node Setting Address
-@subsection Setting a Socket's Address
+@subsection Setting the Address of a Socket
 
 @pindex sys/socket.h
 Use the @code{bind} function to assign an address to a socket.  The
@@ -391,7 +391,7 @@ of the socket.
 @end deftypefun
 
 @node Reading Address
-@subsection Reading a Socket's Address
+@subsection Reading the Address of a Socket
 
 @pindex sys/socket.h
 Use the function @code{getsockname} to examine the address of an
@@ -536,9 +536,9 @@ the file name string.
 Here is an example showing how to create and name a socket in the file
 namespace.
 
-@example
+@smallexample
 @include mkfsock.c.texi
-@end example
+@end smallexample
 
 @node Internet Namespace
 @section The Internet Namespace
@@ -945,9 +945,9 @@ functions to set @code{errno}, but use of @code{h_errno} is compatible
 with other systems.)  Before using @code{h_errno}, you must declare it
 like this:
 
-@example
+@smallexample
 extern int h_errno;
-@end example
+@end smallexample
 
 Here are the error codes that you may find in @code{h_errno}:
 
@@ -1328,16 +1328,16 @@ the program is running on.  Rather than finding and using the machine's
 Internet address, this example specifies @code{INADDR_ANY} as the host
 address; the system replaces that with the machine's actual address.
 
-@example
+@smallexample
 @include mkisock.c.texi
-@end example
+@end smallexample
 
 Here is another example, showing how you can fill in a @code{sockaddr_in}
 structure, given a host name string and a port number:
 
-@example
+@smallexample
 @include isockad.c.texi
-@end example
+@end smallexample
 
 @node Misc Namespaces
 @section Other Namespaces
@@ -1979,9 +1979,9 @@ stream socket in the Internet namespace.  It doesn't do anything
 particularly interesting once it has connected to the server; it just
 sends a text string to the server and exits.
 
-@example
+@smallexample
 @include inetcli.c.texi
-@end example
+@end smallexample
 
 @node Server Example
 @subsection Byte Stream Connection Server Example
@@ -2002,9 +2002,9 @@ client shutting down its end of the connection).
 This program uses @code{make_socket} and @code{init_sockaddr} to set
 up the socket address; see @ref{Inet Example}.
 
-@example
+@smallexample
 @include inetsrv.c.texi
-@end example
+@end smallexample
 
 @node Out-of-Band Data
 @subsection Out-of-Band Data
@@ -2051,14 +2051,14 @@ data is ``cancel everything sent so far''.  Here is how you can test,
 in the receiving process, whether any ordinary data was sent before
 the mark:
 
-@example
+@smallexample
 success = ioctl (socket, SIOCATMARK, &result);
-@end example
+@end smallexample
 
 Here's a function to discard any ordinary data preceding the
 out-of-band mark:
 
-@example
+@smallexample
 int
 discard_until_mark (int socket)
 @{
@@ -2083,7 +2083,7 @@ discard_until_mark (int socket)
         perror ("read");
     @}
 @}
-@end example
+@end smallexample
 
 If you don't want to discard the ordinary data preceding the mark, you
 may need to read some of it anyway, to make room in internal system
@@ -2092,7 +2092,7 @@ and get an @code{EWOULDBLOCK} error, try reading some ordinary data
 (saving it so that you can use it when you want it) and see if that
 makes room.  Here is an example:
 
-@example
+@smallexample
 struct buffer
 @{
   char *buffer;
@@ -2172,7 +2172,7 @@ read_oob (int socket)
       @}
     @}
 @}
-@end example
+@end smallexample
 
 @node Datagrams
 @section Datagram Socket Operations
@@ -2312,9 +2312,9 @@ messages to arrive, bouncing each message back to the sender.
 Obviously, this isn't a particularly useful program, but it does show
 the general ideas involved.
 
-@example
+@smallexample
 @include filesrv.c.texi
-@end example
+@end smallexample
 
 @node Example Receiver
 @subsection Example of Reading Datagrams
@@ -2328,9 +2328,9 @@ a message back to the client.  Since the socket has no associated
 connection state, the only way the server can do this is by
 referencing the name of the client.
 
-@example
+@smallexample
 @include filecli.c.texi
-@end example
+@end smallexample
 
 Keep in mind that datagram socket communications are unreliable.  In
 this example, the client program waits indefinitely if the message
@@ -2401,9 +2401,9 @@ talk      dgram   udp     wait    root    /libexec/talkd  talkd
 
 An entry has this format:
 
-@example
+@smallexample
 @var{service} @var{style} @var{protocol} @var{wait} @var{username} @var{program} @var{arguments}
-@end example
+@end smallexample
 
 The @var{service} field says which service this program provides.  It
 should be the name of a service defined in @file{/etc/services}.
@@ -2511,7 +2511,8 @@ This function is used to set the socket option @var{optname} at level
 @var{level} for socket @var{socket}.  The value of the option is passed
 in the buffer @var{optval}, which has size @var{optlen}.
 
-The return value and error codes are the same as for @code{getsockopt}.
+The return value and error codes for @code{setsockopt} are the same as
+for @code{getsockopt}.
 @end deftypefun
 
 @node Socket-Level Options
index 2841363..2f415a0 100644 (file)
@@ -35,9 +35,9 @@ You can define @code{main} either to take no arguments, or to take two
 arguments that represent the command line arguments to the program, like
 this:
 
-@example
+@smallexample
 int main (int @var{argc}, char *@var{argv}[])
-@end example
+@end smallexample
 
 @cindex argc (program argument count)
 @cindex argv (program argument vector)
@@ -251,14 +251,14 @@ is used later in the program.
 A second loop is used to process the remaining non-option arguments.
 @end itemize
 
-@example
+@smallexample
 @include testopt.c.texi
-@end example
+@end smallexample
 
 Here are some examples showing what this program prints with different
 combinations of arguments:
 
-@example
+@smallexample
 % testopt
 aflag = 0, bflag = 0, cvalue = (null)
 
@@ -293,7 +293,7 @@ Non-option argument -b
 % testopt -a -
 aflag = 1, bflag = 0, cvalue = (null)
 Non-option argument -
-@end example
+@end smallexample
 
 @node Long Options
 @subsection Parsing Long Options
@@ -387,9 +387,9 @@ When @code{getopt_long} has no more options to handle, it returns
 @node Long Option Example
 @subsection Example of Parsing Long Options
 
-@example
+@smallexample
 @include longopt.c.texi
-@end example
+@end smallexample
 
 @node Environment Variables
 @section Environment Variables
@@ -450,12 +450,11 @@ The value of an environment variable can be accessed with the
 @comment ANSI
 @deftypefun {char *} getenv (const char *@var{name})
 This function returns a string that is the value of the environment
-variable @var{name}.  You must not modify this string.  In some systems
-not using the GNU library, it might be overwritten by subsequent calls
-to @code{getenv} (but not by any other library function).
-@c !!! never overwritten on any unix system
-If the environment variable @var{name} is not defined, the value is a
-null pointer.
+variable @var{name}.  You must not modify this string.  In some non-Unix
+systems not using the GNU library, it might be overwritten by subsequent
+calls to @code{getenv} (but not by any other library function).  If the
+environment variable @var{name} is not defined, the value is a null
+pointer.
 @end deftypefun
 
 
@@ -549,9 +548,9 @@ current directory (@pxref{Working Directory}).
 
 A typical value for this environment variable might be a string like:
 
-@example
-:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local:/usr/local/bin
-@end example
+@smallexample
+:/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
+@end smallexample
 
 This means that if the user tries to execute a program named @code{foo},
 the system will look for files named @file{foo}, @file{/bin/foo},
@@ -800,9 +799,9 @@ for SunOS, and may not be supported by other implementations.
 Here's a trivial program that illustrates the use of @code{exit} and
 @code{atexit}:
 
-@example
+@smallexample
 @include atexit.c.texi
-@end example
+@end smallexample
 
 @noindent
 When this program is executed, it just prints the message and exits.
index f67a253..63b5177 100644 (file)
@@ -275,13 +275,7 @@ streams, see @ref{Stream Buffering}.
 
 @cindex writing to a stream, by characters
 This section describes functions for performing character- and
-line-oriented output.  Largely for historical compatibility, there are
-several variants of these functions, but as a matter of style (and for
-simplicity!) we suggest you stick with using @code{fputc} and
-@code{fputs}, and perhaps @code{putc} and @code{putchar}.
-@c !!! this "style" shit is completely bogus.  you should use the
-@c function most appropriate for what you are doing.  use putc for
-@c efficiency; there is never a reason to use fputc.
+line-oriented output.
 
 These functions are declared in the header file @file{stdio.h}.
 @pindex stdio.h
@@ -300,13 +294,14 @@ character @var{c} is returned.
 @deftypefun int putc (int @var{c}, FILE *@var{stream})
 This is just like @code{fputc}, except that most systems implement it as
 a macro, making it faster.  One consequence is that it may evaluate the
-@var{stream} argument more than once.
+@var{stream} argument more than once.  @code{putc} is usually the best
+function to use for writing a single character.
 @end deftypefun
 
 @comment stdio.h
 @comment ANSI
 @deftypefun int putchar (int @var{c})
-The @code{putchar} function is equivalent to @code{fputc} with
+The @code{putchar} function is equivalent to @code{putc} with
 @code{stdout} as the value of the @var{stream} argument.
 @end deftypefun
 
@@ -323,11 +318,11 @@ a non-negative value.
 
 For example:
 
-@example
+@smallexample
 fputs ("Are ", stdout);
 fputs ("you ", stdout);
 fputs ("hungry?\n", stdout);
-@end example
+@end smallexample
 
 @noindent
 outputs the text @samp{Are you hungry?} followed by a newline.
@@ -354,13 +349,7 @@ recommend you use @code{fwrite} instead (@pxref{Block Input/Output}).
 
 @cindex reading from a stream, by characters
 This section describes functions for performing character- and
-line-oriented input.  Again, there are several variants of these
-functions, some of which are considered obsolete stylistically.  It's
-suggested that you stick with @code{fgetc}, @code{getline}, and maybe
-@code{getc}, @code{getchar} and @code{fgets}.
-@c !!! this "style" shit is also completely bogus. use getc for speed;
-@c there is never a reason to use fgetc.
-
+line-oriented input.
 These functions are declared in the header file @file{stdio.h}.
 @pindex stdio.h
 
@@ -376,16 +365,17 @@ the stream @var{stream} and returns its value, converted to an
 @comment stdio.h
 @comment ANSI
 @deftypefun int getc (FILE *@var{stream})
-This is just like @code{fgetc}, except that it is permissible (and typical)
-for it to be implemented as a macro that evaluates the @var{stream}
-argument more than once.
-@c !!! and it's faster
+This is just like @code{fgetc}, except that it is permissible (and
+typical) for it to be implemented as a macro that evaluates the
+@var{stream} argument more than once.  @code{getc} is often highly
+optimized, so it is usually the best function to use to read a single
+character.
 @end deftypefun
 
 @comment stdio.h
 @comment ANSI
 @deftypefun int getchar (void)
-The @code{getchar} function is equivalent to @code{fgetc} with @code{stdin}
+The @code{getchar} function is equivalent to @code{getc} with @code{stdin}
 as the value of the @var{stream} argument.
 @end deftypefun
 
@@ -393,7 +383,7 @@ Here is an example of a function that does input using @code{fgetc}.  It
 would work just as well using @code{getc} instead, or using
 @code{getchar ()} instead of @code{fgetc (stdin)}.
 
-@example
+@smallexample
 int
 y_or_n_p (const char *question)
 @{
@@ -418,7 +408,7 @@ y_or_n_p (const char *question)
     fputs ("Please answer y or n:", stdout);
   @}
 @}
-@end example
+@end smallexample
 
 @comment stdio.h
 @comment SVID
@@ -521,14 +511,15 @@ The function @code{gets} reads characters from the stream @code{stdin}
 up to the next newline character, and stores them in the string @var{s}.
 The newline character is discarded (note that this differs from the
 behavior of @code{fgets}, which copies the newline character into the
-string).
-
-@c !!! say what it returns!! either S if winning, or NULL if losing.
-
-@strong{Warning:}  The @code{gets} function is @strong{very dangerous} 
-because it provides no protection against overflowing the string @var{s}.
-The GNU library includes it for compatibility only.  You should 
-@strong{always} use @code{fgets} or @code{getline} instead.
+string).  If @code{gets} encounters a read error or end-of-file, it
+returns a null pointer; otherwise it returns @var{s}.
+
+@strong{Warning:} The @code{gets} function is @strong{very dangerous}
+because it provides no protection against overflowing the string
+@var{s}.  The GNU library includes it for compatibility only.  You
+should @strong{always} use @code{fgets} or @code{getline} instead.  To
+remind you of this, the linker (if using GNU @code{ld}) will issue a
+warning whenever you use @code{gets}.
 @end deftypefn
 
 @node Unreading
@@ -560,10 +551,10 @@ stream reading a file that contains just six characters, the letters
 @samp{foobar}.  Suppose you have read three characters so far.  The
 situation looks like this:
 
-@example
+@smallexample
 f  o  o  b  a  r
          ^
-@end example
+@end smallexample
 
 @noindent
 so the next input character will be @samp{b}.
@@ -572,12 +563,12 @@ so the next input character will be @samp{b}.
 If instead of reading @samp{b} you unread the letter @samp{o}, you get a
 situation like this:
 
-@example
+@smallexample
 f  o  o  b  a  r
          |
       o--
       ^
-@end example
+@end smallexample
 
 @noindent
 so that the next input characters will be @samp{o} and @samp{b}.
@@ -586,12 +577,12 @@ so that the next input characters will be @samp{o} and @samp{b}.
 @c @group
 If you unread @samp{9} instead of @samp{o}, you get this situation:
 
-@example
+@smallexample
 f  o  o  b  a  r
          |
       9--
       ^
-@end example
+@end smallexample
 
 @noindent
 so that the next input characters will be @samp{9} and @samp{b}.
@@ -610,7 +601,9 @@ The @code{ungetc} function pushes back the character @var{c} onto the
 input stream @var{stream}.  So the next input from @var{stream} will
 read @var{c} before anything else.
 
-@c !!! if c==EOF, ungetc does nothing and returns EOF
+If @var{c} is @code{EOF}, @code{ungetc} does nothing and just returns
+@code{EOF}.  This lets call @code{ungetc} with the return value of
+@code{getc} without needing to check for an error from @code{getc}.
 
 The character that you push back doesn't have to be the same as the last
 character that was actually read from the stream.  In fact, it isn't
@@ -632,9 +625,8 @@ called, any pending pushed-back characters are discarded.
 
 Unreading a character on a stream that is at end of file clears the
 end-of-file indicator for the stream, because it makes the character of
-input available.  Reading that character will set the end-of-file
-indicator again.
-@c !!! no, it won't; EOF is not set until you try & fail to read a char.
+input available.  After you read that character, trying to read again
+will encounter end of file.
 @end deftypefun
 
 Here is an example showing the use of @code{getc} and @code{ungetc} to
@@ -642,7 +634,7 @@ skip over whitespace characters.  When this function reaches a
 non-whitespace character, it unreads that character to be seen again on
 the next read operation on the stream.
 
-@example
+@smallexample
 #include <stdio.h>
 
 void
@@ -656,7 +648,7 @@ skip_whitespace (FILE *stream)
   while (isspace (c));
   ungetc (c, stream);
 @}
-@end example
+@end smallexample
 
 @node Formatted Output
 @section Formatted Output
@@ -709,20 +701,20 @@ a @samp{%} character in the template cause subsequent arguments to be
 formatted and written to the output stream.  For example,
 @cindex conversion specifications (@code{printf})
 
-@example
+@smallexample
 int pct = 37;
 char filename[] = "foo.txt";
 printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
         filename, pct);
-@end example
+@end smallexample
 
 @noindent
 produces output like
 
-@example
+@smallexample
 Processing of `foo.txt' is 37% finished.
 Please be patient.
-@end example
+@end smallexample
 
 This example shows the use of the @samp{%d} conversion to specify that
 an @code{int} argument should be printed in decimal notation, the
@@ -770,9 +762,9 @@ a template string.
 The conversion specifications in a @code{printf} template string have
 the general form:
 
-@example
+@smallexample
 % @var{flags} @var{width} @r{[} . @var{precision} @r{]} @var{type} @var{conversion}
-@end example
+@end smallexample
 
 For example, in the conversion specifier @samp{%-10.8ld}, the @samp{-}
 is a flag, @samp{10} specifies the field width, the precision is
@@ -799,13 +791,11 @@ field is @emph{not} truncated.  Normally, the output is right-justified
 within the field.
 @cindex minimum field width (@code{printf})
 
-The GNU library's version of @code{printf} also allows you to specify a
-field width of @samp{*}.  This means that the next argument in the
-argument list (before the actual value to be printed) is used as the
-field width.  The value must be an @code{int}.  Other C library versions may
-not recognize this syntax.
-@c !!! ANSI specifies *. it is not a GNU extension.  if the passed
-@c number is negative, it sets the - flag and is negated to get the width.
+You can also specify a field width of @samp{*}.  This means that the
+next argument in the argument list (before the actual value to be
+printed) is used as the field width.  The value must be an @code{int}.
+If the value is negative, this means to set the @samp{-} flag (see
+below) and to use the absolute value as the field width.
 
 @item 
 An optional @dfn{precision} to specify the number of digits to be
@@ -814,15 +804,12 @@ consists of a period (@samp{.}) followed optionally by a decimal integer
 (which defaults to zero if omitted).
 @cindex precision (@code{printf})
 
-The GNU library's version of @code{printf} also allows you to specify a
-precision of @samp{*}.  This means that the next argument in the
-argument list (before the actual value to be printed) is used as the
-precision.  The value must be an @code{int}.  If you specify @samp{*}
-for both the field width and precision, the field width argument
-precedes the precision argument.  Other C library versions may not
-recognize this syntax.
-@c !!! ANSI specifies *. it is not a GNU extension.  if the passed
-@c number is negative, it is ignored.
+You can also specify a precision of @samp{*}.  This means that the next
+argument in the argument list (before the actual value to be printed) is
+used as the precision.  The value must be an @code{int}, and is ignored
+if it is negative.  If you specify @samp{*} for both the field width and
+precision, the field width argument precedes the precision argument.
+Other C library versions may not recognize this syntax.
 
 @item
 An optional @dfn{type modifier character}, which is used to specify the
@@ -949,12 +936,14 @@ character instead.  Since the @samp{+} flag ensures that the result
 includes a sign, this flag is ignored if you supply both of them.
 
 @item @samp{#}
-For the @samp{%o} conversion, this forces the leading digit to be @samp{0},
-as if by increasing the precision.  For @samp{%x} or @samp{%X}, this
-prefixes a leading @samp{0x} or @samp{0X} (respectively) to the result.
-This doesn't do anything useful for the @samp{%d}, @samp{%i}, or @samp{%u}
-conversions.
-@c !!! should mention this is the fmt grokked by strtoul, and xref to it.
+For the @samp{%o} conversion, this forces the leading digit to be
+@samp{0}, as if by increasing the precision.  For @samp{%x} or
+@samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
+to the result.  This doesn't do anything useful for the @samp{%d},
+@samp{%i}, or @samp{%u} conversions.  Using this flag produces output
+which can be parsed by the @code{strtoul} function (@pxref{Parsing of
+Integers}) and @code{scanf} with the @code{%i} conversion
+(@pxref{Numeric Input Conversions}).
 
 @item @samp{0}
 Pad the field with zeros instead of spaces.  The zeros are placed after
@@ -1001,20 +990,20 @@ the sole purpose of @samp{%Z} is to specify the data type
 
 Here is an example.  Using the template string:
 
-@example
+@smallexample
 |%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
-@end example
+@end smallexample
 
 @noindent
 to print numbers using the different options for the @samp{%d}
 conversion gives results like:
 
-@example
+@smallexample
 |    0|0    |   +0|+0   |    0|00000|     |   00|0|
 |    1|1    |   +1|+1   |    1|00001|    1|   01|1|
 |   -1|-1   |   -1|-1   |   -1|-0001|   -1|  -01|-1|
 |100000|100000|+100000| 100000|100000|100000|100000|100000|
-@end example
+@end smallexample
 
 In particular, notice what happens in the last case where the number
 is too large to fit in the minimum field width specified.
@@ -1022,15 +1011,15 @@ is too large to fit in the minimum field width specified.
 Here are some more examples showing how unsigned integers print under
 various format options, using the template string:
 
-@example
+@smallexample
 "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
-@end example
+@end smallexample
 
-@example
+@smallexample
 |    0|    0|    0|    0|    0|  0x0|  0X0|0x00000000|
 |    1|    1|    1|    1|   01|  0x1|  0X1|0x00000001|
 |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
-@end example
+@end smallexample
 
 
 @node Floating-Point Conversions
@@ -1115,13 +1104,13 @@ Here are some examples showing how numbers print using the various
 floating-point conversions.  All of the numbers were printed using
 this template string:
 
-@example
+@smallexample
 "|%12.4f|%12.4e|%12.4g|\n"
-@end example
+@end smallexample
 
 Here is the output:
 
-@example
+@smallexample
 |      0.0000|  0.0000e+00|           0|
 |      1.0000|  1.0000e+00|           1|
 |     -1.0000| -1.0000e+00|          -1|
@@ -1131,7 +1120,7 @@ Here is the output:
 |  12345.0000|  1.2345e+04|   1.234e+04|
 | 100000.0000|  1.0000e+05|       1e+05|
 | 123456.0000|  1.2346e+05|   1.234e+05|
-@end example
+@end smallexample
 
 Notice how the @samp{%g} conversion drops trailing zeros.
 
@@ -1146,9 +1135,9 @@ flag can be used to specify left-justification in the field, but no
 other flags are defined, and no precision or type modifier can be given.
 For example:
 
-@example
+@smallexample
 printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
-@end example
+@end smallexample
 
 @noindent
 prints @samp{hello}.
@@ -1161,9 +1150,9 @@ written to the output stream.  The @samp{-} flag can be used to specify
 left-justification in the field, but no other flags or type modifiers
 are defined for this conversion.  For example:
 
-@example
+@smallexample
 printf ("%3s%-6s", "no", "where");
-@end example
+@end smallexample
 
 @noindent
 prints @samp{ nowhere }.
@@ -1176,16 +1165,16 @@ argument intentionally.
 The @samp{%m} conversion prints the string corresponding to the error
 code in @code{errno}.  @xref{Error Messages}.  Thus:
 
-@example
+@smallexample
 fprintf (stderr, "can't open `%s': %m\n", filename);
-@end example
+@end smallexample
 
 @noindent
 is equivalent to:
 
-@example
+@smallexample
 fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
-@end example
+@end smallexample
 
 @noindent
 The @samp{%m} conversion is a GNU C library extension.
@@ -1200,9 +1189,9 @@ as if a @samp{%#x} conversion were used.  Null pointers print as
 
 For example:
 
-@example
+@smallexample
 printf ("%p", "testing");
-@end example
+@end smallexample
 
 @noindent
 prints @samp{0x} followed by a hexadecimal number---the address of the
@@ -1223,17 +1212,17 @@ flags, field width, or precision are permitted.
 
 For example,
 
-@example
+@smallexample
 int nchar;
 printf ("%d %s%n\n", 3, "bears", &nchar);
-@end  example
+@end smallexample
 
 @noindent
 prints:
 
-@example
+@smallexample
 3 bears
-@end example
+@end smallexample
 
 @noindent
 and sets @code{nchar} to @code{7}, because @samp{3 bears} is seven 
@@ -1250,7 +1239,10 @@ precision, or type modifiers are permitted.
 
 This section describes how to call @code{printf} and related functions.
 Prototypes for these functions are in the header file @file{stdio.h}.
-@c !!! mention you must have prototypes for these fns (because varargs).
+Because these functions take a variable number of arguments, you
+@emph{must} declare prototypes for them before using them.  Of course,
+the easiest way to make sure you have all the right prototypes is to
+just include @file{stdio.h}.
 @pindex stdio.h
 
 @comment stdio.h
@@ -1320,7 +1312,8 @@ make_message (char *name, char *value)
     @{
       /* @r{Try to print in the allocated space.} */
       int nchars = snprintf (buffer, size,
-                             "value of %s is %s", name, value);
+                             "value of %s is %s",
+                             name, value);
       /* @r{If that worked, return the string.} */
       if (nchars < size)
         return buffer;
@@ -1415,10 +1408,11 @@ arguments again through that pointer.  Calling @code{vprintf} does not
 destroy the argument list of your function, merely the particular
 pointer that you passed to it.
 
-The GNU library does not have such restrictions.  You can safely continue
-to fetch arguments from a @code{va_list} pointer after passing it to
-@code{vprintf}, and @code{va_end} is a no-op.
-@c !!! but note that you will see the args vprintf already saw.
+The GNU library does not have such restrictions.  You can safely
+continue to fetch arguments from a @code{va_list} pointer after passing
+it to @code{vprintf}, and @code{va_end} is a no-op.  (Note, however,
+that subsequent @code{va_arg} calls will fetch the same arguments which
+@code{vprintf} previously used.)
 
 Prototypes for these functions are declared in @file{stdio.h}.
 @pindex stdio.h
@@ -1474,7 +1468,7 @@ with a prefix indicating the name of the program
 (@pxref{Error Messages}, for a description of 
 @code{program_invocation_short_name}).
 
-@example
+@smallexample
 @group
 #include <stdio.h>
 #include <stdarg.h>
@@ -1491,14 +1485,14 @@ eprintf (char *template, ...)
   va_end (ap);
 @}
 @end group
-@end example
+@end smallexample
 
 @noindent
 You could call @code{eprintf} like this:
 
-@example
+@smallexample
 eprintf ("file `%s' does not exist\n", filename);
-@end example
+@end smallexample
 
 @node Parsing a Template String
 @subsection Parsing a Template String
@@ -1594,10 +1588,10 @@ from @code{PA_LAST}.  For example, if you have data types @samp{foo}
 and @samp{bar} with their own specialized @code{printf} conversions,
 you could define encodings for these types as:
 
-@example
+@smallexample
 #define PA_FOO  PA_LAST
 #define PA_BAR  (PA_LAST + 1)
-@end example
+@end smallexample
 @end table
 
 Here are the flag bits that modify a basic type.  They are combined with
@@ -1653,7 +1647,7 @@ assume this is part of an interpreter which contains arguments of type
 @code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
 perhaps others which are not valid here).
 
-@example
+@smallexample
 /* @r{Test whether the @var{nargs} specified objects}
    @r{in the vector @var{args} are valid}
    @r{for the format string @var{format}:}
@@ -1713,7 +1707,7 @@ validate_args (char *format, int nargs, OBJECT *args)
   @}
   return 1;
 @}
-@end example
+@end smallexample
 
 @node Customizing Printf
 @section Customizing @code{printf}
@@ -1725,7 +1719,7 @@ The GNU C library lets you define your own custom conversion specifiers
 for @code{printf} template strings, to teach @code{printf} clever ways
 to print the important data structures of your program.
 
-The way you do this is by registering the conversion with
+The way you do this is by registering the conversion with the function
 @code{register_printf_function}; see @ref{Registering New Conversions}.
 One of the arguments you pass to this function is a pointer to a handler
 function that produces the actual output; see @ref{Defining the Output
@@ -1874,10 +1868,10 @@ which are passed as arguments to @code{register_printf_function}.
 
 You should define your handler functions with a prototype like:
 
-@example
+@smallexample
 int @var{function} (FILE *stream, const struct printf_info *info,
                     va_list *ap_pointer)
-@end example
+@end smallexample
 
 The @code{stream} argument passed to the handler function is the stream to
 which it should write output.
@@ -1916,10 +1910,10 @@ application, you should also define a function to pass as the
 
 You should define these functions with a prototype like:
 
-@example
+@smallexample
 int @var{function} (const struct printf_info *info,
                     size_t n, int *argtypes)
-@end example
+@end smallexample
 
 The return value from the function should be the number of arguments the
 conversion expects, up to a maximum of @var{n}.  The function should
@@ -1945,17 +1939,17 @@ arguments, including the pointer value and the name stored in the data
 structure.  The @samp{%W} conversion supports the minimum field width and
 left-justification options, but ignores everything else.
 
-@example
+@smallexample
 @include rprintf.c.texi
-@end example
+@end smallexample
 
 The output produced by this program looks like:
 
-@example
+@smallexample
 |<Widget 0xffeffb7c: mywidget>|
 |      <Widget 0xffeffb7c: mywidget>|
 |<Widget 0xffeffb7c: mywidget>      |
-@end example
+@end smallexample
 
 @node Formatted Input
 @section Formatted Input
@@ -2019,7 +2013,7 @@ The @code{scanf} function is typically used for things like reading in
 the contents of tables.  For example, here is a function that uses
 @code{scanf} to initialize an array of @code{double}:
 
-@example
+@smallexample
 void
 readarray (double *array, int n)
 @{
@@ -2028,7 +2022,7 @@ readarray (double *array, int n)
     if (scanf (" %lf", &(array[i])) != 1)
       invalid_input_error ();
 @}
-@end example
+@end smallexample
 
 The formatted input functions are not used as frequently as the
 formatted output functions.  Partly, this is because it takes some care
@@ -2063,9 +2057,9 @@ this is not the case, a matching failure occurs.
 The conversion specifications in a @code{scanf} template string
 have the general form:
 
-@example
+@smallexample
 % @var{flags} @var{width} @var{type} @var{conversion}
-@end example
+@end smallexample
 
 In more detail, an input conversion specification consists of an initial
 @samp{%} character followed in sequence by:
@@ -2129,24 +2123,24 @@ language defines for specifying an integer constant.  @xref{Numeric
 Input Conversions}.
 
 @item @samp{%o}
-Matches an unsigned integer in octal radix.  @xref{Numeric
-Input Conversions}.
+Matches an unsigned integer written in octal radix.
+@xref{Numeric Input Conversions}.
 
 @item @samp{%u}
-Matches an unsigned integer in decimal radix.  @xref{Numeric
-Input Conversions}.
+Matches an unsigned integer written in decimal radix.
+@xref{Numeric Input Conversions}.
 
 @item @samp{%x}, @samp{%X}
-Matches an unsigned integer in hexadecimal radix.  @xref{Numeric
-Input Conversions}.
+Matches an unsigned integer written in hexadecimal radix.
+@xref{Numeric Input Conversions}.
 
 @item @samp{%e}, @samp{%f}, @samp{%g}, @samp{%E}, @samp{%G}
 Matches an optionally signed floating-point number.  @xref{Numeric Input
 Conversions}.
 
 @item @samp{%s}
-Matches a string of non-whitespace characters.  @xref{String Input
-Conversions}.
+Matches a string containing only non-whitespace characters.
+@xref{String Input Conversions}.
 
 @item @samp{%[}
 Matches a string of characters that belong to a specified set.
@@ -2193,8 +2187,9 @@ The @samp{%i} conversion matches an optionally signed integer in any of
 the formats that the C language defines for specifying an integer
 constant.  The syntax that is recognized is the same as that for the
 @code{strtol} function (@pxref{Parsing of Integers}) with the value
-@code{0} for the @var{base} argument.
-@c !!! mention printf %#[xod] generates something this can read.
+@code{0} for the @var{base} argument.  (You can print integers in this
+syntax with @code{printf} by using the @samp{#} flag character with the
+@samp{%x}, @samp{%o}, or @samp{%d} conversion.  @xref{Integer Conversions}.)
 
 For example, any of the strings @samp{10}, @samp{0xa}, or @samp{012}
 could be read in as integers under the @samp{%i} conversion.  Each of
@@ -2295,9 +2290,9 @@ at the end of the text that it reads.
 
 For example, reading the input:
 
-@example
+@smallexample
  hello, world
-@end example
+@end smallexample
 
 @noindent
 with the conversion @samp{%10c} produces @code{" hello, wo"}, but
@@ -2377,7 +2372,7 @@ Here is an example of using the @samp{a} flag with the @samp{%[@dots{}]}
 conversion specification to read a ``variable assignment'' of the form
 @samp{@var{variable} = @var{value}}.
 
-@example
+@smallexample
 @{
   char *variable, *value;
 
@@ -2390,7 +2385,7 @@ conversion specification to read a ``variable assignment'' of the form
 
   @dots{}
 @}
-@end example
+@end smallexample
 
 @node Other Input Conversions
 @subsection Other Input Conversions
@@ -3307,20 +3302,20 @@ supply the length of the string as the @var{size} argument.
 Here is an example of using @code{fmemopen} to create a stream for
 reading from a string:
 
-@example
+@smallexample
 @include memopen.c.texi
-@end example
+@end smallexample
 
 This program produces the following output:
 
-@example
+@smallexample
 Got f
 Got o
 Got o
 Got b
 Got a
 Got r
-@end example
+@end smallexample
 
 @comment stdio.h
 @comment GNU
@@ -3346,16 +3341,16 @@ already written fills the intervening space with zeroes.
 
 Here is an example of using @code{open_memstream}:
 
-@example
+@smallexample
 @include memstrm.c.texi
-@end example
+@end smallexample
 
 This program produces the following output:
 
-@example
+@smallexample
 buf = `hello', size = 5
 buf = `hello, world', size = 12
-@end example
+@end smallexample
 
 @c @group  Invalid outside @example.
 @node Obstack Streams
@@ -3390,9 +3385,9 @@ But how do you find out how long the object is?  You can get the length
 in bytes by calling @code{obstack_object_size} (@pxref{Status of an
 Obstack}), or you can null-terminate the object like this:
 
-@example
+@smallexample
 obstack_1grow (@var{obstack}, 0);
-@end example
+@end smallexample
 
 Whichever one you do, you must do it @emph{before} calling
 @code{obstack_finish}.  (You can do both if you wish.)
@@ -3400,7 +3395,7 @@ Whichever one you do, you must do it @emph{before} calling
 
 Here is a sample function that uses @code{open_obstack_stream}:
 
-@example
+@smallexample
 char *
 make_message_string (const char *a, int b)
 @{
@@ -3413,7 +3408,7 @@ make_message_string (const char *a, int b)
   obstack_1grow (&message_obstack, 0);
   return obstack_finish (&message_obstack);
 @}
-@end example
+@end smallexample
 
 @node Custom Streams
 @subsection Programming Your Own Custom Streams
@@ -3480,8 +3475,9 @@ discarded.
 @item cookie_seek_function *seek
 This is the function that performs the equivalent of file positioning on
 the cookie.  If the value is a null pointer instead of a function, calls
-to @code{fseek} on this stream return an @code{ESPIPE} error.
-@c !!! fseek works if you never seek outside the buffer
+to @code{fseek} on this stream can only seek to locations within the
+buffer; any attempt to seek outside the buffer will return an
+@code{ESPIPE} error.
 
 @item cookie_close_function *close
 This function performs any appropriate cleanup on the cookie when
@@ -3513,9 +3509,9 @@ that a custom stream needs.
 
 You should define the function to read data from the cookie as:
 
-@example
+@smallexample
 ssize_t @var{reader} (void *@var{cookie}, void *@var{buffer}, size_t @var{size})
-@end example
+@end smallexample
 
 This is very similar to the @code{read} function; see @ref{I/O
 Primitives}.  Your function should transfer up to @var{size} bytes into
@@ -3525,9 +3521,9 @@ an error.
 
 You should define the function to write data to the cookie as:
 
-@example
+@smallexample
 ssize_t @var{writer} (void *@var{cookie}, const void *@var{buffer}, size_t @var{size})
-@end example
+@end smallexample
 
 This is very similar to the @code{write} function; see @ref{I/O
 Primitives}.  Your function should transfer up to @var{size} bytes from
@@ -3537,9 +3533,9 @@ value of @code{-1} to indicate an error.
 You should define the function to perform seek operations on the cookie
 as:
 
-@example
+@smallexample
 int @var{seeker} (void *@var{cookie}, fpos_t *@var{position}, int @var{whence})
-@end example
+@end smallexample
 
 For this function, the @var{position} and @var{whence} arguments are
 interpreted as for @code{fgetpos}; see @ref{Portable Positioning}.  In
@@ -3555,9 +3551,9 @@ to indicate an error.
 You should define the function to do cleanup operations on the cookie
 appropriate for closing the stream as:
 
-@example
+@smallexample
 int @var{cleaner} (void *@var{cookie})
-@end example
+@end smallexample
 
 Your function should return @code{-1} to indicate an error, and @code{0}
 otherwise.