[6607] move some discussion of tidy mode out of texi2dvi help message

[Gavin D. Smith]

Revision: 6607
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6607
Author:   gavin
Date:     2015-09-08 23:55:13 +0000 (Tue, 08 Sep 2015)
Log Message:
-----------
move some discussion of tidy mode out of texi2dvi help message

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

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-09-08 23:08:55 UTC (rev 6606)
+++ trunk/ChangeLog     2015-09-08 23:55:13 UTC (rev 6607)
@@ -1,3 +1,16 @@
+2015-09-09  Gavin Smith  <address@hidden>
+
+       * util/texi2dvi (usage),
+       doc/texinfo.texi (Format with texi2dvi): Move discussion of the 
+       pros and cons of --tidy.
+
+       * doc/texinfo.texi (Format with texi2dvi): Mention that a line 
+       can't start with "@c (_texi2dvi)" either.  In paragraph about 
+       etex, change "they are" to "it is" in a sentence, and reorder a 
+       sentence, and move this paragraph to the end.  Move --command 
+       paragraph after discussion of output and input format options.
+       Move mention of --help earlier.
+
 2015-09-08  Gavin Smith  <address@hidden>
 
        * util/texi2dvi (make_openout_test): Add a comment.

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-09-08 23:08:55 UTC (rev 6606)
+++ trunk/doc/texinfo.texi      2015-09-08 23:55:13 UTC (rev 6607)
@@ -14975,16 +14975,8 @@
 @samp{sh texi2dvi foo.texi} instead of relying on the operating system
 to invoke the shell on the @samp{texi2dvi} script.)
 
address@hidden address@hidden, for @command{texi2dvi}}
-One useful option to @code{texi2dvi} is @address@hidden
-This inserts @var{cmd} on a line by itself, after a
address@hidden@@setfilename} line in a temporary copy of the input file, before
-running @TeX{}.  With this, you can specify different printing
-formats, such as @code{@@smallbook} (@address@hidden@@smallbook}}),
address@hidden@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
-(@address@hidden@@pagesizes}}), without actually changing the document
-source.  (You can also do this on a site-wide basis with
address@hidden; @pxref{Preparing for @TeX{}}).
+For a list of all the options, run @samp{texi2dvi --help}.  Some of the
+options are discussed below.
 
 @opindex address@hidden, for @command{texi2dvi}}
 @pindex pdftexi2dvi
@@ -15022,27 +15014,79 @@
 @address@hidden command line option, where @var{lang}
 is either @samp{latex} or @samp{texinfo}.
 
address@hidden etex
address@hidden pdfetex
address@hidden will use @command{etex} (or @command{pdfetex}) if
-they are available; this extended version of @TeX{} is not required,
-and the DVI output is identical, but it runs faster in some cases, and
-provide additional tracing information when debugging
address@hidden  (These days, @command{pdftex} and
address@hidden are exactly the same, but we still run
address@hidden to cater to ancient @TeX{} installations.)
address@hidden address@hidden, for @command{texi2dvi}}
+One useful option to @code{texi2dvi} is @address@hidden
+This inserts @var{cmd} on a line by itself, after a
address@hidden@@setfilename} line in a temporary copy of the input file, before
+running @TeX{}.  With this, you can specify different printing
+formats, such as @code{@@smallbook} (@address@hidden@@smallbook}}),
address@hidden@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
+(@address@hidden@@pagesizes}}), without actually changing the document
+source.  (You can also do this on a site-wide basis with
address@hidden; @pxref{Preparing for @TeX{}}).
 
 The option @option{-E} (equivalently, @option{-e} and
 @option{--expand}) does Texinfo macro expansion using
 @command{makeinfo} instead of the @TeX{} implementation (@pxref{Macro
 Details}).  Each implementation has its own limitations and
