[6604] texinfo.texi move details of different types of @ -command into an appendix

[Gavin D. Smith]

Revision: 6604
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6604
Author:   gavin
Date:     2015-09-07 21:05:25 +0000 (Mon, 07 Sep 2015)
Log Message:
-----------
texinfo.texi move details of different types of @-command into an appendix

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

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-09-07 20:51:23 UTC (rev 6603)
+++ trunk/ChangeLog     2015-09-07 21:05:25 UTC (rev 6604)
@@ -1,5 +1,19 @@
 2015-09-07  Gavin Smith  <address@hidden>
 
+       * doc/texinfo.texi (Command Syntax): Make a section of an 
+       appendix on @-commands.
+       (@-Command Details): New appendix.
+       (Command List, Command Contexts): Make sections of the new 
+       appendix.
+       (Conventions): Move some of the information from Command Syntax 
+       here.
+       (Short Sample): Reorder words in a heading.
+       (Def Cmd Continuation Lines, Inserting an Atsign): Add 
+       @sortas{@@} specifiers
+       (@documentdescription): Add @code around "<meta>".
+
+2015-09-07  Gavin Smith  <address@hidden>
+
        * doc/texinfo.tex (\indexnonalnumdisappear)
        (\indexnonalnumreappear): Disregard @ when sorting index 
        entries.

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-09-07 20:51:23 UTC (rev 6603)
+++ trunk/doc/texinfo.texi      2015-09-07 21:05:25 UTC (rev 6604)
@@ -157,8 +157,7 @@
 
 Appendices
 
-* Command List::                All the Texinfo @@-commands.
-* Command Contexts::            Which commands can be used where.
+* @@-Command Details::           Details of the Texinfo @@-commands.
 * Tips::                        Hints on how to write a Texinfo document.
 * Sample Texinfo Files::        Complete examples, including full texts.
 * Texinfo Mode::                Using the GNU Emacs Texinfo mode.
@@ -1262,20 +1261,35 @@
 file, and gives a short sample file.
 
 @menu
-* Command Syntax::              @@-commands are used for formatting.
 * Conventions::                 General rules for writing a Texinfo file.
 * Comments::                    Writing comments and ignored text in general.
 * Minimum::                     What a Texinfo file must have.
 * Short Sample::                A short sample Texinfo file.
 @end menu
 
address@hidden Command Syntax
address@hidden @@-Command Syntax
+
address@hidden Conventions
address@hidden General Syntactic Conventions
address@hidden General syntactic conventions
address@hidden Syntactic conventions
address@hidden Conventions, syntactic
address@hidden Characters, basic input
 @anchor{Formatting Commands} @c old name
address@hidden @@-command syntax
address@hidden Syntax, of @@-commands
address@hidden Command syntax
 
+This section describes the general conventions used in all Texinfo documents.
+
address@hidden @bullet
address@hidden
address@hidden Source files, characters used
+All printable ASCII characters except @samp{@@}, @address@hidden and
address@hidden@}} can appear in a Texinfo file and stand for themselves.
address@hidden@@} is the escape character which introduces commands, while
address@hidden@{} and @address@hidden are used to surround arguments to certain
+commands.  To put one of these special characters into the document, put
+an @samp{@@} character in front of it, like this: @samp{@@@@},
address@hidden@@@{}, and @samp{@@@}}.
+
address@hidden
 @cindex @@-commands
 @cindex Formatting commands
 In a Texinfo file, the commands you write to describe the contents of
@@ -1283,11 +1297,7 @@
 @dfn{@@-commands}.  (The @samp{@@} in Texinfo has the same meaning that
 @samp{\} has in plain @TeX{}.)
 
-Texinfo's @@-commands are a strictly limited set of constructs.  The
-strict limits are primarily intended to ``force'' you, the author, to
-concentrate on the writing and the content of your manual, rather than
-the details of the formatting.
-
address@hidden Braces, when to use
 Depending on what they do or what address@hidden word
 @dfn{argument} comes from the way it is used in mathematics and does not
 refer to a dispute between two people; it refers to the information
@@ -1298,105 +1308,20 @@
 meaning.  In its other thread of derivation, the word came to mean `to
 assert in a manner against which others may make counter assertions',
 which led to the meaning of `argument' as a dispute.} they take, you
-need to write @@-commands on lines of their own or as part of
-sentences.  Texinfo has the following types of @@-command:
+need to write @@-commands on lines of their own, or as part of
+sentences.  As a general rule, a command requires braces if it mingles 
+among other text; but it does not need braces if it is on a line of its 
+own.  For more details of Texinfo command syntax, see @ref{Command 
+Syntax}.
 
address@hidden @asis
address@hidden 1. Brace commands
-These commands start with @@ followed by a letter or a word, followed by an
-argument within braces.  For example, the command @code{@@dfn} indicates
-the introductory or defining use of a term; it is used as follows: @samp{In
-Texinfo, @@@@-commands are @@address@hidden@} commands.}
 
