[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[6110] document \usebracesinindexestrue and other TeX-related updates
|
From: |
karl |
|
Subject: |
[6110] document \usebracesinindexestrue and other TeX-related updates |
|
Date: |
Mon, 09 Feb 2015 19:25:18 +0000 |
Revision: 6110
http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6110
Author: karl
Date: 2015-02-09 19:25:17 +0000 (Mon, 09 Feb 2015)
Log Message:
-----------
document \usebracesinindexestrue and other TeX-related updates
Modified Paths:
--------------
trunk/ChangeLog
trunk/doc/texinfo.texi
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2015-02-09 00:20:54 UTC (rev 6109)
+++ trunk/ChangeLog 2015-02-09 19:25:17 UTC (rev 6110)
@@ -1,3 +1,10 @@
+2015-02-09 Karl Berry <address@hidden>
+
+ * doc/texinfo.texi (Hardcopy): update whole chapter.
+ (Formatting Partial Documents, Details of @t{texindex}):
+ new nodes, mostly to mention the temporary need for
+ \usebracesinindexestrue.
+
2015-02-08 Karl Berry <address@hidden>
* tp/Texinfo/Convert/HTML.pm (_convert_U_command): new fn for @U.
Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi 2015-02-09 00:20:54 UTC (rev 6109)
+++ trunk/doc/texinfo.texi 2015-02-09 19:25:17 UTC (rev 6110)
@@ -572,10 +572,10 @@
Formatting and Printing Hardcopy
* Use @TeX{}:: Use @TeX{} to format for hardcopy.
-* Format with @t{tex}/@t{texindex}:: How to format with explicit shell
commands.
-* Format with @t{texi2dvi}:: A simpler way to format.
+* Format with @t{texi2dvi}:: The simplest way to format.
+* Format with @t{tex}/@t{texindex}:: Formatting with explicit shell
commands.
* Print with @t{lpr}:: How to print.
-* Within Emacs:: How to format and print from an Emacs shell.
+* Within Emacs:: Printing from an Emacs shell.
* Texinfo Mode Printing:: How to format and print in Texinfo mode.
* Compile-Command:: How to print using Emacs's compile command.
* Requirements Summary:: @TeX{} formatting requirements summary.
@@ -589,6 +589,11 @@
* PDF Output:: Portable Document Format output.
* Obtaining @TeX{}:: How to obtain @TeX{}.
+Format with @t{tex}/@t{texindex}
+
+* Formatting Partial Documents::
+* Details of @t{texindex}::
+
@code{texi2any}: The Generic Translator for Texinfo
* Reference Implementation:: @command{texi2any}: the reference
implementation.
@@ -16034,13 +16039,12 @@
simplest way to create printable output. These commands are installed
as part of the Texinfo package.
-More specifically, three major shell commands are used to print
-formatted output from a Texinfo manual: one converts the Texinfo
-source into something printable, a second sorts indices, and a third
-actually prints the formatted document. When you use the shell
-commands, you can either work directly in the operating system shell
-or work within a shell inside GNU Emacs (or some other computing
-environment).
+In more detail, three major shell commands are used to print formatted
+output from a Texinfo manual: one converts the Texinfo source into
+something printable, a second sorts indices, and a third actually
+prints the formatted document. When you use the shell commands, you
+can either work directly in the operating system shell or work within
+a shell inside GNU Emacs (or some other computing environment).
If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands. In addition to the three commands to
@@ -16052,8 +16056,8 @@
@menu
* Use @TeX{}:: Use @TeX{} to format for hardcopy.
-* Format with @t{tex}/@t{texindex}:: How to format with explicit shell
commands.
-* Format with @t{texi2dvi}:: A simpler way to format.
+* Format with @t{texi2dvi}:: The simplest way to format.
+* Format with @t{tex}/@t{texindex}:: Formatting with explicit shell
commands.
* Print with @t{lpr}:: How to print.
* Within Emacs:: How to format and print from an Emacs shell.
* Texinfo Mode Printing:: How to format and print in Texinfo mode.
@@ -16074,15 +16078,107 @@
@node Use @TeX{}
@section Use @TeX{}
-The typesetting program called @TeX{} is used for formatting a Texinfo
-file. @TeX{} is a very powerful typesetting program and, when used
-correctly, does an exceptionally good job.
+The typesetting program called @TeX{} is used to format a Texinfo
+document for printable output. @TeX{} is a very powerful typesetting
+program and, when used correctly, does an exceptionally good job.
@xref{Obtaining @TeX{}}, for information on how to obtain @TeX{}. It
is not included in the Texinfo package, being a vast suite of software
-itself.
+in itself.
address@hidden Format with @t{texi2dvi}
address@hidden Format with @code{texi2dvi}
+
address@hidden texi2dvi @r{(shell script)}
address@hidden DVI, output in
+
+The @code{texi2dvi} program takes care of all the steps for producing
+a @TeX{} DVI file from a Texinfo document. Similarly, @code{texi2pdf}
+produces a PDF file.
+
+To run @code{texi2dvi} or @code{texi2pdf} on an input file
address@hidden, do this (where @samp{prompt$ } is your shell prompt):
+
address@hidden
+prompt$ @kbd{texi2dvi foo.texi}
+prompt$ @kbd{texi2pdf foo.texi}
address@hidden example
+
+As shown in this example, the input filenames to @code{texi2dvi} and
address@hidden must include any extension, such as @samp{.texi}.
+(Under MS-DOS and perhaps in other circumstances, you may need to run
address@hidden 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 the
address@hidden@@setfilename} 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{}}).
+
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden pdftexi2dvi
+With the @option{--pdf} option, @command{texi2dvi} produces PDF output
+instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
+instead of @command{tex}. Alternatively, the command
address@hidden is an abbreviation for running @samp{texi2dvi
+--pdf}. The command @command{pdftexi2dvi} is also provided as a
+convenience for address@hidden (@pxref{Top,,, auctex, address@hidden, as it
+prefers to merely prepend @samp{pdf} to DVI producing tools to have
+PDF producing tools.
+
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvipdfmx
+With the @option{--dvipdf} option, @command{texi2dvi} produces PDF
+output by running @TeX{} and then a DVI-to-PDF program: if the
address@hidden environment variable is set, that value is used, else the
+first program extant among @code{dvipdfmx}, @code{dvipdfm},
address@hidden, @code{dvi2pdf}, @code{dvitopdf}. This method generally
+supports CJK typesetting better than @command{pdftex}.
+
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvips
+With the @option{--ps} option, @command{texi2dvi} produces PostScript
+instead of DVI, by running @command{tex} and then @command{dvips}
+(@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS}
+environment variable, if set.)
+
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden @LaTeX{}, processing with @command{texi2dvi}
address@hidden can also be used to process @LaTeX{} files.
+Normally @command{texi2dvi} is able to guess the input file language
+by its contents and file name extension; however, if it guesses wrong
+you can explicitly specify the input language using
address@hidden@var{lang}} 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.)
+
+The option @option{-E} (equivalently, @option{-e} and
address@hidden) does Texinfo macro expansion using
address@hidden 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.
+
+For a list of all the options, run @samp{texi2dvi --help}.
+
+
@node Format with @t{tex}/@t{texindex}
@section Format with @code{tex}/@code{texindex}
@@ -16090,8 +16186,9 @@
@cindex Formatting with @code{tex} and @code{texindex}
@cindex DVI file
-You can format the Texinfo file with the shell command @code{tex}
-followed by the name of the Texinfo file. For example:
+You can do the basic formatting of a Texinfo file with the shell
+command @code{tex} followed by the name of the Texinfo file. For
+example:
@example
tex foo.texi
@@ -16099,36 +16196,35 @@
@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
files containing information for indices, cross references, etc. The
-DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
-any device (see the following sections).
+DVI file (for @dfn{DeVice Independent} file) can be printed on
+virtually any device, perhaps after a further conversion (see the
+previous section).
@pindex texindex
The @code{tex} formatting command itself does not sort the indices; it
writes an output file of unsorted index data. To generate a printed
index after running the @command{tex} command, you first need a sorted
index to work from. The @command{texindex} command sorts indices.
-(The source file @file{texindex.c} comes as part of the standard
-Texinfo distribution, among other places.) (@command{texi2dvi} runs
+(@command{texi2dvi}, described in the previous section, runs
@command{tex} and @command{texindex} as necessary.)
@anchor{Names of index files}
@cindex Names of index files
@cindex Index file names
address@hidden formatting command outputs unsorted index files under names
-that obey a standard convention: the name of your main input file with
-any @samp{.texinfo} (or similar, @pxref{Minimum,, What a Texinfo File
-Must Have}), followed by the two letter names of indices. For
-example, the raw index output files for the input file
address@hidden would be @file{foo.cp}, @file{foo.vr},
address@hidden outputs unsorted index files under names following a
+standard convention: the name of your main input file with any
address@hidden or similar extension replaced by the two letter index
+name. For example, the raw index output files for the input file
address@hidden would be, by default, @file{foo.cp}, @file{foo.vr},
@file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those
are exactly the arguments to give to @code{texindex}.
@need 1000
@cindex Wildcards
@cindex Globbing
-Instead of specifying all the unsorted index file names explicitly, you
-can use @samp{??} as shell wildcards and give the command in this
-form:
+Instead of specifying all the unsorted index file names explicitly,
+it's typical to use @samp{??} as shell wildcards and give the command
+in this form:
@example
texindex foo.??
@@ -16143,10 +16239,11 @@
@code{texindex} command reports but otherwise ignores such files.
For each file specified, @code{texindex} generates a sorted index file
-whose name is made by appending @samp{s} to the input file name. The
+whose name is made by appending @samp{s} to the input file name; for
+example, @file{foo.cps} is made from @file{foo.cp}. The
@code{@@printindex} command looks for a file with that name
-(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
-raw index output file.
+(@pxref{Printing Indices & Menus}). @TeX{} does not read the raw
+index output file, and @code{texindex} does not alter it. the raw
After you have sorted the indices, you need to rerun @code{tex} on the
Texinfo file. This regenerates the DVI file, this time with
@@ -16155,7 +16252,8 @@
Finally, you may need to run @code{tex} one more time, to get the page
numbers in the cross references correct.
-To summarize, this is a five step process:
+To summarize, this is a five step process. (Alternatively, it's a
+one-step process: run @code{texi2dvi}; see the previous section.)
@enumerate
@item
@@ -16181,28 +16279,31 @@
written for the cross references.
@end enumerate
address@hidden texi2dvi
-Alternatively, it's a one-step process: run @code{texi2dvi}
-(@pxref{Format with @t{texi2dvi}}).
address@hidden
+* Formatting Partial Documents::
+* Details of @t{texindex}::
address@hidden menu
-You need not run @code{texindex} each time after you run @code{tex}. If
-you do not, on the next run, the @code{tex} formatting command will use
-whatever sorted index files happen to exist from the previous use of
address@hidden This is usually ok while you are debugging.
address@hidden Formatting Partial Documents
address@hidden Formatting Partial Documents
address@hidden Auxiliary files, avoiding
address@hidden Formatting partial documents
address@hidden Partial documents, formatting
address@hidden Chapters, formatting one at a time
address@hidden Auxiliary files, omitting
address@hidden Pointer validation, suppressing
@findex novalidate
address@hidden Pointer validation, suppressing
address@hidden Chapters, formatting one at a time
+
Sometimes you may wish to print a document while you know it is
-incomplete, or to print just one chapter of a document. In that case,
-the usual auxiliary files that @TeX{} creates and warnings @TeX{}
-gives when cross references are not satisfied are just nuisances. You
+incomplete, or to print just one chapter of a document. In such a
+case, the usual auxiliary files that @TeX{} creates and warnings
address@hidden gives about undefined cross references are just nuisances. You
can avoid them with the @code{@@novalidate} command, which you must
give @emph{before} the @code{@@setfilename} command
-(@address@hidden@@setfilename}}). Thus, the beginning of your file
-would look approximately like this:
+(@address@hidden@@setfilename}}).
+Thus, the beginning of your file would look approximately like this:
+
@example
\input texinfo
@@novalidate
@@ -16214,198 +16315,115 @@
@code{makeinfo}, just like its @code{--no-validate} option
(@pxref{Pointer Validation}).
+Furthermore, you need not run @code{texindex} each time after you run
address@hidden The @code{tex} formatting command simply uses whatever
+sorted index files happen to exist from a previous use of
address@hidden If those are out of date, that is usually ok while
+you are creating or debugging a document.
address@hidden Format with @t{texi2dvi}
address@hidden Format with @code{texi2dvi}
address@hidden texi2dvi @r{(shell script)}
address@hidden Details of @t{texindex}
address@hidden Details of @t{texindex}
-The @code{texi2dvi} command automatically runs both @TeX{} and
address@hidden as many times as necessary to produce a DVI file
-with sorted indices and all cross references resolved. It is
-therefore simpler than manually executing the
address@hidden@address@hidden@code{tex} sequence
-described in the previous section.
address@hidden Braces, in index entries
+In Texinfo version 6, released in 2015, the @command{texindex} program
+was completely reimplemented. The principal functional difference is
+that index entries beginning with a left brace or right brace
+(@address@hidden resp.@: @address@hidden) can work properly. For example,
these
+simple index entries are processed correctly, including the ``index
+initial'' shown in the index:
-To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
address@hidden } is your shell prompt):
-
@example
-prompt$ @kbd{texi2dvi foo.texi}
+@@cindex @@@{
+@@cindex @@@}
+...
+@@printindex cp
@end example
-As shown in this example, the input filenames to @code{texi2dvi} must
-include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
-MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
-texi2dvi foo.texi} instead of relying on the operating system to invoke
-the shell on the @samp{texi2dvi} script.
address@hidden \usebracesinindexestrue
+However, to enable this behavior, it's necessary (for now) to give a
+special option to @TeX{} early in a source document:
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 the
address@hidden@@setfilename} 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{}}).
address@hidden
+@@tex
+\global\usebracesinindexestrue
+@@end tex
address@hidden example
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden pdftexi2dvi
-With the @option{--pdf} option, @command{texi2dvi} produces PDF output
-instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
-instead of @command{tex}. Alternatively, the command
address@hidden is an abbreviation for running @samp{texi2dvi
---pdf}. The command @command{pdftexi2dvi} is also supported as a
-convenience to address@hidden users (@pxref{Top,,, auctex, address@hidden,
since
-that program merely prepends @samp{pdf} to DVI producing tools to have
-PDF producing tools.
address@hidden Sort string, incorrect @samp{|}
+This is because the previous @command{texindex} implementation aborted
+with an incorrect error message (@samp{No page number in \entry...})
+on such index entries when handled in the normal way. Therefore
address@hidden wrote out an incorrect ``sort string'' using the @samp{|}
+character; this did not affect the text of the entry, but the index
+initial was the incorrect @samp{|} (and sorting was not perfect).
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvipdfmx
-With the @option{--dvipdf} option, @command{texi2dvi} produces PDF
-output by running @TeX{} and then a DVI-to-PDF program: if the
address@hidden environment variable is set, that value is used, else
-the first extant among @code{dvipdfmx}, @code{dvipdfm}, @code{dvipdf},
address@hidden, @code{dvitopdf}. This method can support CJK
-typesetting better than @command{pdftex}.
+Because of that fatal error, and because relatively few documents have
+index entries beginning with braces, we want to provide some
+transition time for installations to have the new @command{texindex}.
+At some point in the future, we'll make @code{\usebracesinindexes}
+true by default (the above @TeX{} code will continue to work fine).
address@hidden address@hidden, for @command{texi2dvi}}
address@hidden dvips
-With the @option{--ps} option, @command{texi2dvi} produces PostScript
-instead of DVI, by running @command{tex} and then @command{dvips}
-(@pxref{Top,,, dvips, Dvips}). (Or the value of the @env{DVIPS}
-environment variable, if set.)
address@hidden Literate programming, with Texinfo and @code{awk}
address@hidden Texinfo, and literate programming
address@hidden Robbins, Arnold
address@hidden texiwebjr
+Although not a matter of functionality, readers may be interested to
+know that the new @command{texindex} is a literate program
+(@url{http://en.wikipedia.org/wiki/Literate_programming}) using
+Texinfo itself for documentation and (portable) @code{awk} for the
+code. A single source file, @file{ti.twjr} in this case, produces the
+runnable program, a printable document, and an online document. The
+system is called @file{texiwebjr} and was created by Arnold Robbins,
+who also wrote the new @command{texindex} (and not coincidentally is
+the long-time maintainer of Gawk, @pxref{Top,,, gawk, The GNU Awk
+User's Guide}). The file @file{texindex/Makefile.am} shows example
+usage.
address@hidden @LaTeX{}, processing with @command{texi2dvi}
address@hidden can also be used to process @LaTeX{} files; simply
-run @samp{texi2dvi filename.ext}.
address@hidden address@hidden, for @command{texi2dvi}}
-Normally @command{texi2dvi} is able to guess the input file language
-by its contents and file name suffix. If, however, it fails to do so
-you can specify the input language using
address@hidden@var{lang}} command line option, where @var{lang}
-is either @samp{latex} or @samp{texinfo}.
-
address@hidden will use @command{etex} (or @command{pdfetex}) if
-they are available; these extended versions of @TeX{} are not
-required, and the DVI (or PDF) output is identical, but they simplify
-the @TeX{} programming in some cases, and provide additional tracing
-information when debugging @file{texinfo.tex}.
-
address@hidden address@hidden, for @command{texi2dvi}}
-Several options are provided for handling documents, written in
-character sets other than address@hidden The
address@hidden@var{file}} option instructs
address@hidden to translate input into internal @TeX{} character
-set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX
-files, TCX files: Character translations, web2c, Web2c: A @TeX{}
-implementation}).
-
address@hidden address@hidden, for @command{texi2dvi}}
-The options @option{--recode} and @address@hidden
-allow conversion of an input document before running @TeX{}. The
address@hidden option recodes the document from encoding specified
-by @samp{@@documentencoding} command
-(@address@hidden@@documentencoding}}) to plain 7-bit @samp{texinfo}
-encoding.
-
address@hidden address@hidden, for @command{texi2dvi}}
-The option @address@hidden recodes the document from
address@hidden encoding to the encoding specified by
address@hidden@@documentencoding}. This is useful, for example, if the
-document is written in @samp{UTF-8} encoding and an equivalent 8-bit
-encoding is supported by @command{makeinfo}.
-
-Both @option{--recode} and @address@hidden use
address@hidden utility to perform the conversion. If
address@hidden fails to process the file, @command{texi2dvi} prints
-a warning and continues, using the unmodified input file.
-
-The option @option{-E} (equivalently, @option{-e} and
address@hidden) does Texinfo macro expansion using
address@hidden 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.
-
-For the list of all options, run @samp{texi2dvi --help}.
-
-
@node Print with @t{lpr}
address@hidden Print With @code{lpr -d} From Shell
address@hidden Print with @code{lpr -d} from Shell
@pindex lpr @r{(DVI print command)}
-The precise command to print a DVI file depends on your system
-installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
--d foo.dvi}.
+The way to print a DVI file depends on your system installation. Two
+common ones are @samp{dvips foo.dvi -o} to make a PostScript file
+first and then print that, and @samp{lpr -d foo.dvi} to print a DVI
+file directly.
-For example, the following commands will (perhaps) suffice to sort the
-indices, format, and print the @cite{Bison Manual}:
+For example, the following commands will (probably) suffice to sort
+the indices, format, and print this manual using the @code{texi2dvi}
+shell script (@pxref{Format with @t{texi2dvi}}).
@example
@group
-tex bison.texinfo
-texindex bison.??
-tex bison.texinfo
-lpr -d bison.dvi
+texi2dvi texinfo.texi
+dvips texinfo.dvi -o
+lpr texinfo.ps
@end group
@end example
address@hidden
-(Remember that the shell commands may be different at your site; but
-these are commonly used versions.)
+Depending on the @code{lpr} setup on your machine, you might able to
+combine the last two steps into @code{lpr -d texinfo.dvi}.
-Using the @code{texi2dvi} shell script (see the previous section):
address@hidden PCL file, for printing
+You can also generate a PDF file by running @code{texi2pdf} instead of
address@hidden; a PDF is often directly printable. Or you can
+generate a PCL file by using @code{dvilj} instead of @code{dvips}, if
+you have a printer that prefers that format.
address@hidden
address@hidden
-texi2dvi bison.texinfo
-lpr -d bison.dvi
-# or perhaps dvips bison.dvi -o
address@hidden group
address@hidden example
-
@cindex Shell printing, on MS-DOS/MS-Windows
@cindex Printing DVI files, on MS-DOS/MS-Windows
@pindex address@hidden, replacements on MS-DOS/MS-Windows}
@code{lpr} is a standard program on Unix systems, but it is usually
-absent on MS-DOS/MS-Windows. Some network packages come with a
-program named @code{lpr}, but these are usually limited to sending files
-to a print server over the network, and generally don't support the
address@hidden option. If you are unfortunate enough to work on one of these
-systems, you have several alternative ways of printing DVI files:
+absent on MS-DOS/MS-Windows. If so, just create a PostScript or PDF
+or PCL file, whatever is most convenient, and print that in the usual
+way for your machine (e.g., by sending to the appropriate port,
+usually @samp{PRN}).
address@hidden @bullet{}
address@hidden Find and install a Unix-like @code{lpr} program, or its clone.
-If you can do that, you will be able to print DVI files just like
-described above.
address@hidden Send the DVI files to a network printer queue for DVI files.
-Some network printers have special queues for printing DVI files. You
-should be able to set up your network software to send files to that
-queue. In some cases, the version of @code{lpr} which comes with your
-network software will have a special option to send a file to specific
-queues, like this:
-
address@hidden
-lpr -Qdvi -hprint.server.domain bison.dvi
address@hidden example
-
address@hidden Convert the DVI file to a Postscript or PCL file and send it to
your
-local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man
-pages for @code{dvilj}, for detailed description of these tools. Once
-the DVI file is converted to the format your local printer understands
-directly, just send it to the appropriate port, usually @samp{PRN}.
address@hidden itemize
-
-
@node Within Emacs
address@hidden From an Emacs Shell
address@hidden Printing From an Emacs Shell
@cindex Print, format from Emacs shell
@cindex Format, print from Emacs shell
@cindex Shell, format, print from
@@ -16413,22 +16431,23 @@
@cindex GNU Emacs shell, format, print from
You can give formatting and printing commands from a shell within GNU
-Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
-shell, you can format and print the document. @xref{Hardcopy, , Format
-and Print Hardcopy}, for details.
+Emacs, just like any other shell command. To create a shell within
+Emacs, type @kbd{M-x shell} (@pxref{Shell,,, emacs, The GNU Emacs
+Manual}). In this shell, you can format and print the document.
address@hidden, , Format and Print Hardcopy}, for details.
You can switch to and from the shell buffer while @code{tex} is
running and do other editing. If you are formatting a long document
on a slow machine, this can be very convenient.
-You can also use @code{texi2dvi} from an Emacs shell. For example,
-here is how to use @code{texi2dvi} to format and print @cite{Using and
+For example, you can use @code{texi2dvi} from an Emacs shell. Here is
+one way to use @code{texi2pdf} to format and print @cite{Using and
Porting GNU CC} from a shell within Emacs:
@example
@group
-texi2dvi gcc.texinfo
-lpr -d gcc.dvi
+texi2pdf gcc.texi
+lpr gcc.pdf
@end group
@end example
@@ -16563,13 +16582,13 @@
commands as a @code{compile-command} and have Emacs run it by typing
@kbd{M-x compile}. This creates a special shell called the
@file{*compilation*} buffer in which Emacs runs the compile command.
-For example, at the end of the @file{gdb.texinfo} file, after the
+For example, at the end of the @file{gdb.texi} file, after the
@code{@@bye}, you could put the following:
@example
@group
Local Variables:
-compile-command: "texi2dvi gdb.texinfo"
+compile-command: "texi2dvi gdb.texi"
End:
@end group
@end example
@@ -16586,7 +16605,7 @@
@cindex Formatting requirements
Every Texinfo file that is to be input to @TeX{} must begin with a
address@hidden command and must contain an @code{@@setfilename} command:
address@hidden command, and must contain an @code{@@setfilename} command:
@example
\input texinfo
@@ -16607,11 +16626,11 @@
Strictly speaking, these lines are all a Texinfo file needs to be
processed successfully by @TeX{}.
-Usually, however, the beginning includes an @code{@@settitle} command to
-define the title of the printed manual, an @code{@@setchapternewpage}
-command, a title page, a copyright page, and permissions. Besides an
address@hidden@@bye}, the end of a file usually includes indices and a table of
-contents. (And of course most manuals contain a body of text as well.)
+Usually, however, the beginning includes an @code{@@settitle} command
+to define the title of the printed manual, a title page, a copyright
+page, permissions, and a table of contents. Besides @code{@@bye}, the
+end of a file usually includes indices. (Not to mention that most
+manuals contain a body of text as well.)
For more information, see:
@@ -16636,21 +16655,29 @@
@TeX{} needs to know where to find the @file{texinfo.tex} file that the
@samp{\input texinfo} command on the first line reads. The
@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
-included in all standard GNU distributions. The latest version is
-always available from the Texinfo source repository:
+included in all standard GNU distributions. The latest version
+released for general use is available
+from the usual GNU servers and mirrors:
+
@smalldisplay
address@hidden://ftp.gnu.org/gnu/texinfo/texinfo.tex}
address@hidden://ftpmirror.gnu.org/texinfo/texinfo.tex}
address@hidden smalldisplay
+
+The latest development version is available from the Texinfo source
+repository:
address@hidden
@uref{http://svn.savannah.gnu.org/viewvc/trunk/doc/texinfo.tex?root=texinfo&view=log}
@end smalldisplay
@pindex address@hidden, installing}
address@hidden is essentially a standalone file, and compatibility
+is of utmost concern; so, if you need or want to try a newer version
+than came with your system, it nearly always suffices to download it
+and put it anywhere that @TeX{} will find it (first). You can replace
+any existing @file{texinfo.tex} with a newer version (of course saving
+the original in case of disaster).
-Usually, the installer has put the @file{texinfo.tex} file in the
-default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
-other GNU software is installed. In this case, @TeX{} will find the
-file and you do not need to do anything special. If this has not been
-done, you can put @file{texinfo.tex} in the current directory when you
-run @TeX{}, and @TeX{} will find it there.
-
@pindex address@hidden, installing}
Also, you should install @file{epsf.tex}, if it is not already installed
from another distribution. More details are at the end of the description
@@ -16659,16 +16686,18 @@
@cindex European Computer Modern fonts, installing
@cindex EC fonts, installing
@cindex CM-Super fonts, installing
-To be able to use quotation marks other than those used in English
-you'll need to install European Computer Modern fonts and optionally
-CM-Super fonts, unless they are already installed (@pxref{Inserting
-Quotation Marks}).
+To use quotation marks other than those used in English, you'll need
+to have the European Computer Modern fonts (e.g., @file{ecrm1000}) and
+(for PDF output) CM-Super fonts (@pxref{Inserting Quotation Marks}).
@pindex address@hidden, installing}
@cindex Euro font, installing
-If you intend to use the @code{@@euro} command, you should install the
-Euro font, if it is not already installed. @address@hidden@@euro}}.
+To use the @code{@@euro} command, you'll need the @samp{feym*} fonts
+(e.g., @file{feymr10}). @address@hidden@@euro}}.
+All of the above files (and a whole lot more) should be installed by
+default in a reasonable @TeX{} installation.
+
@pindex texinfo.cnf @r{installation}
@cindex Customizing of @TeX{} for Texinfo
@cindex Site-wide Texinfo configuration file
@@ -16684,13 +16713,13 @@
@cindex Environment variable @code{TEXINPUTS}
@vindex TEXINPUTS
-If neither of the above locations for these system files suffice for
-you, you can specify the directories explicitly. For
address@hidden, you can do this by writing the complete path for the
-file after the @code{\input} command. Another way, that works for both
+If neither of the above locations for these system files suffice, you
+can specify the directories explicitly. For @file{texinfo.tex}, you
+can do this by writing the complete path for the file after the
address@hidden command. Another way, that works for both
@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
-might read), is to set the @code{TEXINPUTS} environment variable in your
address@hidden or @file{.cshrc} file.
+might read), is to set the @code{TEXINPUTS} environment variable in
+your @file{.profile} or @file{.cshrc} file.
Whether you use @file{.profile} or @file{.cshrc} depends on
whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
@@ -16715,10 +16744,9 @@
setenv TEXINPUTS .:/home/me/mylib:
@end example
+On MS-DOS/MS-Windows, you'd do this (note the use of the @samp{;}
+character as directory separator, instead of @samp{:}):
-On MS-DOS/MS-Windows, you would say it like address@hidden the use
-of the @samp{;} character as directory separator, instead of @samp{:}.}:
-
@example
@group
set TEXINPUTS=.;d:/home/me/mylib;c:
@@ -16736,34 +16764,17 @@
the system directories. (A leading, trailing, or doubled @samp{:}
indicates searching the system directories at that point.)
address@hidden Dumping a .fmt file
address@hidden Format file, dumping
-Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
-web2c, Web2C}) so that @TeX{} can load Texinfo faster. (The
-disadvantage is that then updating @file{texinfo.tex} requires
-redumping.) You can do this by running this command, assuming
address@hidden is findable by @TeX{}:
address@hidden
-initex texinfo @@dump
address@hidden example
-
address@hidden
-(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
-wherever your @code{.fmt} files are found; typically, this will be in the
-subdirectory @file{web2c} of your @TeX{} installation.
-
-
@node Overfull hboxes
@section Overfull ``hboxes''
@cindex Overfull @samp{hboxes}
@cindex @samp{hbox}, overfull
@cindex Final output
address@hidden is sometimes unable to typeset a line without extending it into
-the right margin. This can occur when @TeX{} comes upon what it
address@hidden is sometimes unable to typeset a line within the normal
+margins. This most often occurs when @TeX{} comes upon what it
interprets as a long word that it cannot hyphenate, such as an
-electronic mail network address or a very long title. When this
+electronic mail network address or a very long identifier. When this
happens, @TeX{} prints an error message like this:
@example
@@ -16777,9 +16788,8 @@
@TeX{} also provides the line number in the Texinfo source file and
the text of the offending line, which is marked at all the places that
address@hidden considered hyphenation.
address@hidden with @TeX{}},
-for more information about typesetting errors.
address@hidden considered hyphenation. @xref{Debugging with @TeX{}}, for more
+information about typesetting errors.
If the Texinfo file has an overfull hbox, you can rewrite the sentence
so the overfull hbox does not occur, or you can decide to leave it. A
@@ -16801,17 +16811,17 @@
@noindent
(You should adjust the fraction as needed.) This huge value for
@code{\emergencystretch} cannot be the default, since then the typeset
-output would generally be of noticeably lower quality; the default
-is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
+output would generally be of noticeably lower quality; its default
+value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
containing the current line width.
@cindex Black rectangle in hardcopy
@cindex Rectangle, black in hardcopy
@cindex Box, ugly black in hardcopy
@cindex Ugly black rectangles in hardcopy
-For what overfull boxes you have, however, @TeX{} will print a large,
-ugly, black rectangle beside the line that contains the overfull hbox
-unless told otherwise. This is so you will notice the location of the
+For any overfull boxes you do have, @TeX{} will print a large, ugly,
+black rectangle beside the line that contains the overfull hbox unless
+told otherwise. This is so you will notice the location of the
problem if you are correcting a draft.
@findex finalout
@@ -16922,7 +16932,7 @@
@end example
@noindent and
@example
-@@pagesizes 11.5in @c for legal paper
+@@pagesizes 11.5in @c for legal paper
@end example
@cindex B5 paper, printing on
@@ -16941,9 +16951,7 @@
for other ways to specify @code{@@pagesizes} that do not require
changing the source file.
address@hidden@@pagesizes} is ignored by @code{makeinfo}.
-
@node Cropmarks and Magnification
@section Cropmarks and Magnification
@@ -16990,7 +16998,7 @@
@example
@group
@@tex
-\mag=1200
+\global\mag=1200
@@end tex
@end group
@end example
@@ -17008,6 +17016,7 @@
@node PDF Output
@section PDF Output
@cindex PDF output
address@hidden Output, in PDF
@pindex pdftex
The simplest way to generate PDF output from Texinfo source is to run
@@ -17040,14 +17049,15 @@
At present, Texinfo does not provide @samp{@@ifpdf} or @samp{@@pdf}
commands as for the other output formats, since PDF documents contain
-many internal low-level offsets and references that would be hard or
-impossible to get right at the Texinfo source level.
+many internal low-level offsets and cross-references that would be
+hard or impossible to specify at the Texinfo source level.
PDF files require dedicated software to be displayed, unlike the plain
ASCII formats (Info, HTML) that Texinfo supports. They also tend to
be much larger than the DVI files output by @TeX{} by default.
Nevertheless, a PDF file does define an actual typeset document in a
-self-contained file, so it has its place.
+self-contained file, notably including all the fonts that are used, so
+it has its place.
@node Obtaining @TeX{}
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [6110] document \usebracesinindexestrue and other TeX-related updates,
karl <=