-advantages.  If this option is used, the string
address@hidden@@address@hidden must not appear at the beginning of a line
-in the source file.
+advantages.  If this option is used, no line in the source file
+may begin with the string @code{@@address@hidden or the
+string @code{@@address@hidden(_texi2dvi)}.
 
-For a list of all the options, run @samp{texi2dvi --help}.
address@hidden takes the @address@hidden option to 
+specify where the @TeX{} compilation takes place, and, as a
+consequence, how auxiliary files are treated.  The build mode
+can also be set using the environment variable 
address@hidden  The valid values for @var{mode} are:
 
address@hidden @samp
address@hidden local
+ Compile in the current directory, leaving all the auxiliary
+ files around.  This is the traditional TeX use.
 
address@hidden tidy
+ Compile in a local @code{*.t2d} directory, where the auxiliary files
+ are left.  Output files are copied back to the original file.
+
+ Using the @samp{tidy} mode brings several advantages:
+ @itemize -
+ @item the current directory is not cluttered with plethora of temporary files.
+ @item clutter can be even further reduced using @option{--build-dir=dir}: all
+   the @code{*.t2d} directories are stored there.
+ @item clutter can be reduced to zero using, e.g.,
+   @option{--build-dir=/tmp/\$USER.t2d} or @option {--build-dir=\$HOME/.t2d}.
+ @item the output file is updated after every successful @TeX{} run, for
+   sake of concurrent visualization of the output.  In a @samp{local} build
+   the viewer stops during the whole @TeX{} run.
+ @item if the compilation fails, the previous state of the output file
+   is preserved.
+ @item @acronym{PDF} and @acronym{DVI} compilation are kept in separate
+   subdirectories
+   preventing any possibility of auxiliary file incompatibility.
+ @end itemize
+
+ On the other hand, because @samp{tidy} compilation takes place in another
+ directory, occasionally @TeX{} won't be able to find some files (e.g., when
+ using @code{\graphicspath}): in that case, use @option{-I} to specify the
+ additional directories to consider.
+
address@hidden clean
+ Same as @samp{tidy}, but remove the auxiliary directory afterwards.
+ Every compilation therefore requires the full cycle.
address@hidden table
+
address@hidden etex
address@hidden pdfetex
address@hidden will use @command{etex} (or @command{pdfetex}) if
+it is available, because it runs faster in some cases, and
+provides additional tracing information when debugging
address@hidden  Nevertheless, this extended version of @TeX{} is
+not required, and the DVI output is identical.
+(These days, @command{pdftex} and @command{pdfetex} are exactly the
+same, but we still run @command{pdfetex} to cater to ancient @TeX{}
+installations.)
+
+
 @node Format with @command{tex}/@command{texindex}
 @section Format with @command{tex}/@command{texindex}
 

Modified: trunk/util/texi2dvi
===================================================================
--- trunk/util/texi2dvi 2015-09-08 23:08:55 UTC (rev 6606)
+++ trunk/util/texi2dvi 2015-09-08 23:55:13 UTC (rev 6607)
@@ -179,10 +179,10 @@
   --max-iterations=N   don't process files more than N times [$max_iters]
 
 The MODE specifies where the TeX compilation takes place, and, as a
-consequence, how auxiliary files are treated.  The build mode
-can also be set using the environment variable TEXI2DVI_BUILD_MODE.
+consequence, how auxiliary files are treated.  The build mode can also
+be set using the environment variable TEXI2DVI_BUILD_MODE.
 
-Valid MODEs are:
+Valid values of MODE are:
   \`local'      compile in the current directory, leaving all the auxiliary
                files around.  This is the traditional TeX use.
   \`tidy'       compile in a local *.t2d directory, where the auxiliary files
@@ -190,25 +190,6 @@
   \`clean'      same as \`tidy', but remove the auxiliary directory afterwards.
                Every compilation therefore requires the full cycle.
 
-Using the \`tidy' mode brings several advantages:
-  - the current directory is not cluttered with plethora of temporary files.
-  - clutter can be even further reduced using --build-dir=dir: all the *.t2d
-    directories are stored there.
-  - clutter can be reduced to zero using, e.g., --build-dir=/tmp/\$USER.t2d
-    or --build-dir=\$HOME/.t2d.
-  - the output file is updated after every successful TeX run, for
-    sake of concurrent visualization of the output.  In a \`local' build
-    the viewer stops during the whole TeX run.
-  - if the compilation fails, the previous state of the output file
-    is preserved.
-  - PDF and DVI compilation are kept in separate subdirectories
-    preventing any possibility of auxiliary file incompatibility.
-
-On the other hand, because \`tidy' compilation takes place in another
-directory, occasionally TeX won't be able to find some files (e.g., when
-using \\graphicspath): in that case, use -I to specify the additional
-directories to consider.
-
 The values of these environment variables are used to run the
 corresponding commands, if they are set: