Re: Paragraph indentation suppression

[Simon Law]

Third time's the charm.

        Here, I'll even include a proper change log this time.

2003-04-08  Simon Law  <address@hidden>

        * doc/texinfo.tex (\firstparagraphindent): implement suppression
        of the indentation of the first paragraph.
        (\dofirstparagraphindent): for parsing arguments.
        (\suppressfirstparagraphindent, \gobblefirstindent): does the 
        actual gobbling of indentation.
        (\group, \setupverbatim, \dofootnote): force \everypar to use
        the suppression for every paragraph.
        (\footnote): Compensate for the hanging-indent side-effect.
        (\numhead, \apphead, \unnmhead): ensures the suppression occurs.
        * makeinfo/cmds.c (command_table): add "firstparagraphindent"
        (as cm_firstparagraphindent)
        (set_firstparagraphindent, cm_firstparagraphindent): implement
        @firstparagraphindent parsing of options.
        * makeinfo/makeinfo.c (long_options): add "no-first-par-indent"
        (as &no_first_par_indent).
        * makeinfo/makeinfo.h: declare "no_first_par_indent".
        * makeinfo/sectioning.c (sectioning_underscore): suppress
        indentation.
        * doc/texinfo.txi: document it.

        * doc/texinfo.tex (\indent): override \indent primitive to
        disable \gobblefirstindent.
        (\ptexindent): for saving/restoring \indent in @tex.
        * makeinfo/cmds.c (command_table): add "indent" (as cm_indent).
        (cm_indent): un-inhibit_paragraph_indentation.
        * doc/texinfo.txi: document it.

        * doc/texinfo.txi: take advantage of @firstparagraphindent.

        * doc/texinfo.txi (Conventions): remove extra vertical space
        from bulleted itemize.

        * makeinfo/cmds.c (command_table): fix "novalidate" option.

Index: doc/texinfo.tex
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.tex,v
retrieving revision 1.67
diff -u -r1.67 texinfo.tex
--- doc/texinfo.tex     22 Mar 2003 16:50:15 -0000      1.67
+++ doc/texinfo.tex     9 Apr 2003 03:53:50 -0000
@@ -3,7 +3,7 @@
 % Load plain if necessary, i.e., if running under initex.
 \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
 %
-\def\texinfoversion{2003-03-22.08}
+\def\texinfoversion{2003-04-08.23}
 %
 % Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
@@ -95,6 +95,7 @@
 \let\ptexslash=\/
 \let\ptexstar=\*
 \let\ptext=\t
+\let\ptexindent=\indent
 
 % If this character appears in an error message or help string, it
 % starts a new line in the output.
@@ -608,7 +609,7 @@
     % and the first line afterwards is too small.  But we can't put the
     % strut in \Egroup, since there it would be on a line by itself.
     % Hence this just inserts a strut at the beginning of each line.
-    \everypar = {\strut}%
+    \everypar = {\gobblefirstindent\strut}%
     %
     % Since we have a strut on every line, we don't need any of TeX's
     % normal interline spacing.
@@ -866,6 +867,35 @@
   \parindent = \defaultparindent
 }
 