address@hidden 2. Line commands
-These commands occupy an entire line.  The line starts with @@,
-followed by the name of the command (a word); for example, @code{@@center}
-or @code{@@cindex}.  If no argument is needed, the word is followed by
-the end of the line.  If there is an argument, it is separated from
-the command name by a space.  Braces are not used.
-
address@hidden 3. Block commands
-These commands are written at the start of a line, with general text on
-following lines, terminated by a matching @code{@@end} command on a
-line of its own.  For example, @code{@@example}, then the lines of a
-coding example, then @code{@@end example}.  Some of these block commands
-take arguments as line commands do; for example, @code{@@enumerate A}
-opening an environment terminated by @code{@@end enumerate}.  Here
address@hidden is the argument.
-
address@hidden 4. Symbol insertion commands with no arguments
-These commands start with @@ followed by a word followed by a
-left and right- brace.  These commands insert special symbols in
-the document; they do not take arguments.  Some examples:
address@hidden@@address@hidden@}} @result{} @address@hidden, 
@code{@@address@hidden@}}
address@hidden @address@hidden, @code{@@address@hidden@}} @result{} 
address@hidden', and
address@hidden@@address@hidden@}} @result{} @address@hidden
-
address@hidden 5. Non-alphabetic commands
-The names of commands in all of the above categories consist of
-alphabetic characters, almost entirely in lower-case.  Unlike those, the
-non-alphabetic commands commands consist of an @@ followed by a
-punctuation mark or other character that is not part of the Latin
-alphabet.  Non-alphabetic commands are almost always part of text
-within a paragraph.  The non-alphabetic commands include @code{@@@@},
address@hidden@@@{}, @code{@@@}}, @code{@@.}, @code{@@@kbd{SPACE}}, and most of
-the accent commands.
-
address@hidden 6. Miscellaneous commands
-There are a handful of commands that don't fit into any of the above
-categories; for example, the obsolete command @code{@@refill}, which is
-always used at the end of a paragraph immediately following the final
-period or other punctuation character.  @code{@@refill} takes no
-argument and does not require braces.  Likewise, @code{@@tab} used in a
address@hidden@@multitable} block does not take arguments, and is not followed 
-by braces.
address@hidden table
-
address@hidden
 Whitespace following an @@-command name is optional and (usually)
 ignored if present.  The exceptions are contexts when whitespace is
 significant, e.g., an @code{@@example} environment.
 
address@hidden Braces and argument syntax
-Thus, the alphabetic commands fall into classes that have
-different argument syntaxes.  You cannot tell to which class a command
-belongs by the appearance of its name, but you can tell by the
-command's meaning: if the command stands for a glyph, it is in
-class 4 and does not require an argument; if it makes sense to use the
-command among other text as part of a paragraph, the command
-is in class 1 and must be followed by an argument in braces.
 
address@hidden Braces, when to use
-As a general rule, a command requires braces if it mingles among other
-text; but it does not need braces if it is on a line of its own.  The
-non-alphabetic commands, such as @code{@@:}, are exceptions to the
-rule; they do not need braces.
-
-The purpose of having different syntax for commands is to make Texinfo
-files easier to read, and also to help the GNU Emacs paragraph and
-filling commands work properly.
-
-
address@hidden Conventions
address@hidden General Syntactic Conventions
address@hidden General syntactic conventions
address@hidden Syntactic conventions
address@hidden Conventions, syntactic
address@hidden Characters, basic input
-
-This section describes the general conventions used in all Texinfo documents.
-
address@hidden @bullet
 @item
address@hidden Source files, characters used
-All printable ASCII characters except @samp{@@}, @address@hidden and
address@hidden@}} can appear in a Texinfo file and stand for themselves.
address@hidden@@} is the escape character which introduces commands, while
address@hidden@{} and @address@hidden are used to surround arguments to certain
-commands.  To put one of these special characters into the document, put
-an @samp{@@} character in front of it, like this: @samp{@@@@},
address@hidden@@@{}, and @samp{@@@}}.
-
address@hidden
 Texinfo supports the usual quotation marks used in English and in
 other languages; see @ref{Inserting Quotation Marks}.
 
@@ -1633,7 +1558,7 @@
 @end group
 @end example
 
address@hidden Titlepage, Contents, Copyright
address@hidden Titlepage, Copyright, Contents
 
 The title and copyright segment contains the title and copyright
 pages for the printed manual.  The segment must be enclosed between
@@ -2859,7 +2784,7 @@
 @cindex Description of document
 @cindex Summary of document
 @cindex Abstract of document
address@hidden <meta> HTML tag, and document description
address@hidden @code{<meta>} HTML tag, and document description
 @findex documentdescription
 
 When producing HTML output for a document, @command{makeinfo} writes a
