2c2,8
< @c $Id: texinfo.txi,v 1.192 2002/03/04 14:52:52 karl Exp $
---
> @c $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
> @c Ordinarily Texinfo files have the extension .texi. But texinfo.texi
> @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
>
> @c Everything between the start/end of header lines will be passed by
> @c Emacs's {texinfo,makeinfo}-format region commands. See the `start of
> @c header' node for more info.
5c11,14
< @c All text is ignored before the setfilename.
---
> @c makeinfo and texinfo.tex ignore all text before @setfilename.
> @c
> @c Ordinarily the setfilename argument ends with .info. But
> @c texinfo.info-13 is too long for 14-character filesystems.
7a17,18
> @c Automake automatically updates version.texi to @set VERSION and
> @c @set UPDATED to appropriate values.
9c20
< @settitle Texinfo @value{VERSION}
---
> @settitle GNU Texinfo @value{VERSION}
24a36,57
> @copying
> This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
> a documentation system that can produce both online information and a
> printed manual from a single source.
>
> Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
> Free Software Foundation, Inc.
>
> @quotation
> Permission is granted to copy, distribute and/or modify this document
> under the terms of the GNU Free Documentation License, Version 1.1 or
> any later version published by the Free Software Foundation; with no
> Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
> and with the Back-Cover Texts as in (a) below. A copy of the license is
> included in the section entitled ``GNU Free Documentation License.''
>
> (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
> this GNU Manual, like GNU software. Copies published by the Free
> Software Foundation raise funds for GNU development.''
> @end quotation
> @end copying
>
45c78
< @c If you like blank pages. Can add through texi2dvi -t.
---
> @c If you like blank pages, add through texi2dvi -t.
51,54d83
< @ifinfo
< This file documents Texinfo, a documentation system that can produce
< both online information and a printed manual from a single source. This
< edition is for Texinfo version @value{VERSION}, @value{UPDATED}.
56,67d84
< Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
< Free Software Foundation, Inc.
<
< Permission is granted to copy, distribute and/or modify this document
< under the terms of the GNU Free Documentation License, Version 1.1 or
< any later version published by the Free Software Foundation; with the
< Invariant Section being ``History'', with no Front-Cover Texts, and with
< no Back-Cover Texts. A copy of the license is included in the section
< entitled ``GNU Free Documentation License''.
< @end ifinfo
<
<
83,84c100
< Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
< Free Software Foundation, Inc.
---
> @insertcopying
86,87d101
< This manual is for Texinfo version @value{VERSION}, @value{UPDATED}.
<
93,94c107
< @c ISBN 1-882114-65-5 @c for version 3.12, March 1998.
< @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
---
> @c ISBN 1-882114-65-5 is for version 3.12, March 1998.
95a109
> @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
98,105d111
<
< Permission is granted to copy, distribute and/or modify this document
< under the terms of the GNU Free Documentation License, Version 1.1 or
< any later version published by the Free Software Foundation; with the
< Invariant Section being ``History'', with no Front-Cover Texts, and with
< no Back-Cover Texts. A copy of the license is included in the section
< entitled ``GNU Free Documentation License''.
<
107a114
>
110a118
>
115,116c123
< Texinfo is a documentation system that uses a single source to produce
< both online information and printed output.
---
> @insertcopying
122d128
< This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
126c132
< * Copying:: Your rights.
---
> * Copying Conditions:: Your rights.
154c160
< * Sample Texinfo File:: A sample Texinfo file to look at.
---
> * Sample Texinfo Files:: Complete examples, including full texts.
161c167
< * Documentation Copying:: The GNU Free Documentation License.
---
> * Copying This Manual:: The GNU Free Documentation License.
205,208c211,213
< * Four Parts:: Four parts begin a Texinfo file.
< * Sample Beginning:: Here is a sample beginning for a Texinfo file.
< * Header:: The very beginning of a Texinfo file.
< * Info Summary and Permissions:: Summary and copying permissions for Info.
---
> * Sample Beginning:: A sample beginning for a Texinfo file.
> * Texinfo File Header::
> * Document Permissions::
210a216
> * Global Document Commands::
212c218
< have the right to use and share software.
---
> have the right to use and share software.
214c220
< The Texinfo File Header
---
> Texinfo File Header
220,223d225
< * documentdescription:: Document summary for the HTML output.
< * setchapternewpage:: Start chapters on right-hand pages.
< * paragraphindent:: Specify paragraph indentation.
< * exampleindent:: Specify environment indentation.
226c228
< The Title and Copyright Pages
---
> Document Permissions
227a230,234
> * copying:: Declare the document's copying permissions.
> * insertcopying:: Where to insert the permissions.
>
> Title and Copyright Pages
>
233c240
< * Copyright & Permissions:: How to write the copyright notice and
---
> * Copyright:: How to write the copyright notice and
242,243c249,250
< * Title of Top Node:: Sketch what the file is about.
< * Master Menu Parts:: A master menu has three or more parts.
---
> * Top Node Example::
> * Master Menu Parts::
244a252,258
> Global Document Commands
>
> * documentdescription:: Document summary for the HTML output.
> * setchapternewpage:: Start chapters on right-hand pages.
> * paragraphindent:: Specify paragraph indentation.
> * exampleindent:: Specify environment indentation.
>
284d297
< * Top Node Summary:: Write a brief description for readers.
327c340
< * verb:: A verbatim sequence of characters.
---
> * verb:: A verbatim sequence of characters.
351c364
< * verbatiminclude:: Including a file verbatim.
---
> * verbatiminclude:: Including a file verbatim.
539c552
< * Installing an Info File::
---
> * Installing an Info File::
565a579,583
> Sample Texinfo Files
>
> * Short Sample Texinfo File::
> * GNU Sample Texts::
>
599a618,621
> Copying This Manual
>
> * GNU Free Documentation License:: License for copying this manual.
>
612c634
< @node Copying
---
> @node Copying Conditions
648c670,672
< Licenses that accompany them.
---
> Licenses that accompany them. This manual specifically is covered by
> the GNU Free Documentation License (@pxref{GNU Free Documentation
> License}).
702,703c726
< @item hardware, operating system, and compiler versions.
< @item any unusual options you gave to @command{configure}.
---
> @item hardware and operating system names and versions.
705a729
> @item any unusual options you gave to @command{configure}.
711a736
> @cindex Patches, contributing
741,742c766,768
< from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file
< that you can typeset and print as a book or report (@pxref{Hardcopy}).
---
> and much stricter than @TeX{}'s usual language, plain @TeX{}). This
> creates a DVI file that you can typeset and print as a book or report
> (@pxref{Hardcopy}).
756,758c782,784
< To output DocBook, run @code{makeinfo --docbook}. If you want to
< convert from Docbook @emph{to} Texinfo, please see
< @uref{http://docbook2X.sourceforge.net/}.
---
> To output DocBook (a particular form of XML), run @code{makeinfo
> --docbook}. If you want to convert from Docbook @emph{to} Texinfo,
> please see @uref{http://docbook2X.sourceforge.net/}.
769c795
< Info and HTML.
---
> Info, plain text, HTML, XML, and DocBook.
800c826
< generating a good user manual or a good reference manual. This makes
---
> writing a good user tutorial or a good reference manual. This makes
807,812c833,838
< If you wish to support man pages, the program @command{help2man} may be
< useful; it generates a traditional man page from the @samp{--help}
< output of a program. In fact, this is currently used to generate man
< pages for the Texinfo programs themselves. It is GNU software written
< by Brendan O'Dea, available from
< @uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}.
---
> Man pages still have their place, and if you wish to support them, the
> program @command{help2man} may be useful; it generates a traditional man
> page from the @samp{--help} output of a program. In fact, this is
> currently used to generate man pages for the Texinfo programs
> themselves. It is GNU software written by Brendan O'Dea, available from
> @uref{ftp://ftp.gnu.org/gnu/help2man/}.
822c848
< into an Info file.)@refill
---
> into an Info file.)
829c855
< related nodes.@refill
---
> related nodes.
832c858
< @inforef{Top, info, info}, for more information about using Info.@refill
---
> @inforef{Top, info, info}, for more information about using Info.
842c868
< of subsections.@refill
---
> of subsections.
855c881
< following higher level node as its `Next' pointer.}@refill
---
> following higher level node as its `Next' pointer.}
954,959c980,986
< Most often, documents are printed on 8.5 inch by 11 inch pages
< (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you can also
< print for 7 inch by 9.25 inch pages (178@dmn{mm} by 235@dmn{mm}; the
< @code{@@smallbook} size) or on A4 or A5 size paper (@code{@@afourpaper},
< @code{@@afivepaper}). (@xref{smallbook, , Printing ``Small'' Books}.
< Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)
---
> In the United States, documents are most often printed on 8.5 inch by 11
> inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But
> you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
> 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
> (@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
> Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
> Paper}.)
967c994
< light-hearted, young and cheery.@refill
---
> light-hearted, young and cheery.
978,979c1005
< formatting commands that Texinfo supports are necessarily
< limited.@refill
---
> formatting commands that Texinfo supports are necessarily limited.
985c1011
< @node Formatting Commands, Conventions, Printed Books, Overview
---
> @node Formatting Commands
999,1000c1025
< @code{@@TeX@{@}} command, must be written entirely in lower
< case.@refill
---
> @code{@@TeX@{@}} command, must be written entirely in lower case.
1070c1095
< @node Conventions, Comments, Formatting Commands, Overview
---
> @node Conventions
1082,1086c1107,1111
< @samp{@@} is the escape character which introduces commands.
< @samp{@{} and @samp{@}} should be used only 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{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
---
> @samp{@@} is the escape character which introduces commands, while
> @samp{@{} and @samp{@}} 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{@@@@},
> @samp{@@@{}, and @samp{@@@}}.
1089d1113
< @ifinfo
1091,1099c1115
< begin and end quotations: ` ` and ' ' (but without a space between the
< two single-quote characters). This convention should be followed in
< Texinfo files. @TeX{} converts doubled single-quote characters to
< left- and right-hand doubled quotation marks and Info converts doubled
< single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
< @end ifinfo
< @iftex
< It is customary in @TeX{} to use doubled single-quote characters to
< begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This
---
> begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}. This
1101,1104c1117,1121
< doubled single-quote characters to left- and right-hand doubled
< quotation marks, ``like this'', and Info converts doubled single-quote
< characters to @sc{ascii} double-quotes: @w{@t{ `` }} and
< @w{@t{ '' }} to @w{@t{ " }}.@refill
---
> two single quotes to left- and right-hand doubled
> quotation marks,
> @c this comes out as "like this" in Info, of course, which is just confusing.
> @iftex
> ``like this'',
1105a1123,1124
> and Info converts doubled single-quote characters to @sc{ascii}
> double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
1116c1135
< paragraph.@refill
---
> paragraph.
1122,1130c1141,1146
< borrowed from plain @TeX{} that you cannot use in Info. Likewise, if
< you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
< commands, that region will appear only in the Info file; in that
< region, you can use Info commands that you cannot use in @TeX{}.
< Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
< @code{@@ifnothtml @dots{} @@end ifnothtml},
< @code{@@ifnotinfo @dots{} @@end ifnotinfo},
< @code{@@ifnottex @dots{} @@end ifnottex}.
< @xref{Conditionals}.
---
> borrowed from plain @TeX{} that you cannot use in Info. Conversely,
> text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
> appear in all output formats @emph{except} @TeX{}.
>
> Each of the other output formats (@code{html}, @code{info},
> @code{plaintext}) have an analogous pair of commands. @xref{Conditionals}.
1135,1137c1151,1153
< @strong{Caution:} Do not use tabs in a Texinfo file (except in verbatim
< modes) ! @TeX{} uses variable-width fonts, which means that it is
< impractical at best to define a tab to work in all circumstances.
---
> @strong{Caution:} Do not use tab characters in a Texinfo file (except in
> verbatim modes)! @TeX{} uses variable-width fonts, which means that it
> is impractical at best to define a tab to work in all circumstances.
1141c1157
< differently in the output, for example, in an indented example.
---
> differently in the output, for example, in indented text.
1153c1169
< @node Comments, Minimum, Conventions, Overview
---
> @node Comments
1155a1172,1175
> @cindex Comments
> @findex comment
> @findex c @r{(comment)}
>
1162,1170c1182
< or the printed manual. (Often, you can write the @code{@@comment} or
< @code{@@c} in the middle of a line, and only the text that follows after
< the @code{@@comment} or @code{@@c} command does not appear; but some
< commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
< whole line. You cannot use @code{@@comment} or @code{@@c} in a line
< beginning with such a command.)@refill
< @cindex Comments
< @findex comment
< @findex c @r{(comment)}
---
> or the printed manual.
1171a1184,1193
> Often, you can write the @code{@@comment} or @code{@@c} in the middle of
> a line, and only the text that follows after the @code{@@comment} or
> @code{@@c} command does not appear; but some commands, such as
> @code{@@settitle} and @code{@@setfilename}, work on a whole line. You
> cannot use @code{@@comment} or @code{@@c} in a line beginning with such
> a command.
>
> @cindex Ignored text
> @cindex Unprocessed text
> @findex ignore
1180,1184d1201
< @cindex Ignored text
< @cindex Unprocessed text
< @findex ignore
< @c !!! Perhaps include this comment about ignore and ifset:
< @ignore
1188,1192c1205,1207
< still parse the ignored text, in order to understand when to
< @emph{stop} ignoring text from the source file; that means that you
< will still get error messages if you have invalid Texinfo markup
< within ignored text.
< @end ignore
---
> still parse the ignored text, in order to understand when to @emph{stop}
> ignoring text from the source file; that means that you may still get
> error messages if you have invalid Texinfo commands within ignored text.
1195c1210
< @node Minimum, Six Parts, Comments, Overview
---
> @node Minimum
1202,1206c1217,1222
< By convention, the names of Texinfo files end with one of the
< extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.
< The longer extension is preferred since it describes more clearly to a
< human reader the nature of the file. The shorter extensions are for
< operating systems that cannot handle long file names.@refill
---
> By convention, the namea of a Texinfo file ends with (in order of
> preference) one of the extensions @file{.texinfo}, @file{.texi},
> @file{.txi}, or @file{.tex}. The longer extensions are preferred since
> they describe more clearly to a human reader the nature of the file.
> The shorter extensions are for operating systems that cannot handle long
> file names.
1209c1225
< file @strong{must} begin with lines like this:@refill
---
> file @strong{must} begin with lines like this:
1220,1221c1236,1237
< The contents of the file follow this beginning, and then you @strong{must} end
< a Texinfo file with a line like this:@refill
---
> The contents of the file follow this beginning, and then you
> @strong{must} end a Texinfo file with a line like this:
1227c1243
< @findex input @r{(@TeX{} command)}
---
> @findex \input @r{(raw @TeX{} startup)}
1228a1245,1248
> Here's an explanation:
>
> @itemize @bullet
> @item
1232,1236c1252
< backslash, @samp{\}; this is correct for @TeX{}.) The
< @samp{@@setfilename} line provides a name for the Info file and tells
< @TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a
< title for the page headers (or footers) of the printed manual, and the
< default document description title for the @samp{<head>} in HTML format.
---
> backslash, @samp{\}; this is correct for @TeX{}.)
1237a1254,1265
> @item
> The @code{@@setfilename} line provides a name for the Info file and
> tells @TeX{} to open auxiliary files. @strong{All text before
> @code{@@setfilename} is ignored!}
>
> @item
> The @code{@@settitle} line specifies a title for the page headers (or
> footers) of the printed manual, and the default document description for
> the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
> is optional---if you don't mind your document being titled `Untitled'.
>
> @item
1239c1267
< the formatters that the file is ended and to stop formatting.@refill
---
> the formatters that the file is ended and to stop formatting.
1241c1269,1271
< Usually, you will not use quite such a spare format, but will include
---
> @end itemize
>
> Typically, you will not use quite such a spare format, but will include
1243c1273
< beginning of a Texinfo file, like this:@refill
---
> beginning of a Texinfo file, like this:
1259,1262c1289,1291
< The @code{@@c} lines which surround the @samp{@@setfilename} and
< @samp{@@settitle} lines are optional, but you need them in order to
< run @TeX{} or Info on just part of the file. (@xref{Start of Header},
< for more information.)@refill
---
> The @code{@@c} lines which surround the @code{@@setfilename} and
> @code{@@settitle} lines are optional, but you need them in order to
> run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
1264,1267c1293,1296
< Furthermore, you will usually provide a Texinfo file with a title
< page, indices, and the like. But the minimum, which can be useful
< for short documents, is just the three lines at the beginning and the
< one line at the end.@refill
---
> Furthermore, you will usually provide a Texinfo file with a title page,
> indices, and the like, all of which are explained in this manual. But
> the minimum, which can be useful for short documents, is just the three
> lines at the beginning and the one line at the end.
1269,1270c1298,1299
< @node Six Parts, Short Sample, Minimum, Overview
< @comment node-name, next, previous, up
---
>
> @node Six Parts
1273,1274c1302,1304
< Generally, a Texinfo file contains more than the minimal
< beginning and end---it usually contains six parts:@refill
---
> Generally, a Texinfo file contains more than the minimal beginning and
> end described in the previous section---it usually contains the six
> parts listed below. These are described fully in the following sections.
1278,1279c1308,1309
< The @dfn{Header} names the file, tells @TeX{} which definitions' file to
< use, and performs other ``housekeeping'' tasks.@refill
---
> The @dfn{Header} names the file, tells @TeX{} which definitions file to
> use, and other such housekeeping tasks.
1281,1286c1311,1314
< @item 2. Summary Description and Copyright
< The @dfn{Summary Description and Copyright} segment describes the document
< and contains the copyright notice and copying permissions for the Info
< file. The segment must be enclosed between @code{@@ifinfo} and
< @code{@@end ifinfo} commands so that the formatters place it only in the Info
< file.@refill
---
> @item 2. Summary and Copyright
> The @dfn{Summary and Copyright} segment describes the document and
> contains the copyright notice and copying permissions. This is done
> with the @code{@@copying} command.
1289,1292c1317,1320
< The @dfn{Title and Copyright} segment contains the title and copyright pages
< and copying permissions for the printed manual. The segment must be
< enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
< The title and copyright page appear only in the printed @w{manual}.@refill
---
> The @dfn{Title and Copyright} segment contains the title and copyright
> pages for the printed manual. The segment must be enclosed between
> @code{@@titlepage} and @code{@@end titlepage} commands. The title and
> copyright page appear only in the printed manual.
1295,1296c1323,1327
< The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
< Info file. It appears only in the Info file, in the `Top' node.@refill
---
> The `Top' node starts off the online output; it does not appear in the
> printed manual. We recommend including the copying permissions here as
> well as the segments above. And it contains at least a top-level menu
> listing the chapters, and possibly a @dfn{Master Menu} listing all the
> nodes in the entire document.
1299,1300c1330,1331
< The @dfn{Body} of the document may be structured like a traditional book or
< encyclopedia or it may be free form.@refill
---
> The @dfn{Body} of the document is typically structured like a
> traditional book or encyclopedia, but it may be free form.
1303,1305c1334,1336
< The @dfn{End} contains commands for printing indices and generating
< the table of contents, and the @code{@@bye} command on a line of its
< own.@refill
---
> The @dfn{End} segment contains commands for printing indices and
> generating the table of contents, and the @code{@@bye} command on a line
> of its own.
1307a1339
>
1310c1342
< @cindex Sample Texinfo file
---
> @cindex Sample Texinfo file, with comments
1312,1317c1344,1350
< Here is a complete but very short Texinfo file, in six parts. The first
< three parts of the file, from @samp{\input texinfo} through to
< @samp{@@end titlepage}, look more intimidating than they are. Most of
< the material is standard boilerplate; when you write a manual, simply
< insert the names for your own manual in this segment. (@xref{Beginning a
< File}.)@refill
---
> Here is a very short but complete Texinfo file, in the six conventional
> parts enumerated in the previous section, so you can see how Texinfo
> source appears in practice. The first three parts of the file, from
> @samp{\input texinfo} through to @samp{@@end titlepage}, look more
> intimidating than they are: most of the material is standard
> boilerplate; when writing a manual, you simply change the names as
> appropriate.
1318a1352,1354
> @xref{Beginning a File}, for full documentation on the commands listed
> here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
>
1320,1321c1356,1357
< not. The complete file, without any comments, is shown in
< @ref{Sample Texinfo File}.
---
> not. The complete file, without interspersed comments, is shown in
> @ref{Short Sample Texinfo File}.
1335,1336c1371
< @@settitle Sample Document
< @@setchapternewpage odd
---
> @@settitle Sample Manual 1.0
1344,1345c1379,1380
< The summary description and copyright segment does not
< appear in the printed document.
---
> A real manual includes more text here, according to the license under
> which it is distributed. @xref{GNU Sample Texts}.
1349,1350c1384,1385
< @@ifinfo
< This is a short example of a complete Texinfo file.
---
> @@copying
> This is a short example of a complete Texinfo file, version 1.0.
1353c1388
< @@end ifinfo
---
> @@end copying
1357c1392
< @subheading Part 3: Titlepage and Copyright
---
> @subheading Part 3: Titlepage, Contents, Copyright
1360c1395,1399
< The titlepage segment does not appear in the Info file.
---
> The titlepage segment does not appear in the online output, only in the
> printed manual. We use the @code{@@insertcopying} command to
> include the permission text from the previous section, instead of
> writing it out again; it is output on the back of the title page. The
> @code{@@contents} command generates a table of contents.
1364d1402
< @@contents
1366d1403
< @@sp 10
1374c1411
< Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
---
> @@insertcopying
1376a1414,1416
>
> @@c Output the table of contents at the beginning.
> @@contents
1382,1384c1422,1426
< The `Top' node contains the master menu for the Info file.
< Since a printed manual uses a table of contents rather than
< a menu, the master menu appears only in online output.
---
> The `Top' node contains the master menu for the Info file. Since a
> printed manual uses a table of contents rather than a menu, the master
> menu appears only in online output. We also include the copying text
> again for the benefit of online readers. And since the copying text
> begins with a brief description of the manual, no other text is needed.
1395a1438,1439
> @@insertcopying
>
1398,1399c1442,1443
< only chapter in this sample.
< * Concept Index:: This index has two entries.
---
> only chapter in this sample.
> * Index:: Complete index.
1404d1447
< @subheading Part 5: The Body of the Document
1405a1449,1450
> @subheading Part 5: The Body of the Document
>
1409c1454
< chapter containing an enumerated list.@refill
---
> chapter containing an enumerated list.
1415c1460,1461
< @@cindex Chapter, first
---
>
> @@cindex chapter, first
1419,1420c1465,1466
< This is the contents of the first chapter.
< @@cindex Another sample index entry
---
> This is the first chapter.
> @@cindex index entry, another
1434,1439d1479
<
< @group
< The @@code@{makeinfo@} command transforms a Texinfo file
< such as this into an Info file or other output;
< @@TeX@ typesets it for a printed manual.
< @end group
1441a1482
>
1446,1448c1487,1488
< unnumbered chapter of its own, (usually) for generating the table of
< contents, and the @code{@@bye} command that marks the end of the
< document.@refill
---
> unnumbered chapter of its own, and the @code{@@bye} command that marks
> the end of the document.
1452,1453c1492,1493
< @@node Concept Index
< @@unnumbered Concept Index
---
> @@node Index
> @@unnumbered Index
1463d1502
< @subheading The Results
1464a1504,1505
> @subheading Some Results
>
1470c1511
< This is the contents of the first chapter.
---
> This is the first chapter.
1481,1485d1521
<
< The @code{makeinfo} and @code{texinfo-format-buffer}
< commands transform a Texinfo file such as this into
< an Info file; and @TeX{} typesets it for a printed
< manual.
1493a1530
> @cindex Fox, Brian
1496,1497c1533,1534
< processors, and created Edition 1.0 of this manual. @w{Robert J.@:
< Chassell} greatly revised and extended the manual, starting with Edition
---
> processors, and created Edition 1.0 of this manual. @w{Robert J.@:}
> Chassell greatly revised and extended the manual, starting with Edition
1500,1501c1537,1538
< @command{info}. Karl Berry has made the updates since Texinfo 3.8 and
< subsequent releases, starting with Edition 2.22 of the manual.
---
> @command{info} programs. Karl Berry has continued maintenance since
> Texinfo 3.8 (manual edition 2.22).
1509,1517c1546,1554
< Our thanks go out to all who helped improve this work, particularly to
< Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
< reported mistakes and obscurities; our special thanks go to Melissa
< Weisshaus for her frequent and often tedious reviews of nearly similar
< editions. The indefatigable Eli Zaretskii and Andreas Schwab have
< provided patches beyond counting. Zack Weinberg did the impossible by
< implementing the macro syntax in @file{texinfo.tex}. Dozens of others
< have contributed patches and suggestions, they are gratefully
< acknowledged in the @file{ChangeLog} file. Our mistakes are our own.
---
> Our thanks go out to all who helped improve this work, particularly the
> indefatigable Eli Zaretskii and Andreas Schwab, who have provided
> patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
> tirelessly recorded and reported mistakes and obscurities. Zack
> Weinberg did the impossible by implementing the macro syntax in
> @file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her
> frequent reviews of nearly similar editions. Dozens of others have
> contributed patches and suggestions, they are gratefully acknowledged in
> the @file{ChangeLog} file. Our mistakes are our own.
1521a1559
> @cindex Texinfo history
1524,1525c1562,1564
< @code{@@} character to introduce commands as Texinfo does and strived to
< describe document contents rather than formatting.
---
> @code{@@} character to introduce commands, as Texinfo does. Much more
> consequentially, it strived to describe document contents rather than
> formatting, an idea wholeheartedly adopted by Texinfo.
1531c1570,1571
< language: Bo@TeX{}.
---
> language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been
> 0.02 on October 31, 1984.
1537c1577
< mark up language for text that is intended to be read both on line and
---
> mark up language for text that is intended to be read both online and
1541d1580
<
1551,1552c1590,1591
< comes with a special mode, called Texinfo
< mode, that provides Emacs commands and tools to help ease your work.@refill
---
> comes with a special mode, called Texinfo mode, that provides Emacs
> commands and tools to help ease your work.
1555c1594
< features of the Texinfo formatting language. If you are reading this
---
> features of the Texinfo formatting language. So if you are reading this
1558,1559c1597
< chapters which describe the Texinfo formatting language in
< detail.@refill
---
> chapters which describe the Texinfo formatting language in detail.
2053,2054c2091
< @node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
< @comment node-name, next, previous, up
---
> @node Updating Requirements
2074c2111
< must look either like this:@refill
---
> must look either like this:
2092a2130,2138
> or like this (without the explicit node pointers):
>
> @example
> @group
> @@node Comments
> @@section Comments
> @end group
> @end example
>
2098c2144
< @code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill
---
> @code{@@comment} line, you may also write an @code{@@ifinfo} line.)
2101c2147
< and be the first node in the file.@refill
---
> and be the first node in the file.
2116,2117c2162,2163
< @node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
< @comment node-name, next, previous, up
---
>
> @node Other Updating Commands
2247c2293
< include a line that has @code{@@setfilename} in its header.@refill
---
> include a line that has @code{@@setfilename} in its header.
2495a2542
>
2503,2504c2550,2551
< Texinfo file, such as the name of the file and the title of the
< document.@refill
---
> Texinfo file, such as the name for the output file(s), the title of the
> document, and the Top node.
2505a2553,2555
> This chapter expands on the minimal complete Texinfo source file
> previously given (@pxref{Six Parts}).
>
2507,2510c2557,2559
< * Four Parts:: Four parts begin a Texinfo file.
< * Sample Beginning:: Here is a sample beginning for a Texinfo file.
< * Header:: The very beginning of a Texinfo file.
< * Info Summary and Permissions:: Summary and copying permissions for Info.
---
> * Sample Beginning:: A sample beginning for a Texinfo file.
> * Texinfo File Header:: The first lines.
> * Document Permissions:: Ensuring your manual is free.
2512a2562
> * Global Document Commands:: Affecting formatting throughout.
2514c2564
< have the right to use and share software.
---
> have the right to use and share software.
2517,2520d2566
< @node Four Parts, Sample Beginning, Beginning a File, Beginning a File
< @ifinfo
< @heading Four Parts Begin a File
< @end ifinfo
2522,2556d2567
< Generally, the beginning of a Texinfo file has four parts:@refill
<
< @enumerate
< @item
< The header, delimited by special comment lines, that includes the
< commands for naming the Texinfo file and telling @TeX{} what
< definitions file to use when processing the Texinfo file.@refill
<
< @item
< A short statement of what the file is about, with a copyright notice
< and copying permissions. This is enclosed in @code{@@ifinfo} and
< @code{@@end ifinfo} commands so that the formatters place it only
< in the Info file.@refill
<
< @item
< A title page and copyright page, with a copyright notice and copying
< permissions. This is enclosed between @code{@@titlepage} and
< @code{@@end titlepage} commands. The title and copyright page appear
< only in the printed @w{manual}.@refill
<
< @item
< The `Top' node that contains a menu for the whole Info file. The
< contents of this node appear only in the Info file.@refill
< @end enumerate
<
< Also, optionally, you may include the copying conditions for a program
< and a warranty disclaimer. The copying section will be followed by an
< introduction or else by the first chapter of the manual.@refill
<
< Since the copyright notice and copying permissions for the Texinfo
< document (in contrast to the copying permissions for a program) are in
< parts that appear only in the Info file or only in the printed manual,
< this information must be given twice.@refill
<
<
2560c2571
< The following sample shows what is needed.@refill
---
> @cindex Example beginning of Texinfo file
2561a2573,2579
> The following sample shows what is needed. The elements given here are
> explained in more detail in the following sections. Other commands are
> often included at the beginning of Texinfo files, but the ones here are
> the most critical.
>
> @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
>
2565,2567c2583,2584
< @@setfilename @var{name-of-info-file}
< @@settitle @var{name-of-manual}
< @@setchapternewpage odd
---
> @@setfilename @var{infoname}.info
> @@settitle @var{name-of-manual} @var{version}
2570,2571c2587,2588
< @@ifinfo
< This file documents @dots{}
---
> @@copying
> This manual is for @var{program}, version @var{version}.
2573c2590
< Copyright @var{year} @var{copyright-owner}
---
> Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2575a2593
> @@quotation
2577c2595,2596
< @@end ifinfo
---
> @@end quotation
> @@end copying
2581,2585d2599
< @@c This title page illustrates only one of the
< @@c two methods of forming a title page.
< @end group
<
< @group
2598c2612
< Copyright @@copyright@{@} @var{year} @var{copyright-owner}
---
> @@insertcopying
2602,2603d2615
<
< Permission is granted to @dots{}
2605a2618,2620
> @@c So the toc is printed in the right place.
> @@contents
>
2610,2613c2625
< This document describes @dots{}
<
< This document applies to version @dots{}
< of the program named @dots{}
---
> @@insertcopying
2618d2629
< * Copying:: Your rights and freedoms.
2620c2631
< * Second Chapter:: @dots{}
---
> * Second Chapter:: @dots{}
2622c2633
< @dots{}
---
> * Copying:: Your rights and freedoms.
2627c2638
< @@node First Chapter
---
> @@node First Chapter
2629c2640,2643
< @@cindex Index entry for First Chapter
---
>
> @@cindex first chapter
> @@cindex chapter, first
> @dots{}
2634,2635c2648,2649
< @node Header
< @section The Texinfo File Header
---
> @node Texinfo File Header
> @section Texinfo File Header
2641,2642c2655,2657
< line, the @code{@@settitle} line, and the @code{@@setfilename} line. If
< you want to run @TeX{} on just a part of the Texinfo file, you must
---
> line, the @code{@@settitle} line, and the @code{@@setfilename} line.
>
> Also, if you want to format just part of the Texinfo file, you must
2644c2659,2661
< start-of-header and end-of-header lines.
---
> start-of-header and end-of-header lines. The start- and end-of-header
> lines are optional, but they do no harm, so you might as well always
> include them.
2646c2663,2666
< Thus, the beginning of a Texinfo file looks like this:
---
> Any command that affects document formatting as a whole makes sense to
> include in the header. @code{@@synindex} (@pxref{synindex}), for
> instance, is another command often included in the header. @xref{GNU
> Sample Texts}, for complete sample texts.
2648,2654c2668
< @example
< @group
< \input texinfo @@c -*-texinfo-*-
< @@setfilename sample.info
< @@settitle Sample Document
< @end group
< @end example
---
> Thus, the beginning of a Texinfo file generally looks like this:
2656,2658d2669
< @noindent
< or else like this:
<
2664c2675
< @@settitle Sample Document
---
> @@settitle Sample Manual 1.0
2674,2677d2684
< * documentdescription:: Document summary for the HTML output.
< * setchapternewpage:: Start chapters on right-hand pages.
< * paragraphindent:: Specify paragraph indentation.
< * exampleindent:: Specify environment indentation.
2689c2696
< with a line that looks like this:@refill
---
> with a line that looks like this:
2702,2707c2709,2715
< These are in a file called @file{texinfo.tex}, which is usually located
< in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash,
< @samp{\}, to mark the beginning of a command, just as Texinfo uses
< @samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\}
< to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
< is why it appears at the beginning of the file.@refill
---
> These are in a file called @file{texinfo.tex}, which should have been
> installed on your system along with either the @TeX{} or Texinfo
> software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
> a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
> file causes the switch from @samp{\} to @samp{@@}; before the switch
> occurs, @TeX{} requires @samp{\}, which is why it appears at the
> beginning of the file.
2711c2719
< specification tells Emacs to use Texinfo mode.@refill
---
> specification tells Emacs to use Texinfo mode.
2719,2723c2727
< Write a start-of-header line on the second line of a Texinfo file.
< Follow the start-of-header line with @code{@@setfilename} and
< @code{@@settitle} lines and, optionally, with other command lines, such
< as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
< end-of-header line (@pxref{End of Header}).@refill
---
> A start-of-header line is a Texinfo comment that looks like this:
2725,2729d2728
< With these lines, you can format part of a Texinfo file for Info or
< typeset part for printing.@refill
<
< A start-of-header line looks like this:@refill
<
2733a2733,2742
> Write the start-of-header line on the second line of a Texinfo file.
> Follow the start-of-header line with @code{@@setfilename} and
> @code{@@settitle} lines and, optionally, with other commands that
> globally affect the document formatting, such as @code{@@synindex} or
> @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
> Header}).
>
> The start- and end-of-header lines allow you to format only part of a
> Texinfo file for Info or printing. @xref{texinfo-format commands}.
>
2735c2744,2746
< comment is accidentally taken for a start-of-header line.@refill
---
> comment is accidentally taken for a start-of-header line. You can
> change it if you wish by setting the @code{tex-start-of-header} and/or
> @code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}.
2736a2748
>
2738,2739c2750
< @subsection @code{@@setfilename}
< @cindex Info file requires @code{@@setfilename}
---
> @subsection @code{@@setfilename}: Set the output file name
2740a2752
> @cindex Texinfo requires @code{@@setfilename}
2754a2767,2772
> @cindex Ignored before @code{@@setfilename}
> @cindex @samp{\input} source line ignored
> The Info formatting commands ignore everything written before the
> @code{@@setfilename} line, which is why the very first line of
> the file (the @code{\input} line) does not show up in the output.
>
2756,2761c2774,2777
< be generated. This name should be different from the name of the
< Texinfo file. There are two conventions for choosing the name: you can
< either remove the extension (such as @samp{.texi}) from the input file
< name, or replace it with the @samp{.info} extension. When producing
< HTML output, @code{makeinfo} will replace any extension with
< @samp{html}, or add @samp{.html} if the given name has no extension.
---
> be generated. This name must be different from the name of the Texinfo
> file. There are two conventions for choosing the name: you can either
> remove the extension (such as @samp{.texi}) entirely from the input file
> name, or, preferably, replace it with the @samp{.info} extension.
2763,2764c2779,2784
< Some operating systems cannot handle long file names. You can run into
< a problem even when the file name you specify is itself short enough.
---
> @cindex Length of file names
> @cindex File name collision
> @cindex Info file name, choosing
> Although an explicit @samp{.info} extension is preferable, some
> operating systems cannot handle long file names. You can run into a
> problem even when the file name you specify is itself short enough.
2768,2775c2788,2795
< file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.)
< The subfile name @file{texinfo.info-10}, for example, is too long for
< some systems; so the Info file name for this document is @file{texinfo}
< rather than @file{texinfo.info}. When @code{makeinfo} is running on
< operating systems such as MS-DOS which impose grave limits on file
< names, it will sometimes remove some characters from the original file
< name to leave enough space for the subfile suffix, thus producing files
< named @file{texin-10}, @file{gcc.i12}, etc.
---
> file name. (@xref{Tag and Split Files}.) The subfile name
> @file{texinfo.info-10}, for example, is too long for old systems with a
> 14-character limit on filenames; so the Info file name for this document
> is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
> is running on operating systems such as MS-DOS which impose severe
> limits on file names, it may remove some characters from the original
> file name to leave enough space for the subfile suffix, thus producing
> files named @file{texin-10}, @file{gcc.i12}, etc.
2777,2781c2797,2799
< @cindex Ignored before @code{@@setfilename}
< @cindex @samp{\input} source line ignored
< The Info formatting commands ignore everything written before the
< @code{@@setfilename} line, which is why the very first line of
< the file (the @code{\input} line) does not show up in the output.
---
> When producing HTML output, @code{makeinfo} will replace any extension
> with @samp{html}, or add @samp{.html} if the given name has no
> extension.
2802,2805d2819
< In the HTML file produced by @command{makeinfo}, @var{title} serves as
< the default document description in the @samp{<head>} part; see
< @ref{documentdescription}, for how to change that.
<
2807,2810c2821,2824
< follow it on the same line by the title. This tells @TeX{} the title
< to use in a header or footer. Do not write anything else on the line;
< anything on the line after the command is considered part of the
< title, including a comment.@refill
---
> follow it on the same line by the title. This tells @TeX{} the title to
> use in a header or footer. Do not write anything else on the line;
> anything on the line after the command is considered part of the title,
> including what would otherwise be a comment.
2811a2826,2841
> The @code{@@settitle} command should precede everything that generates
> actual output in @TeX{}.
>
> @cindex <title> HTML tag
> In the HTML file produced by @command{makeinfo}, @var{title} also serves
> as the document @samp{<title>} and the default document description in
> the @samp{<head>} part; see @ref{documentdescription}, for how to change
> that.
>
> The title in the @code{@@settitle} command does not affect the title as
> it appears on the title page. Thus, the two do not need not match
> exactly. A practice we recommend is to include the version or edition
> number of the manual in the @code{@@settitle} title; on the title page,
> the version number generally appears as a @code{@@subtitle} so it would
> be omitted from the @code{@@title}. (@xref{titlepage}.)
>
2816,2817c2846,2847
< from each @code{@@chapter} command.) Page footers are not
< printed.@refill
---
> from each @code{@@chapter} command.) By default, no page footer is
> printed.
2821c2851
< in the heading. @refill
---
> in the heading.
2823,2832d2852
< The @code{@@settitle} command should precede everything that generates
< actual output in @TeX{}.@refill
<
< Although the title in the @code{@@settitle} command is usually the
< same as the title on the title page, it does not affect the title as
< it appears on the title page. Thus, the two do not need not match
< exactly; and the title in the @code{@@settitle} command can be a
< shortened or expanded version of the title as it appears on the title
< page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
<
2837c2857
< information.)@refill
---
> information.)
2839,2841c2859,2860
< You may, if you wish, create your own, customized headings and
< footings. @xref{Headings, , Page Headings}, for a detailed discussion
< of this process.@refill
---
> You may, if you wish, create your own, customized headings and footings.
> @xref{Headings}, for a detailed discussion of this.
2844,2849c2863,2865
< @node documentdescription
< @subsection @code{@@documentdescription}: Summary text
< @cindex Document description
< @cindex Description of document
< @cindex Summary of document
< @cindex <meta> HTML tag, and document description
---
> @node End of Header
> @subsection End of Header
> @cindex End of header line
2851,2856c2867,2868
< When producing HTML output for a document, @command{makeinfo} writes a
< @samp{<meta>} element in the @samp{<head>} to give some idea of the
< content of the document. By default, this @dfn{description} is the title
< of the document, taken from the @code{@@settitle} command
< (@pxref{settitle}). To change this, use the @code{@@documentdescription}
< environment, as in:
---
> Follow the header lines with an @w{end-of-header} line, which is a
> Texinfo comment that looks like this:
2859,2861c2871
< @@documentdescription
< descriptive text
< @@end documendescription
---
> @@c %**end of header
2864,2865c2874
< @noindent
< This will produce the following output in the @samp{<head>} of the HTML:
---
> @xref{Start of Header}.
2867,2869d2875
< @example
< <meta name=description content="descriptive text">
< @end example
2871,2872c2877,2880
< @code{@@documentdescription} must be specified before the first node of
< the document.
---
> @node Document Permissions
> @section Document Permissions
> @cindex Document Permissions
> @cindex Copying Permissions
2873a2882,2886
> The copyright notice and copying permissions for a document need to
> appear in several places in the various Texinfo output formats.
> Therefore, Texinfo provides a command (@code{@@copying}) to declare
> this text once, and another command (@code{@@insertcopying}) to
> insert the text at appropriate points.
2875,2880c2888,2891
< @findex documentdescription
< @node setchapternewpage
< @subsection @code{@@setchapternewpage}:
< @cindex Starting chapters
< @cindex Pages, starting odd
< @findex setchapternewpage
---
> @menu
> * copying:: Declare the document's copying permissions.
> * insertcopying:: Where to insert the permissions.
> @end menu
2882,2887d2892
< In an officially bound book, text is usually printed on both sides of
< the paper, chapters start on right-hand pages, and right-hand pages have
< odd numbers. But in short reports, text often is printed only on one
< side of the paper. Also in short reports, chapters sometimes do not
< start on new pages, but are printed on the same page as the end of the
< preceding chapter, after a small amount of vertical whitespace.
2889,2892c2894,2896
< You can use the @code{@@setchapternewpage} command with various
< arguments to specify how @TeX{} should start chapters and whether it
< should format headers for printing on one or both sides of the paper
< (single-sided or double-sided printing).
---
> @node copying
> @subsection @code{@@copying}: Declare copying permissions
> @findex copying
2894,2895c2898,2902
< Write the @code{@@setchapternewpage} command at the beginning of a
< line followed by its argument.
---
> The @code{@@copying} command should be given very early in the document;
> right after the header material (@pxref{Texinfo File Header}) is the
> recommended location. It conventionally consists of a sentence or two
> about what the program is, the legal copyright line, and the copying
> permissions. Here is a skeletal example:
2897,2899d2903
< For example, you would write the following to cause each chapter to
< start on a fresh odd-numbered page:
<
2901,2902c2905,2907
< @@setchapternewpage odd
< @end example
---
> @@copying
> This manual is for @var{program} (version @var{version}),
> which @dots{}
2904,2905c2909
< You can specify one of three alternatives with the
< @code{@@setchapternewpage} command:
---
> Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2907,2962c2911,2914
< @table @asis
<
< @item @code{@@setchapternewpage off}
< Cause @TeX{} to typeset a new chapter on the same page as the last
< chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
< format page headers for single-sided printing.
<
< @item @code{@@setchapternewpage on}
< Cause @TeX{} to start new chapters on new pages and to format page
< headers for single-sided printing. This is the form most often used for
< short reports or personal printing. This is the default.
<
< @item @code{@@setchapternewpage odd}
< Cause @TeX{} to start new chapters on new, odd-numbered pages
< (right-handed pages) and to typeset for double-sided printing. This is
< the form most often used for books and manuals.
< @end table
<
< Texinfo does not have an @code{@@setchapternewpage even} command,
< because there is no printing tradition of starting chapters or books on
< an even-numbered page.
<
< If you don't like the default headers that @code{@@setchapternewpage}
< sets, you can explicit control them with the @code{@@headings} command.
< @xref{headings on off, , The @code{@@headings} Command}.
<
< At the beginning of a manual or book, pages are not numbered---for
< example, the title and copyright pages of a book are not numbered. By
< convention, table of contents and frontmatter pages are numbered with
< roman numerals and not in sequence with the rest of the document.
<
< Since an Info file does not have pages, the @code{@@setchapternewpage}
< command has no effect on it.
<
< We recommend not including any @code{@@setchapternewpage} command in
< your manual sources at all, since the desired output is not intrinsic to
< the document. Instead, if you don't want the default option (no blank
< pages, same headers on all pages) use the @option{--texinfo} option to
< @command{texi2dvi} to specify the output you want.
<
<
<
< @node paragraphindent
< @subsection Paragraph Indenting
< @cindex Indenting paragraphs
< @cindex Paragraph indentation
< @findex paragraphindent
<
< The Texinfo processors may insert whitespace at the beginning of the
< first line of each paragraph, thereby indenting that paragraph. You can
< use the @code{@@paragraphindent} command to specify this indentation.
< Write an @code{@@paragraphindent} command at the beginning of a line
< followed by either @samp{asis} or a number:
<
< @example
< @@paragraphindent @var{indent}
---
> @@quotation
> Permission is granted to @dots{}
> @@end quotation
> @@end copying
2965c2917,2918
< The indentation is according to the value of @var{indent}:
---
> The @code{@@quotation} has no legal significance; it's there to improve
> readability in some contexts.
2967,2969c2920,2922
< @table @asis
< @item @code{asis}
< Do not change the existing indentation (not implemented in @TeX{}).
---
> @xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
> @xref{GNU Free Documentation License}, for the license itself under
> which GNU and other free manuals are distributed.
2971,2972c2924,2927
< @item 0
< Omit all indentation.
---
> The text of @code{@@copying} is output as a comment at the beginning of
> Info, HTML, and XML output files. It is @emph{not} output implicitly in
> plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
> emit the copying information. See the next section for details.
2974,2976c2929,2933
< @item @var{n}
< Indent by @var{n} space characters in Info output, by @var{n} ems in
< @TeX{}.
---
> @findex copyright
> In output formats that support it (print and HTML), the
> @code{@@copyright@{@}} command generates a @samp{c} inside a circle. In
> Info and plain text, it generates @samp{(C)}. The copyright notice
> itself has the following legally defined sequence:
2978,3005d2934
< @end table
<
< The default value of @var{indent} is @samp{asis}.
< @code{@@paragraphindent} is ignored for HTML output.
<
< Write the @code{@@paragraphindent} command before or shortly after the
< end-of-header line at the beginning of a Texinfo file. (If you write
< the command between the start-of-header and end-of-header lines, the
< region formatting commands indent paragraphs as specified.)
<
< A peculiarity of the @code{texinfo-format-buffer} and
< @code{texinfo-format-region} commands is that they do not indent (nor
< fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
< @xref{Refilling Paragraphs}, for further information.
<
<
< @node exampleindent
< @subsection @code{@@exampleindent}: Environment Indenting
< @cindex Indenting environments
< @cindex Environment indentation
< @cindex Example indentation
< @findex exampleindent
<
< The Texinfo processors indent each line of @code{@@example} and similar
< environments. You can use the @code{@@exampleindent} command to specify
< this indentation. Write an @code{@@exampleindent} command at the
< beginning of a line followed by either @samp{asis} or a number:
<
3007c2936
< @@exampleindent @var{indent}
---
> Copyright @copyright{} @var{years} @var{copyright-owner}.
3010c2939,2942
< The indentation is according to the value of @var{indent}:
---
> @cindex Copyright word, always in English
> The word `Copyright' must always be written in English, even if the
> manual is otherwise in another language. This is due to international
> law.
3012,3014c2944,2948
< @table @asis
< @item @code{asis}
< Do not change the existing indentation (not implemented in @TeX{}).
---
> @cindex Years, in copyright line
> The list of years should include all years in which a version was
> completed (even if it was released in a subsequent year). Ranges are
> not allowed, each year must be written out individually, separated by
> commas.
3016,3017c2950,2953
< @item 0
< Omit all indentation.
---
> @cindex Copyright owner for FSF works
> The copyright owner (or owners) is whoever holds legal copyright on the
> work. In the case of works assigned to the FSF, the owner is `Free
> Software Foundation, Inc.'.
3019,3021c2955,2956
< @item @var{n}
< Indent environments by @var{n} space characters in Info output, by
< @var{n} ems in @TeX{}.
---
> @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
> additional information.
3023d2957
< @end table
3025,3026c2959,2964
< The default value of @var{indent} is 5. @code{@@exampleindent} is
< ignored for HTML output.
---
> @node insertcopying
> @subsection @code{@@insertcopying}: Include permissions text
> @findex insertcopying
> @cindex Copying text, including
> @cindex Permissions text, including
> @cindex Including permissions text
3028,3031c2966,2967
< Write the @code{@@exampleindent} command before or shortly after the
< end-of-header line at the beginning of a Texinfo file. (If you write
< the command between the start-of-header and end-of-header lines, the
< region formatting commands indent examples as specified.)
---
> The @code{@@insertcopying} command is simply written on a line by
> itself, like this:
3033,3040d2968
<
< @node End of Header
< @subsection End of Header
< @cindex End of header line
<
< Follow the header lines with an @w{end-of-header} line.
< An end-of-header line looks like this:@refill
<
3042c2970
< @@c %**end of header
---
> @@insertcopying
3045,3049c2973,2975
< If you include the @code{@@setchapternewpage} command between the
< start-of-header and end-of-header lines, @TeX{} will typeset a region as
< that command specifies. Similarly, if you include an @code{@@smallbook}
< command between the start-of-header and end-of-header lines, @TeX{} will
< typeset a region in the ``small'' book format.@refill
---
> It inserts the text previously defined by @code{@@copying}. Legally, it
> must be used on the copyright page in the printed manual
> (@pxref{Copyright}).
3051,3054c2977,2979
< @ifinfo
< The reason for the odd string of characters (@samp{%**}) is so that the
< @code{texinfo-tex-region} command does not accidentally find
< something that it should not when it is looking for the header.@refill
---
> Although it's not a legal requirement, we also strongly recommend using
> @code{@@insertcopying} in the Top node of your manual (@pxref{The Top
> Node}). Here's why:
3056,3058c2981,2987
< The start-of-header line and the end-of-header line are Texinfo mode
< variables that you can change.@refill
< @end ifinfo
---
> The @code{@@copying} command itself causes the permissions text to
> appear in an Info file @emph{before} the first node. The text is also
> copied into the beginning of each split Info output file, as is legally
> necessary. This location implies a human reading the manual using Info
> does @emph{not} see this text (except when using the advanced Info
> command @kbd{g *}). Therefore, an explicit @code{@@insertcopying}
> in the Top node makes it apparent to readers that the manual is free.
3060,3062c2989,2994
< @iftex
< @xref{Start of Header}.
< @end iftex
---
> Similarly, the @code{@@copying} text is automatically included at the
> beginning of each HTML output file, as an HTML comment. Again, this
> text is not visible (unless the reader views the HTML source). And
> therefore again, the @code{@@insertcopying} in the Top node is valuable
> because it makes the copying permissions visible and thus promotes
> freedom.
3063a2996,2997
> The permissions text defined by @code{@@copying} also appears
> automatically at the beginning of the XML output file.
3065,3066d2998
< @node Info Summary and Permissions
< @section Summary and Copying Permissions for Info
3068,3092d2999
< The title page and the copyright page appear only in the printed copy of
< the manual; therefore, the same information must be inserted in a
< section that appears only in the Info file. This section usually
< contains a brief description of the contents of the Info file, a
< copyright notice, and copying permissions.@refill
<
< The copyright notice should read:
<
< @example
< Copyright @var{year} @var{copyright-owner}
< @end example
<
< @noindent
< and be put on a line by itself.
<
< Standard text for the copyright permissions of free manuals is contained
< in an appendix to this manual (@pxref{Documentation Copying, , GNU Free
< Documentation License}).
<
< The permissions text appears in an Info file @emph{before} the first
< node. This mean that a reader does @emph{not} see this text when
< reading the file using Info (except when using the advanced Info command
< @kbd{g *}).
<
<
3094c3001
< @section The Title and Copyright Pages
---
> @section Title and Copyright Pages
3096,3099c3003,3005
< A manual's name and author are usually printed on a title page.
< Sometimes copyright information is printed on the title page as well;
< more often, copyright information is printed on the back of the title
< page.
---
> In hard copy output, the manual's name and author are usually printed on
> a title page. Copyright information is usually printed on the back of
> the title page.
3101,3102c3007,3008
< The title and copyright pages appear in the printed manual, but not in the
< Info file. Because of this, it is possible to use several slightly
---
> The title and copyright pages appear in the printed manual, but not in
> the Info file. Because of this, it is possible to use several slightly
3104,3105c3010,3011
< In addition, this part of the beginning of a Texinfo file contains the text
< of the copying permissions that will appear in the printed manual.@refill
---
> In addition, this part of the beginning of a Texinfo file contains the
> text of the copying permissions that appears in the printed manual.
3107c3013,3014
< @cindex Titlepage, for plain text
---
> @cindex Title page, for plain text
> @cindex Copyright page, for plain text
3109,3111c3016,3019
< output. Simply place any such leading material between @code{@@ifinfo}
< and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain
< text output. It will not show up in the Info readers.
---
> output. Simply place any such leading material between
> @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
> includes this when writing plain text (@samp{--no-headers}), along with
> an @code{@@insertcopying}.
3113,3115d3020
< @xref{Documentation Copying, , GNU Free Documentation License}, for the
< standard text for the copyright permissions.
<
3122c3027
< * Copyright & Permissions:: How to write the copyright notice and
---
> * Copyright:: How to write the copyright notice and
3131,3132c3036
< @node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
< @comment node-name, next, previous, up
---
> @node titlepage
3139c3043
< @code{@@end titlepage} on a line by itself.@refill
---
> @code{@@end titlepage} on a line by itself.
3161,3164c3065,3068
< that it is helpful to refer to versions of manuals as `editions' and
< versions of programs as `versions'; otherwise, we find we are liable to
< confuse each other in conversation by referring to both the
< documentation and the software with the same words.} for the manual.
---
> that it is helpful to refer to versions of independent manuals as
> `editions' and versions of programs as `versions'; otherwise, we find we
> are liable to confuse each other in conversation by referring to both
> the documentation and the software with the same words.} for the manual.
3167c3071
< @ref{makeinfo top, , @code{@@top}}.)
---
> @ref{The Top Node}.)
3189,3190c3093,3095
< @code{@@shorttitlepage} which takes a single argument as the title. The
< argument is typeset on a page by itself and followed by a blank page.
---
> @code{@@shorttitlepage} which takes the rest of the line as the title.
> The argument is typeset on a page by itself and followed by a blank
> page.
3201c3106
< first of the two methods for creating a title page in Texinfo.)@refill
---
> first of the two methods for creating a title page in Texinfo.)
3215c3120
< the remaining text on that line. Thus,@refill
---
> the remaining text on that line. Thus,
3223c3128
< in the title font.@refill
---
> in the title font.
3225c3130
< Use the @code{@@sp} command to insert vertical space. For example:@refill
---
> Use the @code{@@sp} command to insert vertical space. For example:
3234c3139
< command.)@refill
---
> command.)
3236c3141
< A template for this method looks like this:@refill
---
> A template for this method looks like this:
3252c3157
< The spacing of the example fits an 8.5 by 11 inch manual.@refill
---
> The spacing of the example fits an 8.5 by 11 inch manual.
3269c3174
< or author.@refill
---
> or author.
3280c3185
< flush to the right-hand side of the page.@refill
---
> flush to the right-hand side of the page.
3287c3192
< followed by an @code{@@page} command line.)@refill
---
> followed by an @code{@@page} command line.)
3291c3196
< an @code{@@author} command:@refill
---
> an @code{@@author} command:
3299c3204
< @code{@@author} commands:@refill
---
> @code{@@author} commands:
3309c3214
< (Only the bottom name is underlined with a black rule.)@refill
---
> (Only the bottom name is underlined with a black rule.)
3312c3217
< A template for this method looks like this:@refill
---
> A template for this method looks like this:
3344,3345c3249
< (The use of @code{@@value} here is explained in @ref{value
< Example,,@code{@@value} Example}.)
---
> (The use of @code{@@value} here is explained in @ref{value Example}.
3348,3349c3252,3253
< @node Copyright & Permissions
< @subsection Copyright Page and Permissions
---
> @node Copyright
> @subsection Copyright Page
3354,3357c3258,3263
< By international treaty, the copyright notice for a book should be
< either on the title page or on the back of the title page. The
< copyright notice should include the year followed by the name of the
< organization or person who owns the copyright.@refill
---
> By international treaty, the copyright notice for a book must be either
> on the title page or on the back of the title page. When the copyright
> notice is on the back of the title page, that page is customarily not
> numbered. Therefore, in Texinfo, the information on the copyright page
> should be within @code{@@titlepage} and @code{@@end titlepage}
> commands.
3359,3366c3265,3266
< When the copyright notice is on the back of the title page, that page
< is customarily not numbered. Therefore, in Texinfo, the information
< on the copyright page should be within @code{@@titlepage} and
< @code{@@end titlepage} commands.@refill
<
< @findex vskip
< @findex filll
< @cindex Vertical whitespace (@samp{vskip})
---
> @findex vskip @r{@TeX{} vertical skip}
> @findex filll @r{@TeX{} dimension}
3369,3370c3269
< bottom of the page, you can write a somewhat mysterious line after the
< @code{@@page} command that reads like this:@refill
---
> bottom of the page, use the following incantantion after @code{@@page}:
3378,3383c3277,3281
< commands. The @code{@@vskip} command inserts whitespace. The
< @samp{0pt plus 1filll} means to put in zero points of mandatory whitespace,
< and as much optional whitespace as needed to push the
< following text to the bottom of the page. Note the use of three
< @samp{l}s in the word @samp{filll}; this is the correct usage in
< @TeX{}.@refill
---
> commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
> plus 1filll} means to put in zero points of mandatory whitespace, and as
> much optional whitespace as needed to push the following text to the
> bottom of the page. Note the use of three @samp{l}s in the word
> @samp{filll}; this is correct.
3385,3388c3283,3284
< @findex copyright
< In a printed manual, the @code{@@copyright@{@}} command generates a
< @samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The
< copyright notice itself has the following legally defined sequence:@refill
---
> To insert the copyright text itself, write @code{@@insertcopying}
> next (@pxref{Document Permissions}):
3391c3287
< Copyright @copyright{} @var{year} @var{copyright-owner}
---
> @@insertcopying
3394,3395c3290,3291
< It is customary to put information on how to get a manual after the
< copyright notice, followed by the copying permissions for the manual.
---
> Follow the copying text by the publisher, ISBN numbers, cover art
> credits, and other such information.
3397,3400c3293
< Permissions must be given here as well as in the summary segment within
< @code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the
< header since this text appears only in the printed manual and the
< @samp{ifinfo} text appears only in the Info file.
---
> Here is an example putting all this together:
3402,3403c3295,3300
< @xref{Documentation Copying,,GNU Free Documentation License}, for the
< standard text.
---
> @example
> @@titlepage
> @dots{}
> @@page
> @@vskip 0pt plus 1filll
> @@insertcopying
3404a3302
> Published by @dots{}
3405a3304,3308
> Cover art by @dots{}
> @@end titlepage
> @end example
>
>
3413,3415c3316,3318
< An @code{@@end titlepage} command on a line by itself not only marks
< the end of the title and copyright pages, but also causes @TeX{} to start
< generating page headings and page numbers.
---
> The @code{@@end titlepage} command must be written on a line by itself.
> It not only marks the end of the title and copyright pages, but also
> causes @TeX{} to start generating page headings and page numbers.
3421,3422c3324
< (@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
< You can specify these formats in different ways:@refill
---
> You can specify these formats in different ways:
3429c3331
< (@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
---
> (@xref{setchapternewpage}.)
3441c3343
< information about page headings and footings.@refill
---
> information about page headings and footings.
3447c3349
< single-sided printing.@refill
---
> single-sided printing.
3449,3450c3351,3352
< @node headings on off, , end titlepage, Titlepage & Copyright Page
< @comment node-name, next, previous, up
---
>
> @node headings on off
3515,3516c3417
< @cindex @samp{@r{Top}} node
< @cindex Master menu
---
> @cindex Top node
3519c3420,3425
< The `Top' node is the node from which you enter an Info file.@refill
---
> The `Top' node is the node in which a reader enters an Info manual. As
> such, it should begin with the @code{@@insertcopying} command
> (@pxref{Document Permissions}) to provide a brief description of the
> manual (including the version number) and copying permissions, and end
> with a master menu for the whole manual. Of course you should include
> any other general information you feel a reader would find helpful.
3521,3525c3427,3431
< A `Top' node should contain a brief description of the Info file and an
< extensive, master menu for the whole Info file.
< This helps the reader understand what the Info file is
< about. Also, you should write the version number of the program to
< which the Info file applies; or, at least, the edition number.@refill
---
> @findex top
> It is also conventional to write an @code{@@top} sectioning command line
> containing the title of the document immediately after the @code{@@node
> Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
> Command}).
3527,3529c3433,3435
< The contents of the `Top' node should appear only in the Info file; none
< of it should appear in printed output, so enclose it between
< @code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not
---
> The contents of the `Top' node should appear only in the online output;
> none of it should appear in printed output, so enclose it between
> @code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
3532,3533c3438,3439
< @code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
< @xref{Conditionals, , Conditionally Visible Text}.)@refill
---
> @code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
> so. @xref{Conditionals, , Conditionally Visible Text}.)
3536,3537c3442,3443
< * Title of Top Node:: Sketch what the file is about.
< * Master Menu Parts:: A master menu has three or more parts.
---
> * Top Node Example::
> * Master Menu Parts::
3541,3542c3447,3448
< @node Title of Top Node
< @subsection `Top' Node Title
---
> @node Top Node Example
> @subsection Top Node Example
3544,3547c3450
< Sometimes, you will want to place an @code{@@top} sectioning command
< line containing the title of the document immediately after the
< @code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
< Sectioning Command}, for more information).@refill
---
> @cindex Top node example
3549,3551c3452
< For example, the beginning of the Top node of this manual contains an
< @code{@@top} sectioning command, a short description, and edition and
< version information. It looks like this:@refill
---
> Here is an example of a Top node.
3555,3557d3455
< @dots{}
< @@end titlepage
<
3559,3560c3457,3458
< @@node Top, Copying, , (dir)
< @@top Texinfo
---
> @@node Top
> @@top Sample Title
3562c3460
< Texinfo is a documentation system@dots{}
---
> @@insertcopying
3565,3569c3463
< @group
< This is edition@dots{}
< @dots{}
< @@end ifnottex
< @end group
---
> Additional general information.
3573,3575c3467,3468
< * Copying:: Texinfo is freely
< redistributable.
< * Overview:: What is Texinfo?
---
> * First Chapter::
> * Second Chapter::
3576a3470
> * Index::
3581,3585d3474
< In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
< level directory of the whole Info system, which is called @samp{(dir)}.
< The `Next' node refers to the first node that follows the main or master
< menu, which is usually the copying permissions, introduction, or first
< chapter.@refill
3587c3476
< @node Master Menu Parts, , Title of Top Node, The Top Node
---
> @node Master Menu Parts
3589c3478,3479
< @cindex Master menu parts
---
> @cindex Master menu
> @cindex Menu, master
3596c3486
< commands and does not appear in the printed document.@refill
---
> commands and does not appear in the printed document.
3598c3488
< Generally, a master menu is divided into parts.@refill
---
> Generally, a master menu is divided into parts.
3603c3493
< for the chapters, chapter-like sections, and the appendices.@refill
---
> for the chapters, chapter-like sections, and the appendices.
3606c3496
< The second part contains nodes for the indices.@refill
---
> The second part contains nodes for the indices.
3622c3512
< information.)@refill
---
> information.)
3625c3515
< (but has many more entries):@refill
---
> (but has many more entries):
3630,3633c3520,3521
< * Copying:: Texinfo is freely
< redistributable.
< * Overview:: What is Texinfo?
< * Texinfo Mode:: Special features in GNU Emacs.
---
> * Copying Conditions:: Your rights.
> * Overview:: Texinfo in brief.
3635d3522
< @dots{}
3639,3640c3526
< An entry for each @@-command.
< * Concept Index:: An entry for each concept.
---
> * Concept Index::
3649,3651c3535
< * Info Files:: What is an Info file?
< * Printed Manuals:: Characteristics of
< a printed manual.
---
> * Reporting Bugs:: @dots{}
3653d3536
< @dots{}
3657c3540
< Using Texinfo Mode
---
> Beginning a Texinfo File
3659,3660c3542
< * Info on a Region:: Formatting part of a file
< for Info.
---
> * Sample Beginning:: @dots{}
3662d3543
< @dots{}
3667a3549,3757
>
> @node Global Document Commands
> @section Global Document Commands
> @cindex Global Document Commands
>
> Besides the basic commands mentioned in the previous sections, here are
> additional commands which affect the document as a whole. They are
> generally all given before the Top node, if they are given at all.
>
> @menu
> * documentdescription:: Document summary for the HTML output.
> * setchapternewpage:: Start chapters on right-hand pages.
> * paragraphindent:: Specify paragraph indentation.
> * exampleindent:: Specify environment indentation.
> @end menu
>
>
> @node documentdescription
> @subsection @code{@@documentdescription}: Summary text
> @cindex Document description
> @cindex Description of document
> @cindex Summary of document
> @cindex Abstract of document
> @cindex <meta> HTML tag, and document description
> @findex documentdescription
>
> When producing HTML output for a document, @command{makeinfo} writes a
> @samp{<meta>} element in the @samp{<head>} to give some idea of the
> content of the document. By default, this @dfn{description} is the title
> of the document, taken from the @code{@@settitle} command
> (@pxref{settitle}). To change this, use the @code{@@documentdescription}
> environment, as in:
>
> @example
> @@documentdescription
> descriptive text.
> @@end documentdescription
> @end example
>
> @noindent
> This will produce the following output in the @samp{<head>} of the HTML:
>
> @example
> <meta name=description content="descriptive text.">
> @end example
>
> @code{@@documentdescription} must be specified before the first node of
> the document.
>
>
> @node setchapternewpage
> @subsection @code{@@setchapternewpage}:
> @cindex Starting chapters
> @cindex Pages, starting odd
> @findex setchapternewpage
>
> In an officially bound book, text is usually printed on both sides of
> the paper, chapters start on right-hand pages, and right-hand pages have
> odd numbers. But in short reports, text often is printed only on one
> side of the paper. Also in short reports, chapters sometimes do not
> start on new pages, but are printed on the same page as the end of the
> preceding chapter, after a small amount of vertical whitespace.
>
> You can use the @code{@@setchapternewpage} command with various
> arguments to specify how @TeX{} should start chapters and whether it
> should format headers for printing on one or both sides of the paper
> (single-sided or double-sided printing).
>
> Write the @code{@@setchapternewpage} command at the beginning of a
> line followed by its argument.
>
> For example, you would write the following to cause each chapter to
> start on a fresh odd-numbered page:
>
> @example
> @@setchapternewpage odd
> @end example
>
> You can specify one of three alternatives with the
> @code{@@setchapternewpage} command:
>
> @table @asis
>
> @item @code{@@setchapternewpage off}
> Cause @TeX{} to typeset a new chapter on the same page as the last
> chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
> format page headers for single-sided printing.
>
> @item @code{@@setchapternewpage on}
> Cause @TeX{} to start new chapters on new pages and to format page
> headers for single-sided printing. This is the form most often used for
> short reports or personal printing. This is the default.
>
> @item @code{@@setchapternewpage odd}
> Cause @TeX{} to start new chapters on new, odd-numbered pages
> (right-handed pages) and to typeset for double-sided printing. This is
> the form most often used for books and manuals.
> @end table
>
> Texinfo does not have an @code{@@setchapternewpage even} command,
> because there is no printing tradition of starting chapters or books on
> an even-numbered page.
>
> If you don't like the default headers that @code{@@setchapternewpage}
> sets, you can explicit control them with the @code{@@headings} command.
> @xref{headings on off, , The @code{@@headings} Command}.
>
> At the beginning of a manual or book, pages are not numbered---for
> example, the title and copyright pages of a book are not numbered. By
> convention, table of contents and frontmatter pages are numbered with
> roman numerals and not in sequence with the rest of the document.
>
> Since an Info file does not have pages, the @code{@@setchapternewpage}
> command has no effect on it.
>
> We recommend not including any @code{@@setchapternewpage} command in
> your manual sources at all, since the desired output is not intrinsic to
> the document. For a particular hard copy run, if you don't want the
> default option (no blank pages, same headers on all pages) use the
> @option{--texinfo} option to @command{texi2dvi} to specify the output
> you want.
>
>
> @node paragraphindent
> @subsection Paragraph Indenting
> @cindex Indenting paragraphs, control of
> @cindex Paragraph indentation control
> @findex paragraphindent
>
> The Texinfo processors may insert whitespace at the beginning of the
> first line of each paragraph, thereby indenting that paragraph. You can
> use the @code{@@paragraphindent} command to specify this indentation.
> Write an @code{@@paragraphindent} command at the beginning of a line
> followed by either @samp{asis} or a number:
>
> @example
> @@paragraphindent @var{indent}
> @end example
>
> The indentation is according to the value of @var{indent}:
>
> @table @asis
> @item @code{asis}
> Do not change the existing indentation (not implemented in @TeX{}).
>
> @item @code{none}
> @itemx 0
> Omit all indentation.
>
> @item @var{n}
> Indent by @var{n} space characters in Info output, by @var{n} ems in
> @TeX{}.
>
> @end table
>
> The default value of @var{indent} is 3. @code{@@paragraphindent} is
> ignored for HTML output.
>
> It is best to write the @code{@@paragraphindent} command before the
> end-of-header line at the beginning of a Texinfo file, so the region
> formatting commands indent paragraphs as specified. @xref{Start of
> Header}.
>
> A peculiarity of the @code{texinfo-format-buffer} and
> @code{texinfo-format-region} commands is that they do not indent (nor
> fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
> @xref{Refilling Paragraphs}, for further information.
>
>
> @node exampleindent
> @subsection @code{@@exampleindent}: Environment Indenting
> @cindex Indenting environments
> @cindex Environment indentation
> @cindex Example indentation
> @findex exampleindent
>
> The Texinfo processors indent each line of @code{@@example} and similar
> environments. You can use the @code{@@exampleindent} command to specify
> this indentation. Write an @code{@@exampleindent} command at the
> beginning of a line followed by either @samp{asis} or a number:
>
> @example
> @@exampleindent @var{indent}
> @end example
>
> The indentation is according to the value of @var{indent}:
>
> @table @asis
> @item @code{asis}
> Do not change the existing indentation (not implemented in @TeX{}).
>
> @item 0
> Omit all indentation.
>
> @item @var{n}
> Indent environments by @var{n} space characters in Info output, by
> @var{n} ems in @TeX{}.
>
> @end table
>
> The default value of @var{indent} is 5. @code{@@exampleindent} is
> ignored for HTML output.
>
> It is best to write the @code{@@exampleindent} command before the
> end-of-header line at the beginning of a Texinfo file, so the region
> formatting commands indent paragraphs as specified. @xref{Start of
> Header}.
>
>
3669d3758
< @comment node-name, next, previous, up
3677,3679c3766,3768
< License'' and the distribution information and a warranty disclaimer
< for the software that is documented, this section usually follows the
< `Top' node. The General Public License is very important to Project
---
> License'' and the distribution information and a warranty disclaimer for
> the software that is documented, we recommend placing this right after
> the `Top' node. The General Public License is very important to Project
3681c3770
< right to use and share the software.@refill
---
> right to use and share the software.
3684c3773
< by an introduction or else by the first chapter of the manual.@refill
---
> by an introduction or else by the first chapter of the manual.
3692,3694d3780
< Usually, an introduction is put in an @code{@@unnumbered} section.
< (@xref{unnumbered & appendix, , The @code{@@unnumbered} and
< @code{@@appendix} Commands}.)@refill
3696,3697c3782,3783
< @node Ending a File, Structuring, Beginning a File, Top
< @comment node-name, next, previous, up
---
>
> @node Ending a File
3705,3707c3791,3793
< (usually) to generate detailed and summary tables of contents. And it
< must include the @code{@@bye} command that marks the last line processed
< by @TeX{}.@refill
---
> (perhaps) to generate both the full and summary tables of contents.
> Finally, it must include the @code{@@bye} command that marks the last
> line to be processed.
3713,3715c3799,3800
< @@node Concept Index, , Variables Index, Top
< @@c node-name, next, previous, up
< @@unnumbered Concept Index
---
> @@node Index
> @@unnumbered Index
3718a3804
> @@shortcontents
3719a3806
>
3730,3732c3817,3819
< @node Printing Indices & Menus, Contents, Ending a File, Ending a File
< @comment node-name, next, previous, up
< @section Index Menus and Printing an Index
---
>
> @node Printing Indices & Menus
> @section Printing Indices and Menus
3739,3749c3826,3835
< To print an index means to include it as part of a manual or Info
< file. This does not happen automatically just because you use
< @code{@@cindex} or other index-entry generating commands in the
< Texinfo file; those just cause the raw data for the index to be
< accumulated. To generate an index, you must include the
< @code{@@printindex} command at the place in the document where you
< want the index to appear. Also, as part of the process of creating a
< printed manual, you must run a program called @code{texindex}
< (@pxref{Hardcopy}) to sort the raw data to produce a sorted
< index file. The sorted index file is what is actually used to
< print the index.@refill
---
> To print an index means to include it as part of a manual or Info file.
> This does not happen automatically just because you use @code{@@cindex}
> or other index-entry generating commands in the Texinfo file; those just
> cause the raw data for the index to be accumulated. To generate an
> index, you must include the @code{@@printindex} command at the place in
> the document where you want the index to appear. Also, as part of the
> process of creating a printed manual, you must run a program called
> @code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
> sorted index file. The sorted index file is what is actually used to
> print the index.
3751,3757c3837,3840
< Texinfo offers six different types of predefined index: the concept
< index, the function index, the variables index, the keystroke index, the
< program index, and the data type index (@pxref{Predefined Indices}). Each
< index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
< @samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them
< into separate sections (@pxref{Combining Indices}); or you may define
< your own indices (@pxref{New Indices, , Defining New Indices}).@refill
---
> Texinfo offers six separate types of predefined index, each with a
> two-letter abbreviation, as illustrated in the following table.
> However, you may merge indices (@pxref{Combining Indices}) or define
> your own indices (@pxref{New Indices}).
3759,3761c3842,3843
< The @code{@@printindex} command takes a two-letter index name, reads
< the corresponding sorted index file and formats it appropriately into
< an index.@refill
---
> Here are the predefined indices, their abbreviations, and the
> corresponding index entry commands:
3763,3765d3844
< @ignore
< The two-letter index names are:
<
3768c3847
< concept index
---
> concept index (@code{@@cindex})
3770c3849
< function index
---
> function index (@code{@@findex})
3772c3851
< variable index
---
> variable index (@code{@@index})
3774c3853
< key index
---
> key index (@code{@@kindex})
3776c3855
< program index
---
> program index (@code{@@pindex})
3778c3857
< data type index
---
> data type index (@code{@@tindex})
3780,3786d3858
< @end ignore
< The @code{@@printindex} command does not generate a chapter heading
< for the index. Consequently, you should precede the
< @code{@@printindex} command with a suitable section or chapter command
< (usually @code{@@unnumbered}) to supply the chapter heading and put
< the index into the table of contents. Precede the @code{@@unnumbered}
< command with an @code{@@node} line.@refill
3788c3860,3870
< @need 1200
---
> The @code{@@printindex} command takes a two-letter index abbreviation,
> reads the corresponding sorted index file and formats it appropriately
> into an index.
>
> The @code{@@printindex} command does not generate a chapter heading for
> the index. Consequently, you should precede the @code{@@printindex}
> command with a suitable section or chapter command (usually
> @code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading
> and put the index into the table of contents. Precede the
> @code{@@unnumbered} command with an @code{@@node} line.
>
3793,3794c3875
< @@node Variable Index, Concept Index, Function Index, Top
< @@comment node-name, next, previous, up
---
> @@node Variable Index
3801,3802c3882
< @@node Concept Index, , Variable Index, Top
< @@comment node-name, next, previous, up
---
> @@node Concept Index
3810,3813d3889
< Readers often prefer that the concept index come last in a book,
< since that makes it easiest to find. Having just one index helps
< readers also, since then they have only one place to look
< (@pxref{synindex}).
3814a3891,3893
> We recommend placing the concept index last, since that makes it easiest
> to find. We also recommend having a single index whenever possible,
> since then readers have only one place to look (@pxref{Combining Indices}).
3815a3895
>
3834,3835c3914,3915
< unnumbered chapters. (Headings generated by the @code{@@heading}
< series of commands do not appear in the table of contents.)
---
> unnumbered chapters. Headings generated by the @code{@@heading}
> series of commands do not appear in the table of contents.
3839,3840c3919
< (@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
< two commands are exactly the same.)@refill
---
> (@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
3843,3845c3922,3924
< chapters (and appendices and unnumbered chapters). Omit sections, subsections
< and subsubsections. Only a long manual needs a short table
< of contents in addition to the full table of contents.@refill
---
> chapters, appendices, and unnumbered chapters. Sections, subsections
> and subsubsections are omitted. Only a long manual needs a short table
> of contents in addition to the full table of contents.
3884c3963
< Texinfo documents). You can do this by specifying
---
> Texinfo documents, at this writing). You can do this by specifying
3894,3896c3973,3975
< example). Or, if you're using @command{texi2dvi} (@pxref{Format with
< texi2dvi}), you can use its @option{--texinfo} option to specify this
< without altering the source file at all. For example:
---
> example). We recommend using @command{texi2dvi} (@pxref{Format with
> texi2dvi}) to specify this without altering the source file at all. For
> example:
3898c3977
< texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi
---
> texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
3907,3908c3986,3987
< the formatting commands see any of the file following @code{@@bye}.
< The @code{@@bye} command should be on a line by itself.@refill
---
> the formatting commands reading anything following @code{@@bye}. The
> @code{@@bye} command should be on a line by itself.
3910,3915c3989,3995
< If you wish, you may follow the @code{@@bye} line with notes. These notes
< will not be formatted and will not appear in either Info or a printed
< manual; it is as if text after @code{@@bye} were within @code{@@ignore}
< @dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line
< with a local variables list. @xref{Compile-Command, , Using Local
< Variables and the Compile Command}, for more information.@refill
---
> If you wish, you may follow the @code{@@bye} line with notes. These
> notes will not be formatted and will not appear in either Info or a
> printed manual; it is as if text after @code{@@bye} were within
> @code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
> @code{@@bye} line with a local variables list for Emacs.
> @xref{Compile-Command, , Using Local Variables and the Compile Command},
> for more information.
4637d4716
< * Top Node Summary:: Write a brief description for readers.
4826c4905
< @cindex Case in nodename
---
> @cindex Case in node name
4832,4833c4911
< @node First Node, makeinfo top command, Node Line Requirements, node
< @comment node-name, next, previous, up
---
> @node First Node
4839,4841c4917,4919
< included file (@pxref{Include Files}). The Top node contains the main
< or master menu for the document, and a short summary of the document
< (@pxref{Top Node Summary}).
---
> included file (@pxref{Include Files}). The Top node should contain a
> short summary, copying permissions, and a master menu. @xref{The Top
> Node}, for more information on the Top node contents and examples.
4842a4921,4925
> Here is a description of the node pointers to be used in the Top node:
>
> @itemize @bullet
>
> @item
4847,4852c4930
< menu that leads to this file. Specify the file name in parentheses. If
< the file is to be installed directly in the Info directory file, use
< @samp{(dir)} as the parent of the Top node; this is short for
< @samp{(dir)top}, and specifies the Top node in the @file{dir} file,
< which contains the main menu for the Info system as a whole. For
< example, the @code{@@node Top} line of this manual looks like this:
---
> menu that leads to this file. Specify the file name in parentheses.
4854,4856c4932,4935
< @example
< @@node Top, Copying, , (dir)
< @end example
---
> Usually, all Info files are installed in the same Info directory tree;
> in this case, use @samp{(dir)} as the parent of the Top node; this is
> short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
> file, which contains the main menu for the Info system as a whole.
4858,4861c4937
< @noindent
< (You can use the Texinfo updating commands or the @code{makeinfo}
< utility to insert these pointers automatically.)
<
---
> @item
4863,4867c4939,4943
< Do not define the `Previous' node of the Top node to be @samp{(dir)}, as
< it causes confusing behavior for users: if you are in the Top node and
< hits @key{DEL} to go backwards, you wind up in the middle of the
< some other entry in the @file{dir} file, which has nothing to do with
< what you were reading.
---
> On the other hand, do not define the `Previous' node of the Top node to
> be @samp{(dir)}, as it causes confusing behavior for users: if you are
> in the Top node and hits @key{DEL} to go backwards, you wind up in the
> middle of the some other entry in the @file{dir} file, which has nothing
> to do with what you were reading.
4868a4945,4951
> @item
> @cindex Next node of Top node
> The `Next' node of the Top node should be the first chapter in your
> document.
>
> @end itemize
>
4871a4955,4956
> For concreteness, here is an example with explicit pointers (which you
> can maintain automatically with the texinfo mode commands):
4873,4874c4958,4966
< @node makeinfo top command, Top Node Summary, First Node, node
< @comment node-name, next, previous, up
---
> Or you can leave the pointers off entirely and let the tools implicitly
> define them. This is recommended. Thus:
>
> @example
> @@node Top
> @end example
>
>
> @node makeinfo top command
4878,4879c4970,4971
< A special sectioning command, @code{@@top}, has been created for use
< with the @code{@@node Top} line. The @code{@@top} sectioning command tells
---
> A special sectioning command, @code{@@top} should be used with the
> @code{@@node Top} line. The @code{@@top} sectioning command tells
4881,4885c4973,4976
< the information that @code{makeinfo} needs to insert node
< pointers automatically. Write the @code{@@top} command at the
< beginning of the line immediately following the @code{@@node Top}
< line. Write the title on the remaining part of the same line as the
< @code{@@top} command.@refill
---
> the information that @code{makeinfo} needs to insert node pointers
> automatically. Write the @code{@@top} command at the beginning of the
> line immediately following the @code{@@node Top} line. Write the title
> on the remaining part of the same line as the @code{@@top} command.
4887,4888c4978,4980
< In Info, the @code{@@top} sectioning command causes the title to appear on a
< line by itself, with a line of asterisks inserted underneath.@refill
---
> In Info, the @code{@@top} sectioning command causes the title to appear
> on a line by itself, with a line of asterisks inserted underneath, as
> other sectioning commands do.
4897c4989
< create or update pointers and menus.@refill
---
> create or update pointers and menus.
4898a4991
> Thus, in practice, a Top node starts like this:
4900,4902c4993,4996
< @node Top Node Summary, , makeinfo top command, node
< @subsection The `Top' Node Summary
< @cindex @samp{@r{Top}} node summary
---
> @example
> @@node Top
> @@top Your Manual Title
> @end example
4904,4908d4997
< You can help readers by writing a summary in the `Top' node, after the
< @code{@@top} line, before the main or master menu. The summary should
< briefly describe the document. In Info, this summary will appear just
< before the master menu. In a printed manual, this summary will appear
< on a page of its own.@refill
4910,4929d4998
< If you do not want the summary to appear on a page of its own in a
< printed manual, you can enclose the whole of the `Top' node, including
< the @code{@@node Top} line and the @code{@@top} sectioning command line
< or other sectioning command line between @code{@@ifinfo} and @code{@@end
< ifinfo}. This prevents any of the text from appearing in the printed
< output. (@pxref{Conditionals, , Conditionally Visible Text}). You can
< repeat the brief description from the `Top' node within @code{@@iftex}
< @dots{} @code{@@end iftex} at the beginning of the first chapter, for
< those who read the printed manual. This saves paper and may look
< neater.@refill
<
< You should write the version number of the program to which the manual
< applies in the summary. This helps the reader keep track of which
< manual is for which version of the program. If the manual changes more
< frequently than the program or is independent of it, you should also
< include an edition number for the manual. (The title page should also
< contain this information: see @ref{titlepage, ,
< @code{@@titlepage}}.)@refill
<
<
5055c5124
< not the printed document.@refill
---
> not the printed document.
5058c5127
< @code{@@node} line, and heading, and look like this:@refill
---
> @code{@@node} line, and heading, and look like this:
5079,5081c5148,5149
< The Texinfo file for this document contains more than a dozen
< examples of this procedure. One is at the beginning of this chapter;
< another is at the beginning of @ref{Cross References}. @refill
---
> The Texinfo file for this document contains a number of
> examples of this procedure; one is at the beginning of this chapter.
6410c6478
< * verb:: A verbatim sequence of characters.
---
> * verb:: A verbatim sequence of characters.
7352c7420
< * verbatiminclude:: Including a file verbatim.
---
> * verbatiminclude:: Including a file verbatim.
7567,7568c7635,7636
< block. No character substitutions are made all commands
< are ignored, until the next 'end verbatim' command.
---
> block. No character substitutions are made. All commands
> are ignored, until `<at>end verbatim'.
7582c7650
< @c urg: got to trick this a bit: can't use @end verbatim inside @verbatim
---
> @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
7604c7672
< will disappear, tyically you should put a blank line before the
---
> produce no output, tyically you should put a blank line before the
7607c7675
< ending @code{@@end verbatim} will appear in the output.)
---
> ending @code{@@end verbatim} will appear in the output.
8814c8882
< @node syncodeindex, synindex, Combining Indices, Combining Indices
---
> @node syncodeindex
8962c9030
< @code{@@syncodeindex} commands (@pxref{Header}).@refill
---
> @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
8963a9032
>
9031c9100
< @findex @@ @r{(single @samp{@@})}
---
> @findex @@ @r{(literal @samp{@@})}
9041,9042c9110,9111
< @findex @{ @r{(single @samp{@{})}
< @findex @} @r{(single @samp{@}})}
---
> @findex @{ @r{(literal @samp{@{})}
> @findex @} @r{(literal @samp{@}})}
9267c9336
< @findex "
---
> @findex " @r{(umlaut accent)}
9269c9338
< @findex '
---
> @findex ' @r{(umlaut accent)}
9271c9340
< @findex =
---
> @findex = @r{(macron accent)}
9273c9342
< @findex ^
---
> @findex ^ @r{(circumflex accent)}
9275c9344
< @findex `
---
> @findex ` @r{(grave accent)}
9277c9346
< @findex ~
---
> @findex ~ @r{(tilde accent)}
9279c9348
< @findex ,
---
> @findex , @r{(cedilla accent)}
9283c9352
< @findex H
---
> @findex H @r{(Hungarian umlaut accent)}
9289c9358
< @findex u
---
> @findex u @r{(breve accent)}
9295c9364
< @findex v
---
> @findex v @r{(check accent)}
9542,9543c9611,9612
< simplest to use @samp{\} instead of @samp{@@} for these commands. As
< in:
---
> conventional to use @samp{\} instead of @samp{@@} for these commands.
> As in:
9560a9630,9637
> @findex \ @r{(literal \ in @code{@@math})}
> Since @samp{\} is an escape character inside @code{@@math}, you can use
> @code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
> but you'll get the literal @samp{\\} in Info). @code{@@\} is not
> defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
> literal @samp{\}.
>
>
10374c10451
< @findex -
---
> @findex - @r{(discretionary hyphen)}
10388,10391c10465,10468
< not have to) hyphenate. This is especially useful when you notice
< an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
< hboxes}). @TeX{} will not insert any hyphenation points in a word
< containing @code{@@-}.
---
> not have to) hyphenate. This is especially useful when you notice an
> overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
> hboxes}). @TeX{} will not insert any hyphenation points itself into a
> word containing @code{@@-}.
11747a11825,11827
> Texinfo has a pair of commands for each output format, to allow
> conditional inclusion of text for a particular output format.
>
11751,11755c11831,11834
< in the Info file. The @code{@@ifinfo} command should appear on a line
< by itself; end the Info-only text with a line containing @code{@@end
< ifinfo} by itself. At the beginning of a Texinfo file, the Info
< permissions are contained within a region marked by @code{@@ifinfo} and
< @code{@@end ifinfo}. (@xref{Info Summary and Permissions}.)
---
> in the Info file and (for historical compatibility) the plain text
> output. The @code{@@ifinfo} command should appear on a line by itself;
> end the Info-only text with a line containing @code{@@end ifinfo} by
> itself.
11759,11763c11838,11845
< The @code{@@iftex} and @code{@@end iftex} commands are similar to the
< @code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
< specify text that will appear in the printed manual but not in the Info
< file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
< specify text to appear only in HTML output.@refill
---
> @findex ifplaintext
> The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
> @code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
> will appear in the printed manual but not in the Info file. Likewise
> for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
> appear only in HTML output. And for @code{@@ifplaintext} and
> @code{@@end ifplaintext}, which specify text to appear only in plain
> text output.
11772c11854
< However, this text will appear only in Info.
---
> However, this text will appear only in Info (or plain text).
11776a11859,11861
> @@ifplaintext
> Whereas this text will only appear in plain text.
> @@end ifplaintext
11785c11870
< However, this text will appear only in Info.
---
> However, this text will appear only in Info (or plain text).
11789a11875,11877
> @ifplaintext
> Whereas this text will only appear in plain text.
> @end ifplaintext
11799a11888
> @findex ifnotplaintext
11806a11896
> @@ifnotplaintext @dots{} @@end ifnotplaintext
11811c11901
< actually appear on lines by themselves.)
---
> appear on lines by themselves in your actual source file.)
11813,11814c11903,11904
< If the output file is not being made for the given format, the region is
< included. Otherwise, it is ignored.
---
> If the output file is @emph{not} being made for the given format, the
> region is included. Otherwise, it is ignored.
11815a11906,11917
> With one exception (for historical compatibility): @code{@@ifnotinfo}
> text is omitted for both Info and plain text output, not just Info. To
> specify text which appears only in Info and not in plain text, use
> @code{@@ifnotplaintext}, like this:
> @example
> @ifinfo
> @ifnotplaintext
> This will be in Info, but not plain text.
> @end ifnotplaintext
> @end ifinfo
> @end example
>
12083,12084c12185,12187
< you need to change when you record an update to a manual. Here is how
< it is done in @cite{The GNU Make Manual}:
---
> you need to change when you record an update to a manual. @xref{GNU
> Sample Texts}, for an example of this same principle can work with
> Automake distributions, and full texts.
12085a12189,12191
> Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
> Manual}):
>
12100,12101c12206
< Write text for the first @code{@@ifinfo} section, for people reading the
< Texinfo file:
---
> Write text for the @code{@@copying} section (@pxref{copying}):
12104a12210
> @@copying
12108a12215,12219
>
> Copyright @dots{}
>
> Permission is granted @dots{}
> @@end copying
12114,12115d12224
< @c List only the month and the year since that looks less fussy on a
< @c printed cover than a date that lists the day as well.
12118a12228
> @@titlepage
12122a12233,12236
> @@page
> @@insertcopying
> @dots{}
> @@end titlepage
12135,12138c12249,12255
< This is Edition @@value@{EDITION@}
< of the @@cite@{GNU Make Manual@},
< last updated @@value@{UPDATED@}
< for @@code@{make@} Version @@value@{VERSION@}.
---
> @@ifnottex
> @@node Top
> @@top Make
>
> @@insertcopying
> @dots{}
> @@end ifnottex
12142,12143c12259,12260
< After you format the manual, the text in the first @code{@@ifinfo}
< section looks like this:
---
> After you format the manual, the @code{@@value} constructs have been
> expanded, so the output contains text like this:
12153,12154c12270,12271
< When you update the manual, change only the values of the flags; you do
< not need to edit the three sections.
---
> When you update the manual, you change only the values of the flags; you
> do not need to edit the three sections.
12663c12780
< @@ifinfo
---
> @@ifnottex
12669c12786
< @@end ifinfo
---
> @@end ifnottex
13235,13236c13352
< @cindex Customize Emacs package
< @findex Development/Docs/Texinfo Customize group
---
> @cindex Customize Emacs package (@t{Development/Docs/Texinfo})
13245c13361
< @node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy
---
> @node Compile-Command
13646c13762
< @findex mag @r{(@TeX{} command)}
---
> @findex \mag @r{(raw @TeX{} magnification)}
13717c13833
< * Installing an Info File::
---
> * Installing an Info File::
13797d13912
< @comment node-name, next, previous, up
13923,13928c14038,14043
< For Info output, do not include menus or node lines in the output and
< write to standard output (unless @option{--output} is specified). This
< results in an @sc{ascii} file that you cannot read in Info since it does
< not contain the requisite nodes or menus. It is primarily useful to
< extract certain pieces of a manual into separate files to be included in
< a distribution, such as @file{INSTALL} files.
---
> @cindex Node separators, omitting
> @cindex Menus, omitting
> For Info output, do not include menus or node separator lines in the
> output. This results in a simple plain text file that you can (for
> example) send in email without complications, or include in a
> distribution (as in an @file{INSTALL} file).
13931,13932c14046,14049
< For HTML output, if @samp{--no-split} is also specified, do not include a
< navigation links at the top of each node. @xref{makeinfo html}.
---
> For HTML output, likewise omit menus. And if @samp{--no-split} is also
> specified, do not include a navigation links at the top of each node
> (these are never included in the default case of split output).
> @xref{makeinfo html}.
13933a14051,14053
> In both cases, write to standard output by default (can still be
> overridden by @option{-o}).
>
14425,14427c14545,14548
< in browsers without table support. Please report output from an
< error-free run of @code{makeinfo} which violates the @w{HTML 3.2} DTD as
< a bug.
---
> in browsers without table support. The HTML 4 @samp{lang} attribute on
> the @samp{<html>} attribute is also used. Please report output from an
> error-free run of @code{makeinfo} which has browser portability problems
> as a bug.
14451c14572
< * New Info File:: Listing a new info file.
---
> * New Info File:: Listing a new Info file.
14691,14692c14812,14813
< In order for the Info file to work with @code{install-info}, you should
< use the commands @code{@@dircategory} and
---
> In order for the Info file to work with @code{install-info}, you include
> the commands @code{@@dircategory} and
14740d14860
< Linux
14892c15012
< an @code{@@refill} command. @xref{Line Breaks}.@refill
---
> an @code{@@refill} command. @xref{Line Breaks}.
14923a15044,15047
> @item @@\
> Stands for a backslash (@samp{\}) inside @code{@@math}.
> @xref{math,,@code{math}}.
>
14927c15051
< character, as in @^o.
---
> character, as in @^o and @`e.
15320c15444
< pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
---
> pages. @xref{Custom Headings, ,
15419,15420c15543
< Print @var{text} in @i{italic} font. No effect in Info.
< @xref{Fonts}.@refill
---
> Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}.
15431,15433c15554,15557
< the printed manual. The text appears only in the HTML resp.@: Info
< file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
< @xref{Conditionals}.
---
> the printed manual. @code{@@ifhtml} text appears only in the HTML
> output. @code{@@ifinfo} output appears in both Info and (for historical
> compatibility) plain text output . Pair with @code{@@end ifhtml}
> resp.@: @code{@@end ifinfo}. @xref{Conditionals}.
15436a15561
> @itemx @@ifnotplaintext
15439,15441c15564,15569
< not the others. The text appears only in the format not specified.
< Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
< @code{@@end ifnotinfo}. @xref{Conditionals}.
---
> not the others. The text appears in the formats not specified:
> @code{@@ifnothtml} text is omitted from html output, etc. The exception
> is @code{@@ifnotinfo} text, which is omitted from plain text output as
> well as Info output. Pair with @code{@@end ifnothtml} resp.@:
> @code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
> @code{@@end ifnottex}. @xref{Conditionals}.
15442a15571,15574
> @item @@ifplaintext
> Begin a stretch of text that appears only in the plain text output.
> Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
>
15479c15611
< @xref{Header, , The Texinfo File Header}.@refill
---
> @xref{Texinfo File Header}.
15585c15717
< pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
---
> pages. @xref{Custom Headings, ,
15881c16013
< topmost @code{@@node} line in the file, which must be written on the line
---
> topmost @code{@@node} in the file, which must be written on the line
15885,15886c16017,16018
< line normally should be enclosed by @code{@@ifinfo} and @code{@@end
< ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
---
> line normally should be enclosed by @code{@@ifnottex} and @code{@@end
> ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
15968,15969c16100
< only in contexts ignored for Info. @xref{Copyright & Permissions, ,
< The Copyright Page and Printed Permissions}.@refill
---
> only in contexts ignored for Info. @xref{Copyright}.
16140,16141c16271,16275
< Write the edition and version numbers and date in three places in every
< manual:
---
> Include edition numbers, version numbers, and dates in the
> @code{@@copying} text (for people reading the Texinfo file, and for the
> legal copyright in the output files). Then use @code{@@insertcopying}
> in the @code{@@titlepage} section (for people reading the printed
> output) and the Top node (for people reading the online output).
16143,16145c16277,16278
< @enumerate
< @item
< In the first @code{@@ifinfo} section, for people reading the Texinfo file.
---
> It is easiest to do this using @code{@@set} and @code{@@value}.
> @xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
16147,16148d16279
< @item
< In the @code{@@titlepage} section, for people reading the printed manual.
16150,16183d16280
< @item
< In the `Top' node, for people reading the Info file.
< @end enumerate
<
< @noindent
< Also, it helps to write a note before the first @code{@@ifinfo}
< section to explain what you are doing.
<
< @need 800
< @noindent
< For example:
<
< @example
< @group
< @@c ===> NOTE! <==
< @@c Specify the edition and version numbers and date
< @@c in *three* places:
< @@c 1. First ifinfo section 2. title page 3. top node
< @@c To find the locations, search for !!set
< @end group
<
< @group
< @@ifinfo
< @@c !!set edition, date, version
< This is Edition 4.03, January 1992,
< of the @@cite@{GDB Manual@} for GDB Version 4.3.
< @dots{}
< @end group
< @end example
<
< @noindent
< ---or use @code{@@set} and @code{@@value}
< (@pxref{value Example, , @code{@@value} Example}).
<
16432,16433c16529,16544
< @node Sample Texinfo File
< @appendix A Sample Texinfo File
---
> @node Sample Texinfo Files
> @appendix Sample Texinfo Files
> @cindex Sample Texinfo files
>
> The first example is from the first chapter (@pxref{Short Sample}),
> given here in its entirety, without commentary. The second sample
> includes the full texts to be used in GNU manuals.
>
> @menu
> * Short Sample Texinfo File::
> * GNU Sample Texts::
> @end menu
>
>
> @node Short Sample Texinfo File
> @section Short Sample
16437,16438c16548,16549
< You can see this file, with comments, in the first chapter.
< @xref{Short Sample, , A Short Sample Texinfo File}.
---
> You can see this file, with comments, in the first chapter. @xref{Short
> Sample}.
16439a16551,16555
> In a nutshell: The @command{makeinfo} program transforms a Texinfo
> source file such as this into an Info file or HTML; and @TeX{} typesets
> it for a printed manual.
>
>
16445c16561
< @@settitle Sample Document
---
> @@settitle Sample Manual 1.0
16448c16564
< @@ifinfo
---
> @@copying
16452c16568
< @@end ifinfo
---
> @@end copying
16455d16570
< @@comment The title is printed in a large font.
16457,16458d16571
<
< @@c The following two commands start the copyright page.
16461c16574
< Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
---
> @@insertcopying
16470c16583
< This is the top node of a sample document.
---
> @@insertcopying
16475,16476c16588,16589
< only chapter in this sample.
< * Concept Index:: This index has two entries.
---
> only chapter in this sample.
> * Index:: Complete index.
16480c16593
< @@node First Chapter
---
> @@node First Chapter
16482d16594
< @@cindex Chapter, first
16484,16485c16596
< This is the contents of the first chapter.
< @@cindex Another sample index entry
---
> @@cindex chapter, first
16486a16598,16600
> This is the first chapter.
> @@cindex index entry, another
>
16497,16499d16610
< The @@code@{makeinfo@} command transforms a Texinfo source file
< such as this into an Info file or HTML; and @@TeX typesets it
< for a printed manual.
16500a16612,16613
> @@node Index
> @@unnumbered Index
16502,16503c16615
< @@node Concept Index
< @@unnumbered Concept Index
---
> @@printindex cp
16504a16617,16784
> @@bye
> @end example
>
>
> @node GNU Sample Texts
> @section GNU Sample Texts
>
> @cindex GNU sample texts
> @cindex Sample texts, GNU
> @cindex Full texts, GNU
>
> Here is a sample Texinfo document with the full texts that should be
> used in GNU manuals.
>
> As well as the legal texts, it also serves as a practical example of how
> many elements in a GNU system can affect the manual. If you're not
> familiar with all these different elements, don't worry. They're not
> required and a perfectly good manual can be written without them.
> They're included here nonetheless because many manuals do (or could)
> benefit from them.
>
> @xref{Short Sample}, for a minimal example of a Texinfo file.
> @xref{Beginning a File}, for a full explanation of that minimal
> example.
>
> Here are some notes on the example:
>
> @itemize @bullet
> @item
> @cindex $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ comment
> @cindex CVS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
> @cindex RCS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
> The @samp{$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $} comment is for CVS (@pxref{Top,, Overview, cvs,
> Concurrent Versions System}) or RCS (see rcsintro(1)) version control
> systems, which expand it into a string such as:
> @example
> $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
> @end example
> (This is useful in all sources that use version control, not just manuals.)
>
> @item
> @pindex automake@r{, and version info}
> The @file{version.texi} in the @code{@@include} command is maintained
> automatically by Automake (@pxref{Top,, Introduction, automake, GNU
> Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
> elsewhere. If your distribution doesn't use Automake, you can mimic
> these or equivalent settings.
>
> @item
> The @code{@@syncodeindex} command reflects the recommendation to use only
> one index if at all possible, to make it easier for readers.
>
> @item
> The @code{@@dircategory} is for constructing the Info directory.
> @xref{Installing Dir Entries}, which includes a variety of recommended
> category names.
>
> @item
> The `Invoking' node is a GNU standard to help users find the basic
> information about command-line usage of a given program. @xref{Manual
> Structure Details,,,standards, GNU Coding Standards}.
>
> @item
> It is best to include the entire GNU Free Documentation License in a GNU
> manual, unless the manual is only a few pages long. Of course this
> sample is even shorter than that, but it includes the FDL anyway in
> order to show one conventional way of doing so. The @file{fdl.texi}
> file is available on the GNU machines (and in the Texinfo and other GNU
> distributions).
>
> The FDL provides for omitting itself under certain conditions, but in
> that case the sample texts given here have to be modified. @xref{GNU
> Free Documentation License}.
>
> @item
> If your manual has invariant sections (again, see the license itself for
> details), then don't forget to include them.
> @end itemize
>
> Here is the sample document:
>
> @c We do the first part of this with @example instead of @verbatim
> @c because the literal @setfilename and @include confuse Automake. Argh.
> @example
> \input texinfo @@c -*-texinfo-*-
> @@comment $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
> @@comment %**start of header
> @@setfilename sample.info
> @@include version.texi
> @@settitle GNU Sample @@value@{VERSION@}
> @@syncodeindex pg cp
> @@comment %**end of header
> @@copying
> This manual is for GNU Sample
> (version @@value@{VERSION@}, @@value@{UPDATED@}),
> which is an example in the Texinfo documentation.
>
> Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
>
> @@quotation
> Permission is granted to copy, distribute and/or modify this document
> under the terms of the GNU Free Documentation License, Version 1.1 or
> any later version published by the Free Software Foundation; with no
> Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
> and with the Back-Cover Texts as in (a) below. A copy of the
> license is included in the section entitled ``GNU Free Documentation
> License.''
>
> (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
> this GNU Manual, like GNU software. Copies published by the Free
> Software Foundation raise funds for GNU development.''
> @@end quotation
> @@end copying
>
> @@dircategory Texinfo documentation system
> @@direntry
> * sample: (sample)Invoking sample.
> @@end direntry
>
> @@titlepage
> @@title GNU Sample
> @@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@}
> @@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@})
> @@page
> @@vskip 0pt plus 1filll
> @@insertcopying
> @@end titlepage
>
> @@contents
>
> @@ifnottex
> @@node Top
> @@top GNU Sample
>
> @@insertcopying
> @@end ifnottex
>
> @@menu
> * Invoking sample::
> * Copying This Manual::
> * Index::
> @@end menu
>
>
> @@node Invoking sample
> @@chapter Invoking sample
>
> @@pindex sample
> @@cindex invoking @@command@{sample@}
>
> This is a sample manual. There is no sample program to
> invoke, but if there was, you could see its basic usage
> and command line options here.
>
>
> @@node Copying This Manual
> @@appendix Copying This Manual
>
> @@menu
> * GNU Free Documentation License:: License for copying this manual.
> @@end menu
>
> @@include fdl.texi
>
>
> @@node Index
> @@unnumbered Index
>
16519c16799
< the indices of the output file.@refill
---
> the indices of the output file.
16735,16736c17015
< An included file, such as @file{foo.texinfo}, might look like
< this:@refill
---
> An included file, such as @file{foo.texinfo}, might look like this:
16990,16993c17269,17270
< after the @code{@@end titlepage} command. Enclose your specifications
< between @code{@@iftex} and @code{@@end iftex} commands since the
< @code{texinfo-format-buffer} command may not recognize them. Also,
< you must cancel the predefined heading commands with the
---
> after the @code{@@end titlepage} command.
> You must cancel the predefined heading commands with the
17004d17280
< @@iftex
17007d17282
< @@end iftex
17107d17381
< @@iftex
17111d17384
< @@end iftex
17129,17132c17402,17405
< Besides mistakes in the content of your documentation, there
< are two kinds of mistake you can make with Texinfo: you can make mistakes
< with @@-commands, and you can make mistakes with the structure of the
< nodes and chapters.@refill
---
> Besides mistakes in the content of your documentation, there are two
> kinds of mistake you can make with Texinfo: you can make mistakes with
> @@-commands, and you can make mistakes with the structure of the nodes
> and chapters.
18455,18456c18728,18729
< @node Documentation Copying
< @appendix GNU Free Documentation License
---
> @node Copying This Manual
> @appendix Copying This Manual
18458,18459c18731,18733
< @cindex FDL, GNU Free Documentation License
< @center Version 1.1, March 2000
---
> @menu
> * GNU Free Documentation License:: License for copying this manual.
> @end menu
18461,18463c18735
< @display
< Copyright @copyright{} 2000 Free Software Foundation, Inc.
< 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
---
> @include fdl.texi
18465,18467d18736
< Everyone is permitted to copy and distribute verbatim copies
< of this license document, but changing it is not allowed.
< @end display
18469,18853d18737
< @enumerate 0
< @item
< PREAMBLE
<
< The purpose of this License is to make a manual, textbook, or other
< written document @dfn{free} in the sense of freedom: to assure everyone
< the effective freedom to copy and redistribute it, with or without
< modifying it, either commercially or noncommercially. Secondarily,
< this License preserves for the author and publisher a way to get
< credit for their work, while not being considered responsible for
< modifications made by others.
<
< This License is a kind of ``copyleft'', which means that derivative
< works of the document must themselves be free in the same sense. It
< complements the GNU General Public License, which is a copyleft
< license designed for free software.
<
< We have designed this License in order to use it for manuals for free
< software, because free software needs free documentation: a free
< program should come with manuals providing the same freedoms that the
< software does. But this License is not limited to software manuals;
< it can be used for any textual work, regardless of subject matter or
< whether it is published as a printed book. We recommend this License
< principally for works whose purpose is instruction or reference.
<
< @item
< APPLICABILITY AND DEFINITIONS
<
< This License applies to any manual or other work that contains a
< notice placed by the copyright holder saying it can be distributed
< under the terms of this License. The ``Document'', below, refers to any
< such manual or work. Any member of the public is a licensee, and is
< addressed as ``you''.
<
< A ``Modified Version'' of the Document means any work containing the
< Document or a portion of it, either copied verbatim, or with
< modifications and/or translated into another language.
<
< A ``Secondary Section'' is a named appendix or a front-matter section of
< the Document that deals exclusively with the relationship of the
< publishers or authors of the Document to the Document's overall subject
< (or to related matters) and contains nothing that could fall directly
< within that overall subject. (For example, if the Document is in part a
< textbook of mathematics, a Secondary Section may not explain any
< mathematics.) The relationship could be a matter of historical
< connection with the subject or with related matters, or of legal,
< commercial, philosophical, ethical or political position regarding
< them.
<
< The ``Invariant Sections'' are certain Secondary Sections whose titles
< are designated, as being those of Invariant Sections, in the notice
< that says that the Document is released under this License.
<
< The ``Cover Texts'' are certain short passages of text that are listed,
< as Front-Cover Texts or Back-Cover Texts, in the notice that says that
< the Document is released under this License.
<
< A ``Transparent'' copy of the Document means a machine-readable copy,
< represented in a format whose specification is available to the
< general public, whose contents can be viewed and edited directly and
< straightforwardly with generic text editors or (for images composed of
< pixels) generic paint programs or (for drawings) some widely available
< drawing editor, and that is suitable for input to text formatters or
< for automatic translation to a variety of formats suitable for input
< to text formatters. A copy made in an otherwise Transparent file
< format whose markup has been designed to thwart or discourage
< subsequent modification by readers is not Transparent. A copy that is
< not ``Transparent'' is called ``Opaque''.
<
< Examples of suitable formats for Transparent copies include plain
< @sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
< @acronym{SGML} or @acronym{XML} using a publicly available
< @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
< for human modification. Opaque formats include PostScript,
< @acronym{PDF}, proprietary formats that can be read and edited only by
< proprietary word processors, @acronym{SGML} or @acronym{XML} for which
< the @acronym{DTD} and/or processing tools are not generally available,
< and the machine-generated @acronym{HTML} produced by some word
< processors for output purposes only.
<
< The ``Title Page'' means, for a printed book, the title page itself,
< plus such following pages as are needed to hold, legibly, the material
< this License requires to appear in the title page. For works in
< formats which do not have any title page as such, ``Title Page'' means
< the text near the most prominent appearance of the work's title,
< preceding the beginning of the body of the text.
<
< @item
< VERBATIM COPYING
<
< You may copy and distribute the Document in any medium, either
< commercially or noncommercially, provided that this License, the
< copyright notices, and the license notice saying this License applies
< to the Document are reproduced in all copies, and that you add no other
< conditions whatsoever to those of this License. You may not use
< technical measures to obstruct or control the reading or further
< copying of the copies you make or distribute. However, you may accept
< compensation in exchange for copies. If you distribute a large enough
< number of copies you must also follow the conditions in section 3.
<
< You may also lend copies, under the same conditions stated above, and
< you may publicly display copies.
<
< @item
< COPYING IN QUANTITY
<
< If you publish printed copies of the Document numbering more than 100,
< and the Document's license notice requires Cover Texts, you must enclose
< the copies in covers that carry, clearly and legibly, all these Cover
< Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
< the back cover. Both covers must also clearly and legibly identify
< you as the publisher of these copies. The front cover must present
< the full title with all words of the title equally prominent and
< visible. You may add other material on the covers in addition.
< Copying with changes limited to the covers, as long as they preserve
< the title of the Document and satisfy these conditions, can be treated
< as verbatim copying in other respects.
<
< If the required texts for either cover are too voluminous to fit
< legibly, you should put the first ones listed (as many as fit
< reasonably) on the actual cover, and continue the rest onto adjacent
< pages.
<
< If you publish or distribute Opaque copies of the Document numbering
< more than 100, you must either include a machine-readable Transparent
< copy along with each Opaque copy, or state in or with each Opaque copy
< a publicly-accessible computer-network location containing a complete
< Transparent copy of the Document, free of added material, which the
< general network-using public has access to download anonymously at no
< charge using public-standard network protocols. If you use the latter
< option, you must take reasonably prudent steps, when you begin
< distribution of Opaque copies in quantity, to ensure that this
< Transparent copy will remain thus accessible at the stated location
< until at least one year after the last time you distribute an Opaque
< copy (directly or through your agents or retailers) of that edition to
< the public.
<
< It is requested, but not required, that you contact the authors of the
< Document well before redistributing any large number of copies, to give
< them a chance to provide you with an updated version of the Document.
<
< @item
< MODIFICATIONS
<
< You may copy and distribute a Modified Version of the Document under
< the conditions of sections 2 and 3 above, provided that you release
< the Modified Version under precisely this License, with the Modified
< Version filling the role of the Document, thus licensing distribution
< and modification of the Modified Version to whoever possesses a copy
< of it. In addition, you must do these things in the Modified Version:
<
< @enumerate A
< @item
< Use in the Title Page (and on the covers, if any) a title distinct
< from that of the Document, and from those of previous versions
< (which should, if there were any, be listed in the History section
< of the Document). You may use the same title as a previous version
< if the original publisher of that version gives permission.
<
< @item
< List on the Title Page, as authors, one or more persons or entities
< responsible for authorship of the modifications in the Modified
< Version, together with at least five of the principal authors of the
< Document (all of its principal authors, if it has less than five).
<
< @item
< State on the Title page the name of the publisher of the
< Modified Version, as the publisher.
<
< @item
< Preserve all the copyright notices of the Document.
<
< @item
< Add an appropriate copyright notice for your modifications
< adjacent to the other copyright notices.
<
< @item
< Include, immediately after the copyright notices, a license notice
< giving the public permission to use the Modified Version under the
< terms of this License, in the form shown in the Addendum below.
<
< @item
< Preserve in that license notice the full lists of Invariant Sections
< and required Cover Texts given in the Document's license notice.
<
< @item
< Include an unaltered copy of this License.
<
< @item
< Preserve the section entitled ``History'', and its title, and add to
< it an item stating at least the title, year, new authors, and
< publisher of the Modified Version as given on the Title Page. If
< there is no section entitled ``History'' in the Document, create one
< stating the title, year, authors, and publisher of the Document as
< given on its Title Page, then add an item describing the Modified
< Version as stated in the previous sentence.
<
< @item
< Preserve the network location, if any, given in the Document for
< public access to a Transparent copy of the Document, and likewise
< the network locations given in the Document for previous versions
< it was based on. These may be placed in the ``History'' section.
< You may omit a network location for a work that was published at
< least four years before the Document itself, or if the original
< publisher of the version it refers to gives permission.
<
< @item
< In any section entitled ``Acknowledgments'' or ``Dedications'',
< preserve the section's title, and preserve in the section all the
< substance and tone of each of the contributor acknowledgments
< and/or dedications given therein.
<
< @item
< Preserve all the Invariant Sections of the Document,
< unaltered in their text and in their titles. Section numbers
< or the equivalent are not considered part of the section titles.
<
< @item
< Delete any section entitled ``Endorsements''. Such a section
< may not be included in the Modified Version.
<
< @item
< Do not retitle any existing section as ``Endorsements''
< or to conflict in title with any Invariant Section.
< @end enumerate
<
< If the Modified Version includes new front-matter sections or
< appendices that qualify as Secondary Sections and contain no material
< copied from the Document, you may at your option designate some or all
< of these sections as invariant. To do this, add their titles to the
< list of Invariant Sections in the Modified Version's license notice.
< These titles must be distinct from any other section titles.
<
< You may add a section entitled ``Endorsements'', provided it contains
< nothing but endorsements of your Modified Version by various
< parties---for example, statements of peer review or that the text has
< been approved by an organization as the authoritative definition of a
< standard.
<
< You may add a passage of up to five words as a Front-Cover Text, and a
< passage of up to 25 words as a Back-Cover Text, to the end of the list
< of Cover Texts in the Modified Version. Only one passage of
< Front-Cover Text and one of Back-Cover Text may be added by (or
< through arrangements made by) any one entity. If the Document already
< includes a cover text for the same cover, previously added by you or
< by arrangement made by the same entity you are acting on behalf of,
< you may not add another; but you may replace the old one, on explicit
< permission from the previous publisher that added the old one.
<
< The author(s) and publisher(s) of the Document do not by this License
< give permission to use their names for publicity for or to assert or
< imply endorsement of any Modified Version.
<
< @item
< COMBINING DOCUMENTS
<
< You may combine the Document with other documents released under this
< License, under the terms defined in section 4 above for modified
< versions, provided that you include in the combination all of the
< Invariant Sections of all of the original documents, unmodified, and
< list them all as Invariant Sections of your combined work in its
< license notice.
<
< The combined work need only contain one copy of this License, and
< multiple identical Invariant Sections may be replaced with a single
< copy. If there are multiple Invariant Sections with the same name but
< different contents, make the title of each such section unique by
< adding at the end of it, in parentheses, the name of the original
< author or publisher of that section if known, or else a unique number.
< Make the same adjustment to the section titles in the list of
< Invariant Sections in the license notice of the combined work.
<
< In the combination, you must combine any sections entitled ``History''
< in the various original documents, forming one section entitled
< ``History''; likewise combine any sections entitled ``Acknowledgments'',
< and any sections entitled ``Dedications''. You must delete all sections
< entitled ``Endorsements.''
<
< @item
< COLLECTIONS OF DOCUMENTS
<
< You may make a collection consisting of the Document and other documents
< released under this License, and replace the individual copies of this
< License in the various documents with a single copy that is included in
< the collection, provided that you follow the rules of this License for
< verbatim copying of each of the documents in all other respects.
<
< You may extract a single document from such a collection, and distribute
< it individually under this License, provided you insert a copy of this
< License into the extracted document, and follow this License in all
< other respects regarding verbatim copying of that document.
<
< @item
< AGGREGATION WITH INDEPENDENT WORKS
<
< A compilation of the Document or its derivatives with other separate
< and independent documents or works, in or on a volume of a storage or
< distribution medium, does not as a whole count as a Modified Version
< of the Document, provided no compilation copyright is claimed for the
< compilation. Such a compilation is called an ``aggregate'', and this
< License does not apply to the other self-contained works thus compiled
< with the Document, on account of their being thus compiled, if they
< are not themselves derivative works of the Document.
<
< If the Cover Text requirement of section 3 is applicable to these
< copies of the Document, then if the Document is less than one quarter
< of the entire aggregate, the Document's Cover Texts may be placed on
< covers that surround only the Document within the aggregate.
< Otherwise they must appear on covers around the whole aggregate.
<
< @item
< TRANSLATION
<
< Translation is considered a kind of modification, so you may
< distribute translations of the Document under the terms of section 4.
< Replacing Invariant Sections with translations requires special
< permission from their copyright holders, but you may include
< translations of some or all Invariant Sections in addition to the
< original versions of these Invariant Sections. You may include a
< translation of this License provided that you also include the
< original English version of this License. In case of a disagreement
< between the translation and the original English version of this
< License, the original English version will prevail.
<
< @item
< TERMINATION
<
< You may not copy, modify, sublicense, or distribute the Document except
< as expressly provided for under this License. Any other attempt to
< copy, modify, sublicense or distribute the Document is void, and will
< automatically terminate your rights under this License. However,
< parties who have received copies, or rights, from you under this
< License will not have their licenses terminated so long as such
< parties remain in full compliance.
<
< @item
< FUTURE REVISIONS OF THIS LICENSE
<
< The Free Software Foundation may publish new, revised versions
< of the GNU Free Documentation License from time to time. Such new
< versions will be similar in spirit to the present version, but may
< differ in detail to address new problems or concerns. See
< @uref{http://www.gnu.org/copyleft/}.
<
< Each version of the License is given a distinguishing version number.
< If the Document specifies that a particular numbered version of this
< License ``or any later version'' applies to it, you have the option of
< following the terms and conditions either of that specified version or
< of any later version that has been published (not as a draft) by the
< Free Software Foundation. If the Document does not specify a version
< number of this License, you may choose any version ever published (not
< as a draft) by the Free Software Foundation.
< @end enumerate
<
< @page
< @appendixsubsec ADDENDUM: How to use this License for your documents
<
< To use this License in a document you have written, include a copy of
< the License in the document and put the following copyright and
< license notices just after the title page:
<
< @smallexample
< @group
< Copyright (C) @var{year} @var{your name}.
< Permission is granted to copy, distribute and/or modify this document
< under the terms of the GNU Free Documentation License, Version 1.1
< or any later version published by the Free Software Foundation;
< with the Invariant Sections being @var{list their titles}, with the
< Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
< A copy of the license is included in the section entitled ``GNU
< Free Documentation License''.
< @end group
< @end smallexample
<
< If you have no Invariant Sections, write ``with no Invariant Sections''
< instead of saying which ones are invariant. If you have no
< Front-Cover Texts, write ``no Front-Cover Texts'' instead of
< ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
<
< If your document contains nontrivial examples of program code, we
< recommend releasing these examples in parallel under your choice of
< free software license, such as the GNU General Public License,
< to permit their use in free software.
<
<