+% @firstparagraphindent NCHARS
+% We'll use ems for NCHARS like @paragraphindent.
+\let\suppressfirstparagraphindent=\relax
+\let\gobblefirstindent=\relax
+\newdimen\currentparindent
+\def\suppressword{suppress}
+\def\defaultword{default}
+\def\firstparagraphindent{\parsearg\dofirstparagraphindent}
+\def\dofirstparagraphindent#1{%
+  \def\temp{#1}%
+  \ifx\temp\suppressword
+    \gdef\suppressfirstparagraphindent{%
+      \gdef\gobblefirstindent{%
+        \kern-\parindent
+        \global\let\gobblefirstindent=\relax
+      }%
+      \gdef\indent{%
+        \global\let\gobblefirstindent=\relax
+        \global\let\indent=\ptexindent
+      }%
+      \global\everypar = {\gobblefirstindent}%
+    }%
+  \else\ifx\temp\defaultword
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @firstparagraphindent `\temp'}%
+  \fi\fi
+}
+
 % @exampleindent NCHARS
 % We'll use ems for NCHARS like @paragraphindent.
 % It seems @exampleindent asis isn't necessary, but
@@ -3721,6 +3751,7 @@
     \numberedsubsubseczzz{#2}
   \fi
 \fi
+\suppressfirstparagraphindent
 }
 
 % like \numhead, but chooses appendix heading levels
@@ -3740,6 +3771,7 @@
     \appendixsubsubseczzz{#2}
   \fi
 \fi
+\suppressfirstparagraphindent
 }
 
 % like \numhead, but chooses numberless heading levels
@@ -3759,6 +3791,7 @@
     \unnumberedsubsubseczzz{#2}
   \fi
 \fi
+\suppressfirstparagraphindent
 }
 
 % @chapter, @appendix, @unnumbered.
@@ -4436,6 +4469,7 @@
   \let\/=\ptexslash
   \let\*=\ptexstar
   \let\t=\ptext
+  \let\indent=\ptexindent
   %
   \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
   \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%
@@ -4758,7 +4792,7 @@
   % make each space count
   % must do in this order:
   \obeylines \uncatcodespecials \sepspaces
-  \everypar{\starttabbox}%
+  \everypar{\gobblefirstindent\starttabbox}%
 }
 
 % Do the @verb magic: verbatim text is quoted by unique 
@@ -6146,6 +6180,7 @@
 %
 % Auto-number footnotes.  Otherwise like plain.
 \gdef\footnote{%
+  \indent
   \global\advance\footnoteno by address@hidden
   \edef\thisfootno{$^{\the\footnoteno}$}%
   %
@@ -6198,7 +6233,7 @@
   %
   % Hang the footnote text off the number.  Use \everypar in case the
   % footnote extends for more than one paragraph.
-  \everypar = {\hang}%
+  \everypar = {\gobblefirstindent\hang}%
   \textindent{\thisfootno}%
   %
   % Don't crash into the line above the footnote text.  Since this
Index: doc/texinfo.txi
===================================================================
RCS file: /cvsroot/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.36
diff -u -r1.36 texinfo.txi
--- doc/texinfo.txi     31 Mar 2003 13:54:56 -0000      1.36
+++ doc/texinfo.txi     9 Apr 2003 03:53:59 -0000
@@ -29,6 +29,7 @@
 
 @footnotestyle separate
 @paragraphindent 2
address@hidden suppress
 @c finalout
 
 @comment %**end of header
@@ -257,6 +258,7 @@
 * documentdescription::         Document summary for the HTML output.
 * setchapternewpage::           Start chapters on right-hand pages.
 * paragraphindent::             Specify paragraph indentation.
+* firstparagraphindent::        Suppress indentation of the first paragraph.
 * exampleindent::               Specify environment indentation.
 
 Ending a Texinfo File
@@ -372,6 +374,7 @@
 * exdent::                      Undo indentation on a line.
 * flushleft & flushright::      Pushing text flush left or flush right.
 * noindent::                    Preventing paragraph indentation.
+* indent::                      Forcing paragraph indentation.
 * cartouche::                   Drawing rounded rectangles around examples.
 
 Lists and Tables
@@ -1245,6 +1248,9 @@
 @xref{Conditionals}.
 
 @item
address@hidden
address@hidden@baselineskip
address@hidden iftex
 @cindex Tabs; don't use!
 @quotation
 @strong{Caution:} Do not use tab characters in a Texinfo file (except in
@@ -3668,6 +3674,7 @@
 * documentdescription::         Document summary for the HTML output.
 * setchapternewpage::           Start chapters on right-hand pages.
 * paragraphindent::             Specify paragraph indentation.
+* firstparagraphindent::        Suppress indentation of the first paragraph.
 * exampleindent::               Specify environment indentation.
 @end menu
 
@@ -3779,7 +3786,7 @@
 
 
 @node paragraphindent
address@hidden Paragraph Indenting
address@hidden @code{@@paragraphindent}: Paragraph Indenting
 @cindex Indenting paragraphs, control of
 @cindex Paragraph indentation control
 @findex paragraphindent
@@ -3824,6 +3831,50 @@
 @xref{Refilling Paragraphs}, for further information.
 
 
address@hidden firstparagraphindent
address@hidden @code{@@firstparagraphindent}: Suppress Indentation of the First 
Paragraph
address@hidden First paragraph, suppressing indentation of
address@hidden Suppressing first paragraph indentation
address@hidden Preventing first paragraph indentation
address@hidden Indenting, suppressing of first paragraph
address@hidden firstparagraphindent
+
+As you can see, the first paragraph in any section is never indented.
+Indentation is meant to be a paragraph separator, which means that it
+is unnecessary when a new section begins.  In fact, it is a typographical
+error to indent the first paragraph.
+
+In order to preserve compatibility with older versions of Texinfo,
+the default behaviour is to indent the first paragraph.  However, the
address@hidden option is recommended.
+
address@hidden
+@@firstparagraphindent @var{indent}
address@hidden example
+
+The first paragraph is indented according to the value of @var{indent}:
+
address@hidden @asis
address@hidden @code{suppress}
+Prevents the first paragraph from being indented.  This option is
+ignored if @code{@@paragraphindent asis} is in effect.
+
address@hidden @code{default}
+Leaves the indentation as-is.  By default, this will respect the
+Paragraph Indentation set by an @code{@@paragraphindent} command.
+(@pxref{paragraphindent})
+
address@hidden table
+
+Like @code{@@paragraphindent}, the default value of @var{indent} 
+is @code{default}.  In HTML output, the value of 
address@hidden@@firstparagraphinput} is ignored.
+
+Similiarily, it is best to write the @code{@@firstparagraphindent}
+command before the end-of-header line at the beginning of a Texinfo
+file.  @xref{Start of Header}.
+
+
 @node exampleindent
 @subsection @code{@@exampleindent}: Environment Indenting
 @cindex Indenting environments
@@ -7522,6 +7573,7 @@
 * exdent::                      Undo indentation on a line.
 * flushleft & flushright::      Pushing text flush left or flush right.
 * noindent::                    Preventing paragraph indentation.
+* indent::                      Forcing paragraph indentation.
 * cartouche::                   Drawing rounded rectangles around examples.
 @end menu
 
@@ -8019,6 +8071,9 @@
 
 @node noindent
 @section @code{@@noindent}: Omitting Indentation
address@hidden Omitting indentation
address@hidden Suppressing indentation
address@hidden Indentation, omitting
 @findex noindent
 
 An example or other inclusion can break a paragraph into segments.
@@ -8078,6 +8133,32 @@
 paragraphs (@pxref{Command Syntax}).
 
 
address@hidden indent
address@hidden @code{@@indent}: Forcing Indentation.
address@hidden Forcing indentation
address@hidden Inserting indentation
address@hidden Indentation, forcing
address@hidden indent
+
address@hidden
+To complement the @code{@@noindent} command (@pxref{noindent}), Texinfo
+provides the @code{@@indent} command that forces a paragraph to be
+indented.  This paragraph is indented using an @code{@@indent} command.
+
+It is best to write @code{@@indent} on a line by itself, since in most
+environments, spaces following the command will not be ignored.  It's ok
+to use it at the beginning of a line, with text following, outside of
+any environment.
+
+To adjust the number of blank lines properly in the Info file output,
+remember that the line containing @code{@@indent} does not generate a
+blank line, and neither does the @code{@@end example} line.
+
+Do not put braces after an @code{@@indent} command; they are not
+necessary, since @code{@@indent} is a command used outside of
+paragraphs (@pxref{Command Syntax}).
+
+
 @node cartouche
 @section @code{@@cartouche}: Rounded Rectangles Around Examples
 @findex cartouche
@@ -14218,6 +14299,12 @@
 @code{makeinfo} and then discarded.  This option is used by
 @command{texi2dvi} if you are using an old version of @file{texinfo.tex}
 that does not support @code{@@macro}.
+
address@hidden --no-first-par-indent
address@hidden --no-first-par-indent
+Never indents the first paragraph of any section.  This option overrides 
+the value set in a Texinfo file by an
address@hidden@@firstparagraphindent} command (@pxref{firstparagraphindent}).  
 
 @item --no-headers
 @opindex --no-headers
Index: makeinfo/cmds.c
===================================================================
RCS file: /cvsroot/texinfo/texinfo/makeinfo/cmds.c,v
retrieving revision 1.17
diff -u -r1.17 cmds.c
--- makeinfo/cmds.c     7 Mar 2003 19:22:52 -0000       1.17
+++ makeinfo/cmds.c     9 Apr 2003 03:53:59 -0000
@@ -56,7 +56,8 @@
   cm_anchor (), cm_node (), cm_menu (), cm_xref (), cm_ftable (),
   cm_vtable (), cm_pxref (), cm_inforef (), cm_uref (), cm_email (),
   cm_quotation (), cm_display (), cm_smalldisplay (), cm_itemize (),
-  cm_enumerate (), cm_tab (), cm_table (), cm_itemx (), cm_noindent (),
+  cm_enumerate (), cm_tab (), cm_table (), cm_itemx (), 
+  cm_noindent (), cm_indent (),
   cm_setfilename (), cm_br (), cm_sp (), cm_page (), cm_group (),
   cm_center (), cm_ref (), cm_include (), cm_bye (), cm_item (), cm_end (),
   cm_kindex (), cm_cindex (), cm_findex (), cm_pindex (), cm_vindex (),
@@ -66,7 +67,8 @@
   cm_defcodeindex (), cm_result (), cm_expansion (), cm_equiv (),
   cm_print (), cm_error (), cm_point (), cm_today (), cm_flushleft (),
   cm_flushright (), cm_finalout (), cm_cartouche (), cm_detailmenu (),
-  cm_multitable (), cm_settitle (), cm_titlefont (), cm_titlepage (), cm_tie 
(), cm_tt (),
+  cm_multitable (), cm_settitle (), cm_titlefont (), cm_titlepage (), 
+  cm_tie (), cm_tt (),
   cm_verbatim (), cm_verbatiminclude ();
 
 /* Conditionals. */
@@ -74,7 +76,10 @@
 void cm_value (), cm_ifeq ();
 
 /* Options. */
-static void cm_paragraphindent (), cm_exampleindent ();
+static void 
+  cm_paragraphindent (),
+  cm_firstparagraphindent (),
+  cm_exampleindent ();
 
 /* Internals. */
 static void cm_obsolete ();
@@ -220,6 +225,7 @@
   { "file", cm_code, BRACE_ARGS },
   { "finalout", cm_no_op, NO_BRACE_ARGS },
   { "findex", cm_findex, NO_BRACE_ARGS },
+  { "firstparagraphindent", cm_firstparagraphindent, NO_BRACE_ARGS },
   { "flushleft", cm_flushleft, NO_BRACE_ARGS },
   { "flushright", cm_flushright, NO_BRACE_ARGS },
   { "footnote", cm_footnote, NO_BRACE_ARGS}, /* self-arg eater */
@@ -248,6 +254,7 @@
   { "ignore", command_name_condition, NO_BRACE_ARGS },
   { "image", cm_image, BRACE_ARGS },
   { "include", cm_include, NO_BRACE_ARGS },
+  { "indent", cm_indent, NO_BRACE_ARGS },
   { "inforef", cm_inforef, BRACE_ARGS },
   { "insertcopying", cm_insert_copying, NO_BRACE_ARGS },
   { "item", cm_item, NO_BRACE_ARGS },
@@ -269,7 +276,7 @@
   { "need", cm_ignore_line, NO_BRACE_ARGS },
   { "node", cm_node, NO_BRACE_ARGS },
   { "noindent", cm_noindent, NO_BRACE_ARGS },
-  { "noindent", cm_novalidate, NO_BRACE_ARGS },
+  { "novalidate", cm_novalidate, NO_BRACE_ARGS },
   { "nwnode", cm_node, NO_BRACE_ARGS },
   { "o", cm_special_char, BRACE_ARGS },
   { "oddfooting", cm_ignore_line, NO_BRACE_ARGS },
@@ -995,6 +1002,13 @@
     inhibit_paragraph_indentation = -1;
 }
 
+/* This says to indentation the next paragraph. */
+void
+cm_indent ()
+{
+  inhibit_paragraph_indentation = 0;
+}
+
 /* I don't know exactly what to do with this.  Should I allow
    someone to switch filenames in the middle of output?  Since the
    file could be partially written, this doesn't seem to make sense.
@@ -1398,6 +1412,33 @@
 
   get_rest_of_line (1, &arg);
   if (set_paragraph_indent (arg) != 0)
+    line_error (_("Bad argument to %c%s"), COMMAND_PREFIX, command);
+
+  free (arg);
+}
+
+/* @firstparagraphindent: suppress indentation in the first paragraph. */
+static int
+set_firstparagraphindent (string)
+     char *string;
+{
+  if (strcmp (string, "default") == 0 || strcmp (string, _("default")) == 0)
+    ;
+  else if (strcmp (string, "suppress") == 0 
+           || strcmp (string, _("suppress")) == 0)
+    no_first_par_indent = 1;
+  else
+    return -1;
+  return 0;
+}
+
+static void
+cm_firstparagraphindent ()
+{
+  char *arg;
+
+  get_rest_of_line (1, &arg);
+  if (set_firstparagraphindent (arg) != 0)
     line_error (_("Bad argument to %c%s"), COMMAND_PREFIX, command);
 
   free (arg);
Index: makeinfo/makeinfo.c
===================================================================
RCS file: /cvsroot/texinfo/texinfo/makeinfo/makeinfo.c,v
retrieving revision 1.24
diff -u -r1.24 makeinfo.c
--- makeinfo/makeinfo.c 8 Apr 2003 14:13:54 -0000       1.24
+++ makeinfo/makeinfo.c 9 Apr 2003 03:54:19 -0000
@@ -427,6 +427,7 @@
       --paragraph-indent=VAL  indent Info paragraphs by VAL spaces (default 
%d).\n\
                                 If VAL is `none', do not indent; if VAL is\n\
                                 `asis', preserve existing indentation.\n\
+      --no-first-par-indent   suppress indentation of the first paragraph.\n\
       --split-size=NUM        split Info files at size NUM (default %d).\n"),
              fill_column, paragraph_start_indent,
              DEFAULT_SPLIT_SIZE);
