[5943] @noindent, @indent: documentation

[karl]

Revision: 5943
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5943
Author:   karl
Date:     2014-11-27 18:27:44 +0000 (Thu, 27 Nov 2014)
Log Message:
-----------
@noindent, @indent: documentation

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/doc/texinfo.texi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2014-11-22 18:49:25 UTC (rev 5942)
+++ trunk/ChangeLog     2014-11-27 18:27:44 UTC (rev 5943)
@@ -1,3 +1,8 @@
+2014-11-27  Karl Berry  <address@hidden>
+
+       * doc/texinfo.texi (@noindent, @indent): more explicitly describe
+       recommendations and current behavior.
+
 2014-11-22  Patrice Dumas  <address@hidden>
 
        * Texinfo/Common.pm (%style_commands), 

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2014-11-22 18:49:25 UTC (rev 5942)
+++ trunk/doc/texinfo.texi      2014-11-27 18:27:44 UTC (rev 5943)
@@ -8349,8 +8349,8 @@
 undo the indentation of a line.
 
 The @code{@@noindent} command may be used after one of the above
-constructs (or anywhere) to prevent the following text from being
-indented as a new paragraph.
+constructs (or at the beginning of any paragraph) to prevent the
+following text from being indented as a new paragraph.
 
 
 @node @t{@@quotation}
@@ -8933,7 +8933,7 @@
 advance that justifying the text on both margins will make the
 paragraph look bad.
 
-For example,
+An example (from elswhere in this manual):
 
 @example
 @group
@@ -8973,14 +8973,9 @@
 text.  You can also disable indentation for all paragraphs globally with
 @code{@@paragraphindent} (@address@hidden@@paragraphindent}}).
 
-It is best to write @code{@@noindent} 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.
+Here is an example showing how to eliminate the normal indentation of
+the text after an @code{@@example}, a common situation:
 
address@hidden 1500
-For example:
-
 @example
 @group
 @@example
@@ -8989,38 +8984,39 @@
 
 @@noindent
 This line is not indented.  As you can see, the
-beginning of the line is fully flush left with the line
-that follows after it.  (This whole example is between
-@@address@hidden@@@@address@hidden and @@address@hidden@@@@end address@hidden)
+beginning of the line is fully flush left with the
+line that follows after it.
 @end group
 @end example
 
 @noindent produces:
 
 @display
-
 @example
 This is an example
 @end example
 
 @noindent
 This line is not indented.  As you can see, the
-beginning of the line is fully flush left with the line
-that follows after it.  (This whole example is between
address@hidden@@display} and @code{@@end display}.)
-
+beginning of the line is fully flush left with the
+line that follows after it.
 @end display
 
-To adjust the number of blank lines properly in the Info file output,
-remember that the line containing @code{@@noindent} does not generate a
-blank line, and neither does the @code{@@end example} line.
+The standard usage of @code{@@indent} is just as above: at the
+beginning of what would otherwise be a paragraph, to eliminate the
+indentation that normally happens there.  It can either be followed by
+text or be on a line by itself.  There is no reason to use it
+in other contexts, such as in the middle of a paragraph or inside an
+environment (@pxref{Quotations and Examples}).
 
-In the Texinfo source file for this manual, each line that says
-`produces' is preceded by @code{@@noindent}.
+You can control the number of blank lines in the Info file output by
+adjusting the input as desired: a line containing just
address@hidden@@noindent} does not generate a blank line, and neither does an
address@hidden@@end} line for an environment.
 
 Do not put braces after an @code{@@noindent} command; they are not
-necessary, since @code{@@noindent} is a command used outside of
-paragraphs (@pxref{Command Syntax}).
+used, since @code{@@noindent} is a command used outside of paragraphs
+(@pxref{Command Syntax}).
 
 
 @node @t{@@indent}
@@ -9034,23 +9030,25 @@
 
 @indent
 To complement the @code{@@noindent} command (see the previous
-section), Texinfo provides the @code{@@indent} command that forces a
-paragraph to be indented.  This paragraph, for instance, is indented
-using an @code{@@indent} command.  The first paragraph of a section is
-the most likely place to use @code{@@indent}, to override the normal
-behavior of no indentation there (@address@hidden@@paragraphindent}}).
+section), Texinfo provides the @code{@@indent} command to force a
+paragraph to be indented.  For instance, this paragraph (the first in
+this section) 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.  The
address@hidden@@indent} line will not generate a blank line in the Info output
-within an environment.
+And indeed, the first paragraph of a section is the most likely place
+to use @code{@@indent}, to override the normal behavior of no
+indentation there (@address@hidden@@paragraphindent}}).  It can either be
+followed by text or be on a line by itself.
 
-However, it is ok to use it at the beginning of a line, with text
-following, outside of any environment.
+As a special case, when @code{@@indent} is used in an environment
+where text is not filled, it produces a paragraph indentation space in
+the @TeX{} output.  (These environments are where a line of input
+produces a line of output, such as @code{@@example} and
address@hidden@@display}; for a summary of all environments, @pxref{Block
+Enclosing Commands}.)
 
-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}).
+Do not put braces after an @code{@@indent} command; they are not used,
+since @code{@@indent} is a command used outside of paragraphs
+(@pxref{Command Syntax}).
 
 
 @node @t{@@cartouche}