@@ -9770,7 +9695,7 @@
 @subsection Inserting `@@' with @code{@@@@} and @code{@@address@hidden@}}
 @cindex At sign, inserting
 @cindex Inserting @@ @r{(literal @samp{@@})}
address@hidden @@ @r{(literal @samp{@@})}
address@hidden @sortas{@@} @@ @r{(literal @samp{@@})}
 @findex address@hidden@} @r{(literal @samp{@@})}
 
 @code{@@@@} produces a single @samp{@@} character in the output.  Do
@@ -11891,7 +11816,7 @@
 @section Definition Command Continuation Lines
 @cindex Continuation lines in definition commands
 @cindex Definition command headings, continuing
address@hidden @samp{@@} as continuation in definition commands
address@hidden @sortas{@@} @samp{@@} as continuation in definition commands
 
 The heading line of a definition command can get very long.
 Therefore, Texinfo has a special syntax allowing them to be continued
@@ -19566,8 +19491,89 @@
 difference between the two approaches.
 
 
address@hidden @@-Command Details
address@hidden @@-Command Details
+
+Here are the details of @@-commands: information about their syntax, a 
+list of commands, and information about where commands can appear.
+
address@hidden Command Syntax
address@hidden @@-Command Syntax
address@hidden @@-command syntax
address@hidden Syntax, of @@-commands
address@hidden Command syntax
+
+Texinfo has the following types of @@-command:
+
address@hidden @asis
address@hidden 1. Brace commands
+These commands start with @@ followed by a letter or a word, followed by an
+argument within braces.  For example, the command @code{@@dfn} indicates
+the introductory or defining use of a term; it is used as follows: @samp{In
+Texinfo, @@@@-commands are @@address@hidden@} commands.}
+
address@hidden 2. Line commands
+These commands occupy an entire line.  The line starts with @@,
+followed by the name of the command (a word); for example, @code{@@center}
+or @code{@@cindex}.  If no argument is needed, the word is followed by
+the end of the line.  If there is an argument, it is separated from
+the command name by a space.  Braces are not used.
+
address@hidden 3. Block commands
+These commands are written at the start of a line, with general text on
+following lines, terminated by a matching @code{@@end} command on a
+line of its own.  For example, @code{@@example}, then the lines of a
+coding example, then @code{@@end example}.  Some of these block commands
+take arguments as line commands do; for example, @code{@@enumerate A}
+opening an environment terminated by @code{@@end enumerate}.  Here
address@hidden is the argument.
+
address@hidden 4. Symbol insertion commands with no arguments
+These commands start with @@ followed by a word followed by a
+left and right- brace.  These commands insert special symbols in
+the document; they do not take arguments.  Some examples:
address@hidden@@address@hidden@}} @result{} @address@hidden, 
@code{@@address@hidden@}}
address@hidden @address@hidden, @code{@@address@hidden@}} @result{} 
address@hidden', and
address@hidden@@address@hidden@}} @result{} @address@hidden
+
address@hidden 5. Non-alphabetic commands
+The names of commands in all of the above categories consist of
+alphabetic characters, almost entirely in lower-case.  Unlike those, the
+non-alphabetic commands commands consist of an @@ followed by a
+punctuation mark or other character that is not part of the Latin
+alphabet.  Non-alphabetic commands are almost always part of text
+within a paragraph.  The non-alphabetic commands include @code{@@@@},
address@hidden@@@{}, @code{@@@}}, @code{@@.}, @code{@@@kbd{SPACE}}, and most of
+the accent commands.
+
address@hidden 6. Miscellaneous commands
+There are a handful of commands that don't fit into any of the above
+categories; for example, the obsolete command @code{@@refill}, which is
+always used at the end of a paragraph immediately following the final
+period or other punctuation character.  @code{@@refill} takes no
+argument and does not require braces.  Likewise, @code{@@tab} used in a
address@hidden@@multitable} block does not take arguments, and is not followed 
+by braces.
address@hidden table
+
address@hidden Braces and argument syntax
+Thus, the alphabetic commands fall into classes that have
+different argument syntaxes.  You cannot tell to which class a command
+belongs by the appearance of its name, but you can tell by the
+command's meaning: if the command stands for a glyph, it is in
+class 4 and does not require an argument; if it makes sense to use the
+command among other text as part of a paragraph, the command
+is in class 1 and must be followed by an argument in braces.  The
+non-alphabetic commands, such as @code{@@:}, are exceptions to the
+rule; they do not need braces.
+
+The purpose of having different syntax for commands is to make Texinfo
+files easier to read, and also to help the GNU Emacs paragraph and
+filling commands work properly.
+
+
 @node Command List
address@hidden @@-Command List
address@hidden @@-Command List
 @cindex Alphabetical @@-command list
 @cindex List of @@-commands
 @cindex @@-command list
@@ -19577,9 +19583,6 @@
 brackets, @address@hidden address@hidden, indicate optional arguments; an 
ellipsis,
 @address@hidden, indicates repeated text.
 
-More specifics on the general syntax of different @@-commands are
-given in @ref{Command Syntax}.
-
 @table @code
 @item @@@var{whitespace}
 An @code{@@} followed by a space, tab, or newline produces a normal,
@@ -20883,7 +20886,7 @@
 
 
 @node Command Contexts
address@hidden @@-Command Contexts
address@hidden @@-Command Contexts
 
 @cindex Contexts, of @@-commands