@@ -503,6 +504,7 @@
   { "iftex", 0, &process_tex, 1 },
   { "ifxml", 0, &process_xml, 1 },
   { "macro-expand", 1, 0, 'E' },
+  { "no-first-par-indent", 0, &no_first_par_indent, 1 },
   { "no-headers", 0, &no_headers, 1 },
   { "no-ifhtml", 0, &process_html, 0 },
   { "no-ifinfo", 0, &process_info, 0 },
Index: makeinfo/makeinfo.h
===================================================================
RCS file: /cvsroot/texinfo/texinfo/makeinfo/makeinfo.h,v
retrieving revision 1.5
diff -u -r1.5 makeinfo.h
--- makeinfo/makeinfo.h 5 Apr 2003 22:51:01 -0000       1.5
+++ makeinfo/makeinfo.h 9 Apr 2003 03:54:19 -0000
@@ -178,6 +178,10 @@
    is, generate plain text.  (--no-headers) */
 DECLARE (int, no_headers, 0);
 
+/* Nonzero means that we suppress the indentation of the first paragraph
+   in any section.  (--no-first-par-indent) */
+DECLARE (int, no_first_par_indent, 0);
+
 /* Nonzero means that we process @html and @rawhtml even when not
    generating HTML.  (--ifhtml) */
 DECLARE (int, process_html, 0);
Index: makeinfo/sectioning.c
===================================================================
RCS file: /cvsroot/texinfo/texinfo/makeinfo/sectioning.c,v
retrieving revision 1.8
diff -u -r1.8 sectioning.c
--- makeinfo/sectioning.c       22 Mar 2003 17:40:54 -0000      1.8
+++ makeinfo/sectioning.c       9 Apr 2003 03:54:25 -0000
@@ -215,6 +215,11 @@
 sectioning_underscore (cmd)
      char *cmd;
 {
+  /* If we're not indenting the first paragraph, we shall make it behave
+     like @noindent is called directly after the section heading. */
+  if (no_first_par_indent)
+    cm_noindent ();
+
   if (xml)
     {
       char *temp;