branch-1_4 doc cleanup

[Eric Blake]

The texinfo manual recommends against TABs in documentation (they don't format 
well).  But our testsuite expects literal TABs when matching dump output.  So 
here's the compromise I am checking in:

2006-06-22  Eric Blake  <address@hidden>

        * doc/m4.texinfo: Whitespace cleanup.  TABs are evil in texinfo.
        (tabchar): New macro, so that 'make check' still works.
        (Invoking m4): Document that ignored compatibility options -B, -S,
        and -T each consume an argument.
        * checks/get-them: Honor @tabchar{}.

Index: checks/get-them
===================================================================
RCS file: /sources/m4/m4/checks/Attic/get-them,v
retrieving revision 1.1.1.1.2.1
diff -u -r1.1.1.1.2.1 get-them
--- checks/get-them     31 Mar 2005 11:20:17 -0000      1.1.1.1.2.1
+++ checks/get-them     22 Jun 2006 17:43:30 -0000
@@ -1,6 +1,6 @@
 #!/bin/sh
 # Extract all examples from the manual source.
-# Copyright (C) 1992, 2005 Free Software Foundation, Inc.
+# Copyright (C) 1992, 2005, 2006 Free Software Foundation, Inc.
 
 # This script is for use with GNU awk.
 
@@ -60,6 +60,7 @@
     prefix = "";
   gsub("@@", "@", $0);
   gsub("@comment.*", "", $0);
+  gsub("@tabchar{}", "\t", $0);
   printf("%s%s\n", prefix, $0) >> file;
 }
 
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.21
diff -u -r1.1.1.1.2.21 m4.texinfo
--- doc/m4.texinfo      18 Jun 2006 21:36:09 -0000      1.1.1.1.2.21
+++ doc/m4.texinfo      22 Jun 2006 17:43:30 -0000
@@ -9,9 +9,15 @@
 
 @include version.texi
 
address@hidden The testsuite expects literal tab output in some examples, but
address@hidden literal tabs in texinfo lead to formatting issues.
address@hidden tabchar
+@      @c
address@hidden macro
+
 @dircategory GNU programming tools
 @direntry
-* m4: (m4).                    A powerful macro processor.
+* m4: (m4).                     A powerful macro processor.
 @end direntry
 
 @ifnottex
@@ -471,9 +477,9 @@
 @itemx --silent
 Suppress warnings about missing or superfluous arguments in macro calls.
 
address@hidden -B
address@hidden -S
address@hidden -T
address@hidden address@hidden
address@hidden address@hidden
address@hidden address@hidden
 These options are present for compatibility with System V @code{m4}, but
 do nothing in this implementation.
 
@@ -1564,10 +1570,10 @@
 @comment ignore
 @example
 define(`forloop',
-       `pushdef(`$1', `$2')_forloop(`$1',`$2',`$3',`$4')popdef(`$1')')
+  `pushdef(`$1', `$2')_forloop(`$1', `$2', `$3', `$4')popdef(`$1')')
 define(`_forloop',
-       `$4`'ifelse($1, `$3', ,
-                  `define(`$1', incr($1))_forloop(`$1',`$2',`$3',`$4')')')
+  `$4`'ifelse($1, `$3', ,
+    `define(`$1', incr($1))_forloop(`$1', `$2', `$3', `$4')')')
 @end example
 
 Notice the careful use of quotes.  Only three macro arguments are
@@ -1621,10 +1627,10 @@
 define(`foo', `Hello world.')
 @result{}
 dumpdef(`foo')
address@hidden: `Hello world.'
address@hidden:@tabchar{}`Hello world.'
 @result{}
 dumpdef(`define')
address@hidden: <define>
address@hidden:@tabchar{}<define>
 @result{}
 @end example
 
@@ -1638,7 +1644,7 @@
 pushdef(`f', ``$0'1')pushdef(`f', ``$0'2')
 @result{}
 f(popdef(`f')dumpdef(`f'))
address@hidden: ``$0'1'
address@hidden:@tabchar{}``$0'1'
 @result{}f2
 f(popdef(`f')dumpdef(`f'))
 @error{}m4.input:7: m4: Undefined name f
@@ -2803,7 +2809,7 @@
 define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
 define(`capitalize1',
        `regexp(`$1', `^\(\w\)\(\w*\)',
-               `upcase(`\1')`'downcase(`\2')')')dnl
+              `upcase(`\1')`'downcase(`\2')')')dnl
 define(`capitalize',
        `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
 capitalize(`GNUs not Unix')
@@ -2848,16 +2854,16 @@
 @example
 forloop(`i', 1, 10, `format(`%6d squared is %10d
 ', i, eval(i**2))')
address@hidden     1 squared is     1
address@hidden     2 squared is     4
address@hidden     3 squared is     9
address@hidden     4 squared is    16
address@hidden     5 squared is    25
address@hidden     6 squared is    36
address@hidden     7 squared is    49
address@hidden     8 squared is    64
address@hidden     9 squared is    81
address@hidden    10 squared is   100
address@hidden     1 squared is          1
address@hidden     2 squared is          4
address@hidden     3 squared is          9
address@hidden     4 squared is         16
address@hidden     5 squared is         25
address@hidden     6 squared is         36
address@hidden     7 squared is         49
address@hidden     8 squared is         64
address@hidden     9 squared is         81
address@hidden    10 squared is        100
 @end example
 
 The builtin @code{format} is modeled after the ANSI C @samp{printf}
@@ -3722,4 +3728,6 @@
 @c Local Variables:
 @c fill-column: 72
 @c ispell-local-dictionary: "american"
address@hidden indent-tabs-mode: nil
address@hidden whitespace-check-buffer-indent: nil
 @c End: