[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[6571] some reorganization of introductory material in manual
|
From: |
Gavin D. Smith |
|
Subject: |
[6571] some reorganization of introductory material in manual |
|
Date: |
Tue, 25 Aug 2015 15:18:10 +0000 |
Revision: 6571
http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6571
Author: gavin
Date: 2015-08-25 15:18:09 +0000 (Tue, 25 Aug 2015)
Log Message:
-----------
some reorganization of introductory material in manual
Modified Paths:
--------------
trunk/ChangeLog
trunk/doc/texinfo.texi
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2015-08-25 14:53:32 UTC (rev 6570)
+++ trunk/ChangeLog 2015-08-25 15:18:09 UTC (rev 6571)
@@ -1,5 +1,29 @@
2015-08-25 Gavin Smith <address@hidden>
+ * doc/texinfo.texi (Nodes, Cross References): Move @anchor node
+ between chapters.
+ (Overview): Move Texinfo Document Structure node later, and
+ Adding Output Formats later, and History earlier.
+ (Adding Output Formats): Move material about man pages to the
+ end. Reword slightly.
+ (Output Formats) <Info>: Be slightly less detailed, because the
+ reader might not know what "nodes" are yet.
+ (Six Parts, Short Sample): Merge Six Parts into Short Sample.
+ <Header>: Mention that %**start of header is for the benefit of
+ Emacs, moved from Minimum.
+ (Minimum): Remove use of @emph and the word "good". Explain why
+ @bye is needed. Put discussion of which file extensions are
+ preferred in a footnote.
+
+ (Overview): Split off later sections into a new chapter, Writing
+ a Texinfo File.
+
+ (Chapter Structuring): Move chapter after Nodes and Menus.
+
+ * doc/texinfo.texi: Remove @shorttitlepage.
+
+2015-08-25 Gavin Smith <address@hidden>
+
* tp/Texinfo/Common.pm (%brace_commands): Add 'sortas'.
* tp/Texinfo/Convert/Plaintext.pm (%ignored_commands): Add
'sortas'.
Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi 2015-08-25 14:53:32 UTC (rev 6570)
+++ trunk/doc/texinfo.texi 2015-08-25 15:18:09 UTC (rev 6571)
@@ -80,8 +80,6 @@
@c setchapternewpage odd
address@hidden GNU Texinfo
-
@titlepage
@title Texinfo
@subtitle The GNU Documentation Format
@@ -132,10 +130,11 @@
@menu
* Copying Conditions:: Your rights.
* Overview:: Texinfo in brief.
+* Writing a Texinfo File:: Format of a Texinfo source file.
* Beginning and Ending a File:: Beginning and end of a Texinfo file.
-* Chapter Structuring:: Creating chapters, sections, appendices, etc.
* Nodes:: Writing nodes, the basic unit of Texinfo.
* Menus:: Writing menus.
+* Chapter Structuring:: Creating chapters, sections, appendices, etc.
* Cross References:: Writing cross references.
* Marking Text:: Marking words and phrases as code,
keyboard input, meta-syntactic
@@ -178,17 +177,19 @@
* Reporting Bugs:: Submitting effective bug reports.
* Output Formats:: Overview of the supported output formats.
-* Adding Output Formats:: Man pages and implementing new formats.
-* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
+* Adding Output Formats:: Man pages and implementing new formats.
+* History:: Acknowledgements, contributors and genesis.
+
+Writing a Texinfo File
+
* Command Syntax:: @@-commands are used for formatting.
* Conventions:: General rules for writing a Texinfo file.
* Comments:: Writing comments and ignored text in general.
* Minimum:: What a Texinfo file must have.
-* Six Parts:: Usually, a Texinfo file has six parts.
* Short Sample:: A short sample Texinfo file.
-* History:: Acknowledgements, contributors and genesis.
+* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
Beginning and Ending a Texinfo File
@@ -241,25 +242,9 @@
* @code{@@firstparagraphindent}:: Suppressing first paragraph
indentation.
* @code{@@exampleindent}:: Specify environment indentation.
-Chapter Structuring
-
-* Tree Structuring:: A manual is like an upside down tree @dots{}
-* Structuring Command Types:: How to divide a manual into parts.
-* @code{@@chapter}:: Chapter structuring.
-* @code{@@unnumbered @@appendix}::
-* @code{@@majorheading @@chapheading}::
-* @code{@@section}::
-* @code{@@unnumberedsec @@appendixsec @@heading}::
-* @code{@@subsection}::
-* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}::
-* @code{@@subsubsection}:: Commands for the lowest level sections.
-* @code{@@part}:: Collections of chapters.
-* Raise/lower sections:: How to change commands' hierarchical level.
-
Nodes
* @code{@@node}:: Creating nodes, in detail.
-* @code{@@anchor}:: Defining arbitrary cross reference
targets.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node
pointers.
@@ -280,6 +265,21 @@
* Less Cluttered Menu Entry:: Two part menu entry.
* Other Info Files:: How to refer to a different Info file.
+Chapter Structuring
+
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* @code{@@chapter}:: Chapter structuring.
+* @code{@@unnumbered @@appendix}::
+* @code{@@majorheading @@chapheading}::
+* @code{@@section}::
+* @code{@@unnumberedsec @@appendixsec @@heading}::
+* @code{@@subsection}::
+* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}::
+* @code{@@subsubsection}:: Commands for the lowest level sections.
+* @code{@@part}:: Collections of chapters.
+* Raise/lower sections:: How to change commands' hierarchical level.
+
Cross References
* References:: What cross references are for.
@@ -289,6 +289,7 @@
* Top Node Naming:: How to refer to the beginning of another file.
* @code{@@ref}:: A reference for the last part of a
sentence.
* @code{@@pxref}:: How to write a parenthetical cross
reference.
+* @code{@@anchor}:: Defining arbitrary cross-reference
targets
* @code{@@inforef}:: How to refer to an Info-only file.
* @code{@@url}:: How to refer to a uniform resource
locator.
* @code{@@cite}:: How to refer to books not in the Info
system.
@@ -826,16 +827,9 @@
@menu
* Reporting Bugs:: Submitting effective bug reports.
* Output Formats:: Overview of the supported output formats.
-* Adding Output Formats:: Man pages and implementing new formats.
-* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
* Info Files:: What is an Info file?
* Printed Books:: Characteristics of a printed book or manual.
-* Command Syntax:: @@-commands are used for formatting.
-* Conventions:: General rules for writing a Texinfo file.
-* Comments:: Writing comments and ignored text in general.
-* Minimum:: What a Texinfo file must have.
-* Six Parts:: Usually, a Texinfo file has six parts.
-* Short Sample:: A short sample Texinfo file.
+* Adding Output Formats:: Man pages and implementing new formats.
* History:: Acknowledgements, contributors and genesis.
@end menu
@@ -893,12 +887,11 @@
@cindex Info output, overview
(Generated via @command{makeinfo}.) Info format is mostly a plain
text transliteration of the Texinfo source. It adds a few control
-characters to separate nodes and provide navigational information for
-menus, cross references, indices, and so on. The Emacs Info subsystem
-(@pxref{Top,,, info, Info}), and the standalone @command{info} program
-(@pxref{Top,,, info-stnd, GNU Info}), among others, can read these
-files. @xref{Info Files}, and @ref{Creating and Installing Info
-Files}.
+characters to provide navigational information for cross-references,
+indices, and so on. The Emacs Info subsystem (@pxref{Top,,, info,
+Info}), and the standalone @command{info} program (@pxref{Top,,,
+info-stnd, GNU Info}), among others, can read these files. @xref{Info
+Files}, and @ref{Creating and Installing Info Files}.
@item Plain text
@cindex Plain text output, overview
@@ -996,118 +989,6 @@
@end table
address@hidden Adding Output Formats
address@hidden Adding Output Formats
address@hidden Additional output formats
-
-The output formats in the previous section handle a wide variety of
-usage, but of course there is always room for more.
-
address@hidden Man page output, not supported
-From time to time, proposals are made to generate traditional Unix man
-pages from Texinfo source. However, because man pages have a strict
-conventional format, creating a good man page requires a completely
-different source than the typical Texinfo applications of writing a
-good user tutorial and/or a good reference manual. This makes
-generating man pages incompatible with the Texinfo design goal of not
-having to document the same information in different ways for
-different output formats. You might as well write the man page
-directly.
-
address@hidden help2man
address@hidden O'Dea, Brendan
-As an alternative way to support man pages, you may find the program
address@hidden to be useful. It generates a traditional man page
-from the @samp{--help} output of a program. In fact, the man pages
-for the programs in the Texinfo distribution are generated with this.
-It is GNU software written by Brendan O'Dea, available from
address@hidden://www.gnu.org/software/help2man}.
-
address@hidden Output formats, supporting more
address@hidden SGML-tools output format
-If you are a programmer and would like to contribute to the GNU
-project by implementing additional output formats for Texinfo, that
-would be excellent. The way to do this that would be most useful is
-to write a new back-end for @command{texi2any}, our reference
-implementation of a Texinfo parser; it creates a tree representation
-of the Texinfo input that you can use for the conversion. The
-documentation in the source file
address@hidden/Texinfo/Convert/Converter.pm} is a good place to start.
address@hidden Translator @command{texi2any}}.
-
-Another viable approach is use the Texinfo XML output from
address@hidden as your input. This XML is an essentially complete
-representation of the input, but without the Texinfo syntax and option
-peculiarities, as described above.
-
address@hidden Texinfo parsers, discouraging more
-If you still cannot resist the temptation of writing a new program
-that reads Texinfo source directly, let us give some more caveats:
-please do not underestimate the amount of work required. Texinfo is
-by no means a simple language to parse correctly, and remains under
-development, so you would be committing to an ongoing task. At a
-minimum, please check that the extensive tests of the language that
-come with @command{texi2any} give correct results with your new
-program.
-
-
address@hidden Texinfo Document Structure
address@hidden Texinfo Document Structure
address@hidden Texinfo document structure
address@hidden Document structure, of Texinfo
address@hidden Structure, of Texinfo documents
address@hidden Double structure, of Texinfo documents
-
address@hidden address@hidden node name
-Texinfo documents most usefully have a double structure, reflecting
-the double purposes of printed and online output. For printed output
-(DVI, PDF, @dots{}), with physical pages, there are chapters,
-sections, subsections, etc. For online output (Info, HTML, @dots{}),
-with interactive navigation and no physical pages, there are so-called
-``nodes''.
-
-Typically, the sectioning structure and the node structure are
-completely parallel, with one node for each chapter, section, etc.,
-and with the nodes following the same hierarchical arrangement as the
-sectioning. Thus, if a node is at the logical level of a chapter, its
-child nodes are at the level of sections; similarly, the child nodes
-of sections are at the level of subsections.
-
-Each @dfn{node} has a name, and contains the discussion of one topic.
-Along with the text for the user to read, each node also has pointers
-to other nodes, identified in turn by their own names. Info readers
-display one node at a time, and provide commands for the user to move
-to related nodes. The HTML output can be similarly navigated.
-
-The names of child nodes are listed in a @dfn{menu} within the parent
-node; for example, a node corresponding to a chapter would have a menu
-of the sections in that chapter. The menus allow the user to move to
-the child nodes in a natural way in the online output.
-
-In addition, nodes at the same level are formed into a chain with
-`Next' and `Previous' pointers. As you might imagine, the `Next'
-pointer links to the next node (section), and the `Previous' pointer
-links to the previous node (section). Thus, for example, all the
-nodes that are at the level of sections within a chapter are linked
-together, and the order in this chain is the same as the order of the
-children in the menu of parent chapter. Each child node records the
-parent node name as its `Up' pointer. The last child has no `Next'
-pointer, and the first child has the parent both as its `Previous' and
-as its `Up' pointer.
-
-In addition to menus and `Next', `Previous', and `Up' pointers,
-Texinfo provides pointers of another kind for cross references, that
-can be sprinkled throughout the text. This is usually the best way to
-represent links that do not fit a hierarchical structure.
-
-Although it is technically possible to create Texinfo documents with
-only one structure or the other, or for the two structures not to be
-parallel, or for either the sectioning or node structure to be
-abnormally formed, etc., this is @emph{not at all recommended}. To
-the best of our knowledge, all the Texinfo manuals currently in
-general use do follow the conventional parallel structure.
-
-
@node Info Files
@section Info Files
@cindex Info files
@@ -1203,6 +1084,194 @@
not part of the Texinfo distribution.
address@hidden Adding Output Formats
address@hidden Adding Output Formats
address@hidden Additional output formats
+
+The output formats in the previous sections handle a wide variety of
+usage, but of course there is always room for more.
+
address@hidden Output formats, supporting more
address@hidden SGML-tools output format
+If you are a programmer and would like to contribute to the GNU
+project by implementing additional output formats for Texinfo, that
+would be excellent. The way to do this that would be most useful is
+to write a new back-end for @command{texi2any}, our reference
+implementation of a Texinfo parser; it creates a tree representation
+of the Texinfo input that you can use for the conversion. The
+documentation in the source file
address@hidden/Texinfo/Convert/Converter.pm} is a good place to start.
address@hidden Translator @command{texi2any}}.
+
+Another viable approach is use the Texinfo XML output from
address@hidden as your input. This XML is an essentially complete
+representation of the input, but without the Texinfo syntax and option
+peculiarities, as described above.
+
address@hidden Texinfo parsers, discouraging more
+If you still cannot resist the temptation of writing a new program
+that reads Texinfo source directly, let us give some more caveats:
+please do not underestimate the amount of work required. Texinfo is
+by no means a simple language to parse correctly, and remains under
+development, so you would be committing to an ongoing task. You
+are advised to check that the tests of the language that come with
address@hidden give correct results with your new program.
+
address@hidden Man page output, not supported
+From time to time, proposals are made to generate traditional Unix man
+pages from Texinfo source. However, because man pages have a strict
+conventional format, creating a good man page requires a completely
+different source from that needed for the typical Texinfo applications
+of writing a good user tutorial and/or a good reference manual. This
+makes generating man pages incompatible with the Texinfo design
+goal of not having to document the same information in different
+ways for different output formats. You might as well write the man
+page directly.
+
address@hidden help2man
address@hidden O'Dea, Brendan
+As an alternative way to support man pages, you may find the program
address@hidden to be useful. It generates a traditional man page
+from the @samp{--help} output of a program. In fact, the man pages
+for the programs in the Texinfo distribution are generated with this.
+It is GNU software written by Brendan O'Dea, available from
address@hidden://www.gnu.org/software/help2man}.
+
+
+
address@hidden History
address@hidden History
+
address@hidden Stallman, Richard M.
address@hidden Chassell, Robert J.
address@hidden Fox, Brian
address@hidden Berry, Karl
+Richard M. Stallman invented the Texinfo format, wrote the initial
+processors, and created Edition 1.0 of this manual. address@hidden
+Chassell greatly revised and extended the manual, starting with
+Edition 1.1. Brian Fox was responsible for the standalone Texinfo
+distribution until version 3.8, and originally wrote the standalone
address@hidden and @command{info} programs. Karl Berry has
+continued maintenance since Texinfo 3.8 (manual edition 2.22).
+
address@hidden Pinard, Fran@,{c}ois
address@hidden Schwab, Andreas
address@hidden Weinberg, Zack
address@hidden Weisshaus, Melissa
address@hidden Zaretskii, Eli
address@hidden Zuhn, David D.
+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 address@hidden Zuhn,
+tirelessly recorded and reported mistakes and obscurities. Zack
+Weinberg did the impossible by implementing the macro syntax in
address@hidden Thanks 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
address@hidden file. Our mistakes are our own.
+
address@hidden History of Texinfo
address@hidden Texinfo history
address@hidden Beginnings
+
address@hidden Scribe
address@hidden Reid, Brian
+In the 1970's at CMU, Brian Reid developed a program and format named
+Scribe to mark up documents for printing. It used the @code{@@}
+character to introduce commands, as Texinfo does. Much more
+consequentially, it strove to describe document contents rather than
+formatting, an idea wholeheartedly adopted by Texinfo.
+
address@hidden Bolio
address@hidden address@hidden
+Meanwhile, people at MIT developed another, not too dissimilar format
+called Bolio. This then was converted to using @TeX{} as its typesetting
+language: address@hidden The earliest address@hidden version seems to have
been
+0.02 on October 31, 1984.
+
address@hidden could only be used as a markup language for documents to be
+printed, not for online documents. Richard Stallman (RMS) worked on
+both Bolio and address@hidden He also developed a nifty on-line help format
+called Info, and then combined address@hidden and Info to create Texinfo, a
+mark up language for text that is intended to be read both online and
+as printed hard copy.
+
+Moving forward, the original translator to create Info was written
+(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the
address@hidden and other functions. In the early 1990s,
+Brian Fox reimplemented the conversion program in C, now called
address@hidden
+
address@hidden Reimplementing in Perl
+
address@hidden Cons, Lionel
address@hidden Dumas, Patrice
+In 2012, the C @command{makeinfo} was itself replaced by a Perl
+implementation generically called @command{texi2any}. This version
+supports the same level of output customization as
address@hidden, an independent program originally written by
+Lionel Cons, later with substantial work by many others. The many
+additional features needed to make @command{texi2html} a replacement
+for @command{makeinfo} were implemented by Patrice Dumas. The first
+never-released version of @command{texi2any} was based on the
address@hidden code. That implementation, however, was abandoned
+in favor of the current program, which parses the Texinfo input into a
+tree for processing. It still supports nearly all the features of
address@hidden
+
+The new Perl program is much slower than the old C program. We hope
+the speed gap will close in the future, but it may not ever be
+entirely comparable. So why did we switch? In short, we intend and
+hope that the present program will be much easier than the previous C
+implementation of @command{makeinfo} to extend to different output
+styles, back-end output formats, and all other customizations.
+In more detail:
+
address@hidden @bullet
address@hidden HTML customization. Many GNU and other free software packages
+had been happily using the HTML customization features in
address@hidden for years. Thus, in effect two independent
+implementations of the Texinfo language had developed, and keeping
+them in sync was not simple. Adding the HTML customization possible
+in @command{texi2html} to a C program would have been an
+enormous effort.
+
address@hidden Unicode, and multilingual support generally, especially of east
+Asian languages. Although of course it's perfectly plausible to write
+such support in C, in the particular case of @command{makeinfo}, it
+would have been tantamount to rewriting the entire program. In Perl,
+much of that comes essentially for free.
+
address@hidden Additional back-ends. The @command{makeinfo} code had become
+convoluted to the point where adding a new back-end was quite complex,
+requiring complex interactions with existing back-ends. In contrast,
+our Perl implementation provides a clean tree-based representation for
+all back-ends to work from. People have requested numerous different
+back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now
+be much more feasible to implement. Which leads to the last item:
+
address@hidden Making contributions easier. In general, due to the cleaner
+structure, the Perl program should be considerably easier than the C
+for anyone to read and contribute to, with the resulting obvious
+benefits.
address@hidden itemize
+
address@hidden Implementation}, for more on the rationale for and
+role of @command{texi2any}.
+
+
address@hidden Writing a Texinfo File
address@hidden Writing a Texinfo File
+
address@hidden
+* Command Syntax:: @@-commands are used for formatting.
+* Conventions:: General rules for writing a Texinfo file.
+* Comments:: Writing comments and ignored text in general.
+* Minimum:: What a Texinfo file must have.
+* Short Sample:: A short sample Texinfo file.
+* Texinfo Document Structure:: How Texinfo manuals are usually arranged.
address@hidden menu
+
@node Command Syntax
@section @@-Command Syntax
@anchor{Formatting Commands} @c old name
@@ -1452,15 +1521,15 @@
@cindex Required in Texinfo file
@cindex Texinfo file minimum
-By convention, the name of a Texinfo file ends with (in order of
-preference) one of the extensions @file{.texinfo}, @file{.texi},
address@hidden, 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.
+By convention, the name of a Texinfo file ends with one of the
+extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or
address@hidden@footnote{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.}
-In order to be made into a good printed manual and other output
-formats, a Texinfo file @emph{must} begin with lines like this:
+In order to be made into a printed manual and other output
+formats, a Texinfo file must begin with lines like this:
@example
@group
@@ -1472,7 +1541,7 @@
@noindent
The contents of the file follow this beginning, and then you
address@hidden end the Texinfo source with a line like this:
+must end the Texinfo source with a line like this:
@example
@@bye
@@ -1503,84 +1572,23 @@
@item
The @code{@@bye} line at the end of the file on a line of its own tells
-the formatters that the file is ended and to stop formatting.
+the formatters that the file is ended and to stop formatting. If you
+leave this out, you'll be dumped at @TeX{}'s prompt at the end of the
+run.
@end itemize
-If you use Emacs, it is also useful to include mode setting and
-start-of-header and end-of-header lines at the beginning of a Texinfo
-file, like this:
-
address@hidden
address@hidden
-\input texinfo @@c -*-texinfo-*-
-@@c %**start of header
-@@setfilename @var{info-file-name}
-@@settitle @var{name-of-manual}
-@@c %**end of header
address@hidden group
address@hidden example
-
address@hidden
-In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
-Texinfo mode when you edit the file.
-
-The @code{@@c ...header} lines above which surround the
address@hidden@@setfilename} and @code{@@settitle} lines allow you to process,
-within Emacs, just part of the Texinfo source. (@xref{Start of
-Header}.)
-
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.
address@hidden Six Parts
address@hidden Six Parts of a Texinfo File
-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.
-
address@hidden @r
address@hidden 1. Header
-The @dfn{Header} names the file, tells @TeX{} which definitions file to
-use, and other such housekeeping tasks.
-
address@hidden 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.
-
address@hidden 3. Title and Copyright
-The @dfn{Title and Copyright} segment contains the title and copyright
-pages for the printed manual. The segment must be enclosed between
address@hidden@@titlepage} and @code{@@end titlepage} commands. The title and
-copyright page appear only in the printed manual.
-
address@hidden 4. `Top' Node and Master Menu
-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.
-
address@hidden 5. Body
-The @dfn{Body} of the document is typically structured like a
-traditional book or encyclopedia, but it may be free form.
-
address@hidden 6. End
-The @dfn{End} segment may contain commands for printing indices, and
-closes with the @code{@@bye} command on a line of its own.
address@hidden table
-
-
@node Short Sample
@section A Short Sample Texinfo File
@cindex Sample Texinfo file, with comments
-Here is a short but complete Texinfo file consisting of the
-parts enumerated in the previous section, so you can see how Texinfo
+Here is a short but complete Texinfo file, so you can see how Texinfo
source appears in practice. The first three parts of the file are
mostly boilerplate: when writing a manual, you simply change
the names as appropriate.
@@ -1589,16 +1597,14 @@
@ref{Short Sample Texinfo File}.
@xref{Beginning and Ending a File}, for more documentation on the
-commands listed here. @xref{GNU Sample Texts}, for the full texts to be
-used in GNU manuals.
+commands listed here.
address@hidden Part 1: Header
address@hidden Header
@noindent
-The header does not appear in either the Info file or the
-printed output. It sets various parameters, including the
-name of the Info file and the title used in the header.
+The header tells @TeX{} which definitions file to
+use, names the file, and carries out other such housekeeping tasks.
@example
@group
@@ -1610,8 +1616,21 @@
@end group
@end example
address@hidden Part 2: Summary Description and Copyright
+If you use Emacs, it is also useful to include mode setting and
+start-of-header and end-of-header lines at the beginning of a Texinfo
+file. In the first line, @samp{-*-texinfo-*-} causes Emacs to switch
+into Texinfo mode when you edit the file.
+The @code{@@c ...header} lines above which surround the
address@hidden@@setfilename} and @code{@@settitle} lines allow you to process,
+within Emacs, just part of the Texinfo source. (@xref{Start of
+Header}.)
+
address@hidden Summary Description and Copyright
+
+This segment describes the document and contains the copyright notice
+and copying permissions. This is done with the @code{@@copying} command.
+
@noindent
A real manual includes more text here, according to the license under
which it is distributed. @xref{GNU Sample Texts}.
@@ -1626,11 +1645,15 @@
@end group
@end example
address@hidden Part 3: Titlepage, Contents, Copyright
address@hidden Titlepage, Contents, Copyright
+The title and copyright segment contains the title and copyright
+pages for the printed manual. The segment must be enclosed between
address@hidden@@titlepage} and @code{@@end titlepage} commands. The title and
+copyright page does not appear in the online output.
+
@noindent
-The titlepage segment does not appear in the online output, only in the
-printed manual. We use the @code{@@insertcopying} command to
+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.
@@ -1653,17 +1676,19 @@
@@contents
@end example
address@hidden Part 4: `Top' Node and Master Menu
address@hidden `Top' Node and Master Menu
address@hidden
-The `Top' node contains the master menu for the Info file. Since the
-printed manual uses a table of contents rather than a menu, it
-excludes the `Top' node. We repeat the short description from the
-beginning of the @samp{@@copying} text, but there's no need to repeat
-the copyright information, so we don't use @samp{@@insertcopying} here.
-The @samp{@@top} command itself helps @command{makeinfo} determine the
-relationships between nodes.
+The `Top' node starts off the online output; it does not appear in the
+printed manual. We repeat the short description from the beginning of
+the @samp{@@copying} text, but there's no need to repeat the copyright
+information, so we don't use @samp{@@insertcopying} here.
+The @samp{@@top} command itself helps @command{makeinfo} determine
+the relationships between nodes. The `Top' node contains at least a
+top-level @dfn{menu} listing the chapters, and possibly a @dfn{Master
+Menu} listing all the nodes in the entire document.
+
+
@example
@@ifnottex
@@node Top
@@ -1682,7 +1707,7 @@
@end example
address@hidden Part 5: The Body of the Document
address@hidden The Body of the Document
@noindent
The body segment contains all the text of the document, but not the
@@ -1716,12 +1741,10 @@
@end example
address@hidden Part 6: The End of the Document
address@hidden The End of the Document
address@hidden
-The end segment contains commands for generating an index in a node and
-unnumbered chapter of its own, and the @code{@@bye} command that marks
-the end of the document.
+This may contain commands for printing indices, and
+closes with the @code{@@bye} command, which marks the end of the document.
@example
@group
@@ -1758,127 +1781,62 @@
@end quotation
address@hidden History
address@hidden History
address@hidden Texinfo Document Structure
address@hidden Texinfo Document Structure
address@hidden Texinfo document structure
address@hidden Document structure, of Texinfo
address@hidden Structure, of Texinfo documents
address@hidden Double structure, of Texinfo documents
address@hidden Stallman, Richard M.
address@hidden Chassell, Robert J.
address@hidden Fox, Brian
address@hidden Berry, Karl
-Richard M. Stallman invented the Texinfo format, wrote the initial
-processors, and created Edition 1.0 of this manual. address@hidden
-Chassell greatly revised and extended the manual, starting with
-Edition 1.1. Brian Fox was responsible for the standalone Texinfo
-distribution until version 3.8, and originally wrote the standalone
address@hidden and @command{info} programs. Karl Berry has
-continued maintenance since Texinfo 3.8 (manual edition 2.22).
address@hidden address@hidden node name
+Texinfo documents most usefully have a double structure, reflecting
+the double purposes of printed and online output. For printed output
+(DVI, PDF, @dots{}), with physical pages, there are chapters,
+sections, subsections, etc. For online output (Info, HTML, @dots{}),
+with interactive navigation and no physical pages, there are so-called
+``nodes''.
address@hidden Pinard, Fran@,{c}ois
address@hidden Schwab, Andreas
address@hidden Weinberg, Zack
address@hidden Weisshaus, Melissa
address@hidden Zaretskii, Eli
address@hidden Zuhn, David D.
-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 address@hidden Zuhn,
-tirelessly recorded and reported mistakes and obscurities. Zack
-Weinberg did the impossible by implementing the macro syntax in
address@hidden Thanks 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
address@hidden file. Our mistakes are our own.
+Typically, the sectioning structure and the node structure are
+completely parallel, with one node for each chapter, section, etc.,
+and with the nodes following the same hierarchical arrangement as the
+sectioning. Thus, if a node is at the logical level of a chapter, its
+child nodes are at the level of sections; similarly, the child nodes
+of sections are at the level of subsections.
address@hidden History of Texinfo
address@hidden Texinfo history
address@hidden Beginnings
+Each @dfn{node} has a name, and contains the discussion of one topic.
+Along with the text for the user to read, each node also has pointers
+to other nodes, identified in turn by their own names. Info readers
+display one node at a time, and provide commands for the user to move
+to related nodes. The HTML output can be similarly navigated.
address@hidden Scribe
address@hidden Reid, Brian
-In the 1970's at CMU, Brian Reid developed a program and format named
-Scribe to mark up documents for printing. It used the @code{@@}
-character to introduce commands, as Texinfo does. Much more
-consequentially, it strove to describe document contents rather than
-formatting, an idea wholeheartedly adopted by Texinfo.
+The names of child nodes are listed in a @dfn{menu} within the parent
+node; for example, a node corresponding to a chapter would have a menu
+of the sections in that chapter. The menus allow the user to move to
+the child nodes in a natural way in the online output.
address@hidden Bolio
address@hidden address@hidden
-Meanwhile, people at MIT developed another, not too dissimilar format
-called Bolio. This then was converted to using @TeX{} as its typesetting
-language: address@hidden The earliest address@hidden version seems to have
been
-0.02 on October 31, 1984.
+In addition, nodes at the same level are formed into a chain with
+`Next' and `Previous' pointers. As you might imagine, the `Next'
+pointer links to the next node (section), and the `Previous' pointer
+links to the previous node (section). Thus, for example, all the
+nodes that are at the level of sections within a chapter are linked
+together, and the order in this chain is the same as the order of the
+children in the menu of parent chapter. Each child node records the
+parent node name as its `Up' pointer. The last child has no `Next'
+pointer, and the first child has the parent both as its `Previous' and
+as its `Up' pointer.
address@hidden could only be used as a markup language for documents to be
-printed, not for online documents. Richard Stallman (RMS) worked on
-both Bolio and address@hidden He also developed a nifty on-line help format
-called Info, and then combined address@hidden and Info to create Texinfo, a
-mark up language for text that is intended to be read both online and
-as printed hard copy.
+In addition to menus and `Next', `Previous', and `Up' pointers,
+Texinfo provides pointers of another kind for cross references, that
+can be sprinkled throughout the text. This is usually the best way to
+represent links that do not fit a hierarchical structure.
-Moving forward, the original translator to create Info was written
-(primarily by RMS and Bob Chassell) in Emacs Lisp, namely the
address@hidden and other functions. In the early 1990s,
-Brian Fox reimplemented the conversion program in C, now called
address@hidden
+Although it is technically possible to create Texinfo documents with
+only one structure or the other, or for the two structures not to be
+parallel, or for either the sectioning or node structure to be
+abnormally formed, etc., this is @emph{not at all recommended}. To
+the best of our knowledge, all the Texinfo manuals currently in
+general use do follow the conventional parallel structure.
address@hidden Reimplementing in Perl
-
address@hidden Cons, Lionel
address@hidden Dumas, Patrice
-In 2012, the C @command{makeinfo} was itself replaced by a Perl
-implementation generically called @command{texi2any}. This version
-supports the same level of output customization as
address@hidden, an independent program originally written by
-Lionel Cons, later with substantial work by many others. The many
-additional features needed to make @command{texi2html} a replacement
-for @command{makeinfo} were implemented by Patrice Dumas. The first
-never-released version of @command{texi2any} was based on the
address@hidden code. That implementation, however, was abandoned
-in favor of the current program, which parses the Texinfo input into a
-tree for processing. It still supports nearly all the features of
address@hidden
-
-The new Perl program is much slower than the old C program. We hope
-the speed gap will close in the future, but it may not ever be
-entirely comparable. So why did we switch? In short, we intend and
-hope that the present program will be much easier than the previous C
-implementation of @command{makeinfo} to extend to different output
-styles, back-end output formats, and all other customizations.
-In more detail:
-
address@hidden @bullet
address@hidden HTML customization. Many GNU and other free software packages
-had been happily using the HTML customization features in
address@hidden for years. Thus, in effect two independent
-implementations of the Texinfo language had developed, and keeping
-them in sync was not simple. Adding the HTML customization possible
-in @command{texi2html} to a C program would have been an
-enormous effort.
-
address@hidden Unicode, and multilingual support generally, especially of east
-Asian languages. Although of course it's perfectly plausible to write
-such support in C, in the particular case of @command{makeinfo}, it
-would have been tantamount to rewriting the entire program. In Perl,
-much of that comes essentially for free.
-
address@hidden Additional back-ends. The @command{makeinfo} code had become
-convoluted to the point where adding a new back-end was quite complex,
-requiring complex interactions with existing back-ends. In contrast,
-our Perl implementation provides a clean tree-based representation for
-all back-ends to work from. People have requested numerous different
-back-ends (@LaTeX{}, the latest (X)HTML, @dots{}), and they will now
-be much more feasible to implement. Which leads to the last item:
-
address@hidden Making contributions easier. In general, due to the cleaner
-structure, the Perl program should be considerably easier than the C
-for anyone to read and contribute to, with the resulting obvious
-benefits.
address@hidden itemize
-
address@hidden Implementation}, for more on the rationale for and
-role of @command{texi2any}.
-
-
@node Beginning and Ending a File
@anchor{Beginning a File} @c old name
@chapter Beginning and Ending a Texinfo File
@@ -1887,7 +1845,7 @@
@cindex File beginning
This chapter expands on the minimal complete Texinfo source file
-previously given (@pxref{Six Parts}).
+previously given (@pxref{Short Sample}).
Certain pieces of information must be provided at the beginning of a
Texinfo file, such as the name for the output file(s), the title of the
@@ -3311,592 +3269,6 @@
(@pxref{Compile-Command,, Using the Local Variables List}).
address@hidden Chapter Structuring
address@hidden Chapter Structuring
address@hidden@c old name
address@hidden Chapter structuring
address@hidden Structuring of chapters
address@hidden Sectioning
-
-Texinfo's @dfn{chapter structuring} commands divide a document into a
-hierarchy of chapters, sections, subsections, and subsubsections. These
-commands generate large headings in the text, like the one above. They
-also provide information for generating the table of contents
-(@pxref{Contents,, Generating a Table of Contents}), and for implicitly
-determining node pointers, as is recommended (@address@hidden
-Pointer Creation}).
-
-The chapter structuring commands do not create a node structure, so
-normally you put a @code{@@node} command immediately before each
-chapter structuring command (@pxref{Nodes}). The only time you are
-likely to use the chapter structuring commands without also using
-nodes is if you are writing a document that contains no cross
-references and will only be printed, not transformed into Info, HTML,
-or other formats.
-
address@hidden
-* Tree Structuring:: A manual is like an upside down tree @dots{}
-* Structuring Command Types:: How to divide a manual into parts.
-* @code{@@chapter}:: Chapter structuring.
-* @code{@@unnumbered @@appendix}::
-* @code{@@majorheading @@chapheading}::
-* @code{@@section}::
-* @code{@@unnumberedsec @@appendixsec @@heading}::
-* @code{@@subsection}::
-* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}::
-* @code{@@subsubsection}:: Commands for the lowest level sections.
-* @code{@@part}:: Collections of chapters.
-* Raise/lower sections:: How to change commands' hierarchical level.
address@hidden menu
-
-
address@hidden Tree Structuring
address@hidden Tree Structure of Sections
address@hidden Tree structuring
-
-A Texinfo file is usually structured like a book with chapters,
-sections, subsections, and the like. This structure can be visualized
-as a tree (or rather as an upside-down tree) with the root at the top
-and the levels corresponding to chapters, sections, subsection, and
-subsubsections.
-
-Here is a diagram that shows a Texinfo file with three chapters, each
-with two sections.
-
address@hidden
address@hidden
- Top
- |
- -------------------------------------
- | | |
- Chapter 1 Chapter 2 Chapter 3
- | | |
- -------- -------- --------
- | | | | | |
-Section Section Section Section Section Section
- 1.1 1.2 2.1 2.2 3.1 3.2
-
address@hidden group
address@hidden example
-
-In a Texinfo file that has this structure, the beginning of Chapter 2
-would be written like this:
-
address@hidden
address@hidden
-@@node Chapter 2
-@@chapter Chapter 2
address@hidden group
address@hidden example
-
address@hidden
-For purposes of example, here is how it would be written with
-explicit node pointers:
-
address@hidden
address@hidden
-@@node Chapter 2, Chapter 3, Chapter 1, Top
-@@chapter Chapter 2
address@hidden group
address@hidden example
-
-The chapter structuring commands are described in the sections that
-follow; the @code{@@node} command is described in
-the following chapter (@pxref{Nodes}).
-
-
address@hidden Structuring Command Types
address@hidden Structuring Command Types
-
-The chapter structuring commands fall into four groups or series, each
-of which contains structuring commands corresponding to the
-hierarchical levels of chapters, sections, subsections, and
-subsubsections.
-
-The four groups of commands are the @code{@@chapter} series, the
address@hidden@@unnumbered} series, the @code{@@appendix} series, and the
address@hidden@@heading} series. Each command produces a title with a
-different appearance in the body of the document. Some of the
-commands list their titles in the tables of contents, while others do
-not. Here are the details:
-
address@hidden @bullet
address@hidden
-The @code{@@chapter} and @code{@@appendix} series of commands produce
-numbered or lettered entries both in the body of a document and in its
-table of contents.
-
address@hidden
-The @code{@@unnumbered} series of commands produce unnumbered entries
-both in the body of a document and in its table of contents. The
address@hidden@@top} command, which has a special use, is a member of this
-series (@address@hidden@@top} Command}). An @code{@@unnumbered} section
-is a normal part of the document structure.
-
address@hidden
-The @code{@@heading} series of commands produce simple unnumbered
-headings that do not appear in a table of contents, are not associated
-with nodes, and cannot be cross-referenced. These heading commands
-never start a new page.
address@hidden itemize
-
-When a @code{@@setchapternewpage} command says to do so, the
address@hidden@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
-start new pages in the printed manual; the @code{@@heading} commands
-do not. @address@hidden@@setchapternewpage}}.
-
-Here is a summary:
-
address@hidden
-{\globaldefs=1 \smallfonts \rm}
address@hidden tex
-
address@hidden @columnfractions .19 .30 .29 .22
address@hidden @tab @tab
@tab No new page
address@hidden @i{Numbered} @tab @i{Unnumbered} @tab
@i{Lettered/numbered} @tab @i{Unnumbered}
address@hidden In contents @tab In contents @tab In
contents @tab Not in contents
address@hidden @tab @code{@@top} @tab
@tab @code{@@majorheading}
address@hidden @code{@@chapter} @tab @code{@@unnumbered} @tab
@code{@@appendix} @tab @code{@@chapheading}
address@hidden @code{@@section} @tab @code{@@unnumberedsec} @tab
@code{@@appendixsec} @tab @code{@@heading}
address@hidden @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab
@code{@@appendixsubsec} @tab @code{@@subheading}
address@hidden @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab
@code{@@appendixsubsubsec} @tab @code{@@subsubheading}
address@hidden multitable
address@hidden
-{\globaldefs=1 \textfonts \rm}
address@hidden tex
-
-
address@hidden @code{@@chapter}
address@hidden @code{@@chapter}: Chapter Structuring
-
address@hidden@c old name
address@hidden chapter
-
address@hidden@@chapter} identifies a chapter in the document--the highest
-level of the normal document structuring hierarchy. Write the command
-at the beginning of a line and follow it on the same line by the title
-of the chapter. The chapter is numbered automatically, starting
address@hidden
-
-For example, the present chapter in this manual is entitled
address@hidden@@chapter}: Chapter Structuring''; the @code{@@chapter} line
-looks like this:
-
address@hidden
-@@chapter @@address@hidden@@@@address@hidden: Chapter Structuring
address@hidden example
-
-In @TeX{}, the @code{@@chapter} command produces a chapter heading in
-the document.
-
-In Info and plain text output, the @code{@@chapter} command causes the
-title to appear on a line by itself, with a line of asterisks inserted
-underneath. So, the above example produces the following output:
-
address@hidden
address@hidden
-5 Chapter Structuring
-*********************
address@hidden group
address@hidden example
-
-In HTML, the @code{@@chapter} command produces an @code{<h2>}-level
-header by default (controlled by the @code{CHAPTER_HEADER_LEVEL}
-customization variable, @pxref{Other Customization Variables}).
-
-In the XML and Docbook output, a @code{<chapter>} element is produced
-that includes all the following sections, up to the next chapter.
-
-
address@hidden @code{@@unnumbered @@appendix}
address@hidden @code{@@unnumbered}, @code{@@appendix}: Chapters with Other
Labeling
-
address@hidden & address@hidden old name
address@hidden unnumbered
address@hidden appendix
-
-Use the @code{@@unnumbered} command to start a chapter-level element
-that appears without chapter numbers of any kind. Use the
address@hidden@@appendix} command to start an appendix that is labeled by
-letter (`A', `B', @dots{}) instead of by number; appendices are also
-at the chapter level of structuring.
-
-Write an @code{@@appendix} or @code{@@unnumbered} command at the
-beginning of a line and follow it on the same line by the title,
-just as with @code{@@chapter}.
-
address@hidden centerchap
-Texinfo also provides a command @code{@@centerchap}, which is analogous
-to @code{@@unnumbered}, but centers its argument in the printed and HTML
-outputs. This kind of stylistic choice is not usually offered by
-Texinfo. It may be suitable for short documents.
address@hidden but the Hacker's Dictionary wanted it, before they quit Texinfo.
-
address@hidden Docbook and prefatory sections
address@hidden Preface, etc., and Docbook
-With @code{@@unnumbered}, if the name of the associated node is one of
-these English words (case-insensitive):
-
address@hidden
-Acknowledgements Colophon Dedication Preface
address@hidden example
-
address@hidden @code{<acknowledgements>} Docbook tag
address@hidden @code{<colophon>} Docbook tag
address@hidden @code{<dedication>} Docbook tag
address@hidden @code{<preface>} Docbook tag
address@hidden @code{<chapter>} Docbook tag
address@hidden @code{<title>} Docbook tag
address@hidden then the Docbook output uses corresponding special tags
-(@code{<preface>}, etc.)@: instead of the default @code{<chapter>}.
-The argument to @code{@@unnumbered} itself can be anything, and is
-output as the following @code{<title>} text as usual.
-
-
address@hidden @code{@@majorheading @@chapheading}
address@hidden @code{@@majorheading}, @code{@@chapheading}: Chapter-level
Headings
-
address@hidden & address@hidden old name
address@hidden majorheading
address@hidden chapheading
-
-The @code{@@majorheading} and @code{@@chapheading} commands produce
-chapter-like headings in the body of a document.
-
-However, neither command produces an entry in the table of contents,
-and neither command causes @TeX{} to start a new page in a printed
-manual.
-
-In @TeX{}, a @code{@@majorheading} command generates a larger vertical
-whitespace before the heading than a @code{@@chapheading} command but
-is otherwise the same.
-
-In Info and plain text, the @code{@@majorheading} and
address@hidden@@chapheading} commands produce the same output as
address@hidden@@chapter}: the title is printed on a line by itself with a line
-of asterisks underneath. Similarly for address@hidden The only difference is
-the lack of numbering and the lack of any association with nodes.
address@hidden@code{@@chapter}}.
-
-
address@hidden @code{@@section}
address@hidden @code{@@section}: Sections Below Chapters
-
address@hidden@c old name
address@hidden section
-
-An @code{@@section} command identifies a section within a chapter
-unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or
address@hidden@@appendix}, following the numbering scheme of the chapter-level
-command. Thus, within a @code{@@chapter} chapter numbered `1', the
-sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix}
-``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.;
-within an @code{@@unnumbered} chapter, the section gets no number.
-The output is underlined with @samp{=} in Info and plain text.
-
-To make a section, write the @code{@@section} command at the
-beginning of a line and follow it on the same line by the section
-title. For example,
-
address@hidden
-@@section This is a section
address@hidden example
-
address@hidden
-might produce the following in Info:
-
address@hidden
address@hidden
-5.7 This is a section
-=====================
address@hidden group
address@hidden example
-
-Section titles are listed in the table of contents.
-
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
-chapter-level output, just ``one level down''; @address@hidden@@chapter}}.
-
-
address@hidden @code{@@unnumberedsec @@appendixsec @@heading}
address@hidden @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
-
address@hidden appendixsec address@hidden old name
address@hidden unnumberedsec
address@hidden appendixsec
address@hidden heading
-
-The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
-commands are, respectively, the unnumbered, appendix-like, and
-heading-like equivalents of the @code{@@section} command (see the
-previous section).
-
address@hidden@@unnumberedsec} and @code{@@appendixsec} do not need to be used
-in ordinary circumstances, because @code{@@section} may also be used
-within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
-the previous section.
-
address@hidden @code
address@hidden @@unnumberedsec
-The @code{@@unnumberedsec} command may be used within an unnumbered
-chapter or within a regular chapter or appendix to produce an
-unnumbered section.
-
address@hidden @@appendixsec
address@hidden @@appendixsection
address@hidden appendixsection
address@hidden appendixsec
address@hidden@@appendixsection} is a longer spelling of the
address@hidden@@appendixsec} command; the two are synonymous.
-
-Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
-command is used only within appendices.
-
address@hidden @@heading
-You may use the @code{@@heading} command (almost) anywhere for a
-section-style heading that will not appear in the table of contents.
-The @code{@@heading}-series commands can appear inside most
-environments, for example, though pathological and useless locations
-such as inside @code{@@titlepage}, as an argument to another command,
-etc., are not allowed.
-
address@hidden table
-
-
address@hidden @code{@@subsection}
address@hidden @code{@@subsection}: Subsections Below Sections
-
address@hidden@c old name
address@hidden subsection
-
-Subsections are to sections as sections are to chapters;
address@hidden@code{@@section}}. In Info and plain text, subsection titles
-are underlined with @samp{-}. For example,
-
address@hidden
-@@subsection This is a subsection
address@hidden example
-
address@hidden
-might produce
-
address@hidden
address@hidden
-1.2.3 This is a subsection
---------------------------
address@hidden group
address@hidden example
-
-Subsection titles are listed in the table of contents.
-
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
-chapter-level output, just ``two levels down'';
address@hidden@code{@@chapter}}.
-
-
address@hidden @code{@@unnumberedsubsec @@appendixsubsec @@subheading}
address@hidden The @code{@@subsection}-like Commands
-
address@hidden appendixsubsec address@hidden old name
address@hidden unnumberedsubsec
address@hidden appendixsubsec
address@hidden subheading
address@hidden Subsection-like commands
-
-The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
address@hidden@@subheading} commands are, respectively, the unnumbered,
-appendix-like, and heading-like equivalents of the @code{@@subsection}
-command. (@address@hidden@@subsection}}.)
-
address@hidden@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
-be used in ordinary circumstances, because @code{@@subsection} may
-also be used within sections of @code{@@unnumbered} and
address@hidden@@appendix} chapters (@address@hidden@@section}}).
-
-An @code{@@subheading} command produces a heading like that of a
-subsection except that it is not numbered and does not appear in the
-table of contents. Similarly, an @code{@@unnumberedsubsec} command
-produces an unnumbered heading like that of a subsection and an
address@hidden@@appendixsubsec} command produces a subsection-like heading
-labeled with a letter and numbers; both of these commands produce
-headings that appear in the table of contents. In Info and plain
-text, the @code{@@subsection}-like commands generate a title
-underlined with hyphens.
-
-
address@hidden @code{@@subsubsection}
address@hidden @code{@@subsection} and Other Subsub Commands
-
address@hidden@c old name
address@hidden subsubsection
address@hidden unnumberedsubsubsec
address@hidden appendixsubsubsec
address@hidden subsubheading
address@hidden Subsub sectioning commands
-
-The fourth and lowest level sectioning commands in Texinfo are the
-`subsub' commands. They are:
-
address@hidden @code
address@hidden @@subsubsection
-Subsubsections are to subsections as subsections are to sections.
-(@address@hidden@@subsection}}.) Subsubsection titles appear in the
-table of contents.
-
address@hidden @@unnumberedsubsubsec
-Unnumbered subsubsection titles appear in the table of contents,
-but lack numbers. Otherwise, unnumbered subsubsections are the same
-as subsubsections.
-
address@hidden @@appendixsubsubsec
-Conventionally, appendix commands are used only for appendices and are
-lettered and numbered appropriately. They also appear in the table
-of contents.
-
address@hidden @@subsubheading
-The @code{@@subsubheading} command may be used anywhere that you want
-a small heading that will not appear in the table of contents.
address@hidden table
-
-As with subsections, @code{@@unnumberedsubsubsec} and
address@hidden@@appendixsubsubsec} do not need to be used in ordinary
-circumstances, because @code{@@subsubsection} may also be used within
-subsections of @code{@@unnumbered} and @code{@@appendix} chapters
-(@address@hidden@@section}}).
-
-In Info, `subsub' titles are underlined with periods. For example,
-
address@hidden
-@@subsubsection This is a subsubsection
address@hidden example
-
address@hidden
-might produce
-
address@hidden
address@hidden
-1.2.3.4 This is a subsubsection
-...............................
address@hidden group
address@hidden example
-
-The @TeX{}, HTML, Docbook, and XML output is all analogous to the
-chapter-level output, just ``three levels down''; @address@hidden@@chapter}}.
-
-
address@hidden @code{@@part}
address@hidden @code{@@part}: Groups of Chapters
address@hidden part
address@hidden Part pages
-
-The final sectioning command is @code{@@part}, to mark a @dfn{part} of
-a manual, that is, a group of chapters or (rarely) appendices. This
-behaves quite differently from the other sectioning commands, to fit
-with the way such ``parts'' are conventionally used in books.
-
-No @code{@@node} command is associated with @code{@@part}. Just write
-the command on a line by itself, including the part title, at the
-place in the document you want to mark off as starting that part. For
-example:
-
address@hidden
-@@part Part I:@@* The beginning
address@hidden example
-
-As can be inferred from this example, no automatic numbering or
-labeling of the @code{@@part} text is done. The text is taken as-is.
-
-Because parts are not associated with nodes, no general text can
-follow the @code{@@part} line. To produce the intended output, it
-must be followed by a chapter-level command (including its node).
-Thus, to continue the example:
-
address@hidden
-@@part Part I:@@* The beginning
-
-@@node Introduction
-@@chapter Introduction
-...
address@hidden example
-
-In the @TeX{} output, the @code{@@part} text is included in both the
-normal and short tables of contents (@pxref{Contents}), without a page
-number (since that is the normal convention). In addition, a ``part
-page'' is output in the body of the document, with just the
address@hidden@@part} text. In the example above, the @code{@@*} causes a
-line break on the part page (but is replaced with a space in the
-tables of contents). This part page is always forced to be on an odd
-(right-hand) page, regardless of the chapter pagination
-(@address@hidden@@setchapternewpage}}).
-
-In the HTML output, the @code{@@part} text is similarly included in
-the tables of contents, and a heading is included in the main document
-text, as part of the following chapter or appendix node.
-
-In the XML and Docbook output, the @code{<part>} element includes all
-the following chapters, up to the next @code{<part>}. A @code{<part>}
-containing chapters is also closed at an appendix.
-
-In the Info and plain text output, @code{@@part} has no effect.
-
address@hidden@@part} is ignored when raising or lowering sections (see next
-section). That is, it is never lowered and nothing can be raised to it.
-
-
address@hidden Raise/lower sections
address@hidden Raise/lower Sections: @code{@@raisesections} and
@code{@@lowersections}
address@hidden raisesections
address@hidden lowersections
address@hidden Raising and lowering sections
address@hidden Lowering and raising sections
address@hidden Sections, raising and lowering
-
-The @code{@@raisesections} and @code{@@lowersections} commands
-implicitly raise and lower the hierarchical level of following
-chapters, sections and the other sectioning commands (excluding parts).
-
-That is, the @code{@@raisesections} command changes sections to
-chapters, subsections to sections, and so on. Conversely, the
address@hidden@@lowersections} command changes chapters to sections, sections
-to subsections, and so on. Thus, a @code{@@lowersections} command
-cancels a @code{@@raisesections} command, and vice versa.
-
address@hidden Include files, and section levels
-You can use @code{@@lowersections} to include text written as an outer
-or standalone Texinfo file in another Texinfo file as an inner,
-included file (@pxref{Include Files}). Typical usage looks like this:
-
address@hidden
-@@lowersections
-@@include somefile.texi
-@@raisesections
address@hidden example
-
address@hidden (Without the @code{@@raisesections}, all the subsequent
-sections in the main file would also be lowered.)
-
-If the included file being lowered has a @code{@@top} node, you'll
-need to conditionalize its inclusion with a flag (@address@hidden@@set
-@@value}}).
-
-As a practical matter, you generally only want to raise or lower large
-chunks, usually in external files as shown above. The final result has
-to have menus that take the raising and lowering into account, so you
-cannot just arbitrarily sprinkle @code{@@raisesections} and
address@hidden@@lowersections} commands throughout the document.
-
-Repeated use of the commands continues to raise or lower the
-hierarchical level a step at a time. An attempt to raise above
-`chapter' reproduces chapter commands; an attempt to lower below
-`subsubsection' reproduces subsubsection commands. Also, lowered
-subsubsections and raised chapters will not work with
address@hidden's feature of implicitly determining node pointers,
-since the menu structure cannot be represented correctly.
-
-Write each @code{@@raisesections} and @code{@@lowersections} command
-on a line of its own.
-
-
@node Nodes
@chapter Nodes
@@ -3922,7 +3294,6 @@
@menu
* @code{@@node}:: Creating nodes, in detail.
-* @code{@@anchor}:: Defining arbitrary cross reference
targets.
* Node Menu Illustration:: A diagram, and sample nodes and menus.
* @command{makeinfo} Pointer Creation:: Letting makeinfo determine node
pointers.
@end menu
@@ -4331,65 +3702,6 @@
(@pxref{Raise/lower sections}).
address@hidden @code{@@anchor}
address@hidden @code{@@anchor}: Defining Arbitrary Cross Reference Targets
-
address@hidden@c old name
address@hidden anchor
address@hidden Anchors
address@hidden Cross reference targets, arbitrary
address@hidden Targets for cross references, arbitrary
-
-An @dfn{anchor} is a position in your document, labeled so that cross
-references can refer to it, just as they can to nodes. You create an
-anchor with the @code{@@anchor} command, and give the label as a
-normal brace-delimited argument. For example:
-
address@hidden
-This marks the @@address@hidden@}spot.
address@hidden
-@@address@hidden,,the address@hidden
address@hidden example
-
address@hidden produces:
-
address@hidden
-This marks the spot.
address@hidden
-See [the spot], page 1.
address@hidden example
-
-As you can see, the @code{@@anchor} command itself produces no output.
-This example defines an anchor `x-spot' just before the word `spot'.
-You can refer to it later with an @code{@@xref} or other cross
-reference command, as shown (@pxref{Cross References}).
-
-It is best to put @code{@@anchor} commands just before the position you
-wish to refer to; that way, the reader's eye is led on to the correct
-text when they jump to the anchor. You can put the @code{@@anchor}
-command on a line by itself if that helps readability of the source.
-Whitespace (including newlines) is ignored after @code{@@anchor}.
-
-Anchor names and node names may not conflict. Anchors and nodes are
-given similar treatment in some ways; for example, the
address@hidden command takes either an anchor name or a node name as
-an argument. (@xref{Go to node,,, info, Info}.)
-
-Also like node names, anchor names cannot include some characters
-(@pxref{Node Line Requirements}).
-
address@hidden Nodes, deleting or renaming
-Because of this duality, when you delete or rename a node, it is
-usually a good idea to define an @code{@@anchor} with the old name.
-That way, any links to the old node, whether from other Texinfo
-manuals or general web pages, keep working. You can also do this with
-the @file{RENAMED_NODES_FILE} feature of @command{makeinfo}
-(@pxref{HTML Xref Link Preservation}). Both methods keep links
-on the web working; the only substantive difference is that defining
-anchors also makes the old node names available when reading the
-document in Info.
-
-
@node Node Menu Illustration
@section Node and Menu Illustration
@@ -4893,6 +4205,592 @@
refer to other files. You must write such menus by hand.
address@hidden Chapter Structuring
address@hidden Chapter Structuring
address@hidden@c old name
address@hidden Chapter structuring
address@hidden Structuring of chapters
address@hidden Sectioning
+
+Texinfo's @dfn{chapter structuring} commands divide a document into a
+hierarchy of chapters, sections, subsections, and subsubsections. These
+commands generate large headings in the text, like the one above. They
+also provide information for generating the table of contents
+(@pxref{Contents,, Generating a Table of Contents}), and for implicitly
+determining node pointers, as is recommended (@address@hidden
+Pointer Creation}).
+
+The chapter structuring commands do not create a node structure, so
+normally you put a @code{@@node} command immediately before each
+chapter structuring command (@pxref{Nodes}). The only time you are
+likely to use the chapter structuring commands without also using
+nodes is if you are writing a document that contains no cross
+references and will only be printed, not transformed into Info, HTML,
+or other formats.
+
address@hidden
+* Tree Structuring:: A manual is like an upside down tree @dots{}
+* Structuring Command Types:: How to divide a manual into parts.
+* @code{@@chapter}:: Chapter structuring.
+* @code{@@unnumbered @@appendix}::
+* @code{@@majorheading @@chapheading}::
+* @code{@@section}::
+* @code{@@unnumberedsec @@appendixsec @@heading}::
+* @code{@@subsection}::
+* @code{@@unnumberedsubsec @@appendixsubsec @@subheading}::
+* @code{@@subsubsection}:: Commands for the lowest level sections.
+* @code{@@part}:: Collections of chapters.
+* Raise/lower sections:: How to change commands' hierarchical level.
address@hidden menu
+
+
address@hidden Tree Structuring
address@hidden Tree Structure of Sections
address@hidden Tree structuring
+
+A Texinfo file is usually structured like a book with chapters,
+sections, subsections, and the like. This structure can be visualized
+as a tree (or rather as an upside-down tree) with the root at the top
+and the levels corresponding to chapters, sections, subsection, and
+subsubsections.
+
+Here is a diagram that shows a Texinfo file with three chapters, each
+with two sections.
+
address@hidden
address@hidden
+ Top
+ |
+ -------------------------------------
+ | | |
+ Chapter 1 Chapter 2 Chapter 3
+ | | |
+ -------- -------- --------
+ | | | | | |
+Section Section Section Section Section Section
+ 1.1 1.2 2.1 2.2 3.1 3.2
+
address@hidden group
address@hidden example
+
+In a Texinfo file that has this structure, the beginning of Chapter 2
+would be written like this:
+
address@hidden
address@hidden
+@@node Chapter 2
+@@chapter Chapter 2
address@hidden group
address@hidden example
+
address@hidden
+For purposes of example, here is how it would be written with
+explicit node pointers:
+
address@hidden
address@hidden
+@@node Chapter 2, Chapter 3, Chapter 1, Top
+@@chapter Chapter 2
address@hidden group
address@hidden example
+
+The chapter structuring commands are described in the sections that
+follow; the @code{@@node} command is described in
+the following chapter (@pxref{Nodes}).
+
+
address@hidden Structuring Command Types
address@hidden Structuring Command Types
+
+The chapter structuring commands fall into four groups or series, each
+of which contains structuring commands corresponding to the
+hierarchical levels of chapters, sections, subsections, and
+subsubsections.
+
+The four groups of commands are the @code{@@chapter} series, the
address@hidden@@unnumbered} series, the @code{@@appendix} series, and the
address@hidden@@heading} series. Each command produces a title with a
+different appearance in the body of the document. Some of the
+commands list their titles in the tables of contents, while others do
+not. Here are the details:
+
address@hidden @bullet
address@hidden
+The @code{@@chapter} and @code{@@appendix} series of commands produce
+numbered or lettered entries both in the body of a document and in its
+table of contents.
+
address@hidden
+The @code{@@unnumbered} series of commands produce unnumbered entries
+both in the body of a document and in its table of contents. The
address@hidden@@top} command, which has a special use, is a member of this
+series (@address@hidden@@top} Command}). An @code{@@unnumbered} section
+is a normal part of the document structure.
+
address@hidden
+The @code{@@heading} series of commands produce simple unnumbered
+headings that do not appear in a table of contents, are not associated
+with nodes, and cannot be cross-referenced. These heading commands
+never start a new page.
address@hidden itemize
+
+When a @code{@@setchapternewpage} command says to do so, the
address@hidden@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
+start new pages in the printed manual; the @code{@@heading} commands
+do not. @address@hidden@@setchapternewpage}}.
+
+Here is a summary:
+
address@hidden
+{\globaldefs=1 \smallfonts \rm}
address@hidden tex
+
address@hidden @columnfractions .19 .30 .29 .22
address@hidden @tab @tab
@tab No new page
address@hidden @i{Numbered} @tab @i{Unnumbered} @tab
@i{Lettered/numbered} @tab @i{Unnumbered}
address@hidden In contents @tab In contents @tab In
contents @tab Not in contents
address@hidden @tab @code{@@top} @tab
@tab @code{@@majorheading}
address@hidden @code{@@chapter} @tab @code{@@unnumbered} @tab
@code{@@appendix} @tab @code{@@chapheading}
address@hidden @code{@@section} @tab @code{@@unnumberedsec} @tab
@code{@@appendixsec} @tab @code{@@heading}
address@hidden @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab
@code{@@appendixsubsec} @tab @code{@@subheading}
address@hidden @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab
@code{@@appendixsubsubsec} @tab @code{@@subsubheading}
address@hidden multitable
address@hidden
+{\globaldefs=1 \textfonts \rm}
address@hidden tex
+
+
address@hidden @code{@@chapter}
address@hidden @code{@@chapter}: Chapter Structuring
+
address@hidden@c old name
address@hidden chapter
+
address@hidden@@chapter} identifies a chapter in the document--the highest
+level of the normal document structuring hierarchy. Write the command
+at the beginning of a line and follow it on the same line by the title
+of the chapter. The chapter is numbered automatically, starting
address@hidden
+
+For example, the present chapter in this manual is entitled
address@hidden@@chapter}: Chapter Structuring''; the @code{@@chapter} line
+looks like this:
+
address@hidden
+@@chapter @@address@hidden@@@@address@hidden: Chapter Structuring
address@hidden example
+
+In @TeX{}, the @code{@@chapter} command produces a chapter heading in
+the document.
+
+In Info and plain text output, the @code{@@chapter} command causes the
+title to appear on a line by itself, with a line of asterisks inserted
+underneath. So, the above example produces the following output:
+
address@hidden
address@hidden
+5 Chapter Structuring
+*********************
address@hidden group
address@hidden example
+
+In HTML, the @code{@@chapter} command produces an @code{<h2>}-level
+header by default (controlled by the @code{CHAPTER_HEADER_LEVEL}
+customization variable, @pxref{Other Customization Variables}).
+
+In the XML and Docbook output, a @code{<chapter>} element is produced
+that includes all the following sections, up to the next chapter.
+
+
address@hidden @code{@@unnumbered @@appendix}
address@hidden @code{@@unnumbered}, @code{@@appendix}: Chapters with Other
Labeling
+
address@hidden & address@hidden old name
address@hidden unnumbered
address@hidden appendix
+
+Use the @code{@@unnumbered} command to start a chapter-level element
+that appears without chapter numbers of any kind. Use the
address@hidden@@appendix} command to start an appendix that is labeled by
+letter (`A', `B', @dots{}) instead of by number; appendices are also
+at the chapter level of structuring.
+
+Write an @code{@@appendix} or @code{@@unnumbered} command at the
+beginning of a line and follow it on the same line by the title,
+just as with @code{@@chapter}.
+
address@hidden centerchap
+Texinfo also provides a command @code{@@centerchap}, which is analogous
+to @code{@@unnumbered}, but centers its argument in the printed and HTML
+outputs. This kind of stylistic choice is not usually offered by
+Texinfo. It may be suitable for short documents.
address@hidden but the Hacker's Dictionary wanted it, before they quit Texinfo.
+
address@hidden Docbook and prefatory sections
address@hidden Preface, etc., and Docbook
+With @code{@@unnumbered}, if the name of the associated node is one of
+these English words (case-insensitive):
+
address@hidden
+Acknowledgements Colophon Dedication Preface
address@hidden example
+
address@hidden @code{<acknowledgements>} Docbook tag
address@hidden @code{<colophon>} Docbook tag
address@hidden @code{<dedication>} Docbook tag
address@hidden @code{<preface>} Docbook tag
address@hidden @code{<chapter>} Docbook tag
address@hidden @code{<title>} Docbook tag
address@hidden then the Docbook output uses corresponding special tags
+(@code{<preface>}, etc.)@: instead of the default @code{<chapter>}.
+The argument to @code{@@unnumbered} itself can be anything, and is
+output as the following @code{<title>} text as usual.
+
+
address@hidden @code{@@majorheading @@chapheading}
address@hidden @code{@@majorheading}, @code{@@chapheading}: Chapter-level
Headings
+
address@hidden & address@hidden old name
address@hidden majorheading
address@hidden chapheading
+
+The @code{@@majorheading} and @code{@@chapheading} commands produce
+chapter-like headings in the body of a document.
+
+However, neither command produces an entry in the table of contents,
+and neither command causes @TeX{} to start a new page in a printed
+manual.
+
+In @TeX{}, a @code{@@majorheading} command generates a larger vertical
+whitespace before the heading than a @code{@@chapheading} command but
+is otherwise the same.
+
+In Info and plain text, the @code{@@majorheading} and
address@hidden@@chapheading} commands produce the same output as
address@hidden@@chapter}: the title is printed on a line by itself with a line
+of asterisks underneath. Similarly for address@hidden The only difference is
+the lack of numbering and the lack of any association with nodes.
address@hidden@code{@@chapter}}.
+
+
address@hidden @code{@@section}
address@hidden @code{@@section}: Sections Below Chapters
+
address@hidden@c old name
address@hidden section
+
+An @code{@@section} command identifies a section within a chapter
+unit, whether created with @code{@@chapter}, @code{@@unnumbered}, or
address@hidden@@appendix}, following the numbering scheme of the chapter-level
+command. Thus, within a @code{@@chapter} chapter numbered `1', the
+sections are numbered `1.1', `1.2', etc.; within an @code{@@appendix}
+``chapter'' labeled `A', the sections are numbered `A.1', `A.2', etc.;
+within an @code{@@unnumbered} chapter, the section gets no number.
+The output is underlined with @samp{=} in Info and plain text.
+
+To make a section, write the @code{@@section} command at the
+beginning of a line and follow it on the same line by the section
+title. For example,
+
address@hidden
+@@section This is a section
address@hidden example
+
address@hidden
+might produce the following in Info:
+
address@hidden
address@hidden
+5.7 This is a section
+=====================
address@hidden group
address@hidden example
+
+Section titles are listed in the table of contents.
+
+The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+chapter-level output, just ``one level down''; @address@hidden@@chapter}}.
+
+
address@hidden @code{@@unnumberedsec @@appendixsec @@heading}
address@hidden @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
+
address@hidden appendixsec address@hidden old name
address@hidden unnumberedsec
address@hidden appendixsec
address@hidden heading
+
+The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
+commands are, respectively, the unnumbered, appendix-like, and
+heading-like equivalents of the @code{@@section} command (see the
+previous section).
+
address@hidden@@unnumberedsec} and @code{@@appendixsec} do not need to be used
+in ordinary circumstances, because @code{@@section} may also be used
+within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
+the previous section.
+
address@hidden @code
address@hidden @@unnumberedsec
+The @code{@@unnumberedsec} command may be used within an unnumbered
+chapter or within a regular chapter or appendix to produce an
+unnumbered section.
+
address@hidden @@appendixsec
address@hidden @@appendixsection
address@hidden appendixsection
address@hidden appendixsec
address@hidden@@appendixsection} is a longer spelling of the
address@hidden@@appendixsec} command; the two are synonymous.
+
+Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
+command is used only within appendices.
+
address@hidden @@heading
+You may use the @code{@@heading} command (almost) anywhere for a
+section-style heading that will not appear in the table of contents.
+The @code{@@heading}-series commands can appear inside most
+environments, for example, though pathological and useless locations
+such as inside @code{@@titlepage}, as an argument to another command,
+etc., are not allowed.
+
address@hidden table
+
+
address@hidden @code{@@subsection}
address@hidden @code{@@subsection}: Subsections Below Sections
+
address@hidden@c old name
address@hidden subsection
+
+Subsections are to sections as sections are to chapters;
address@hidden@code{@@section}}. In Info and plain text, subsection titles
+are underlined with @samp{-}. For example,
+
address@hidden
+@@subsection This is a subsection
address@hidden example
+
address@hidden
+might produce
+
address@hidden
address@hidden
+1.2.3 This is a subsection
+--------------------------
address@hidden group
address@hidden example
+
+Subsection titles are listed in the table of contents.
+
+The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+chapter-level output, just ``two levels down'';
address@hidden@code{@@chapter}}.
+
+
address@hidden @code{@@unnumberedsubsec @@appendixsubsec @@subheading}
address@hidden The @code{@@subsection}-like Commands
+
address@hidden appendixsubsec address@hidden old name
address@hidden unnumberedsubsec
address@hidden appendixsubsec
address@hidden subheading
address@hidden Subsection-like commands
+
+The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
address@hidden@@subheading} commands are, respectively, the unnumbered,
+appendix-like, and heading-like equivalents of the @code{@@subsection}
+command. (@address@hidden@@subsection}}.)
+
address@hidden@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
+be used in ordinary circumstances, because @code{@@subsection} may
+also be used within sections of @code{@@unnumbered} and
address@hidden@@appendix} chapters (@address@hidden@@section}}).
+
+An @code{@@subheading} command produces a heading like that of a
+subsection except that it is not numbered and does not appear in the
+table of contents. Similarly, an @code{@@unnumberedsubsec} command
+produces an unnumbered heading like that of a subsection and an
address@hidden@@appendixsubsec} command produces a subsection-like heading
+labeled with a letter and numbers; both of these commands produce
+headings that appear in the table of contents. In Info and plain
+text, the @code{@@subsection}-like commands generate a title
+underlined with hyphens.
+
+
address@hidden @code{@@subsubsection}
address@hidden @code{@@subsection} and Other Subsub Commands
+
address@hidden@c old name
address@hidden subsubsection
address@hidden unnumberedsubsubsec
address@hidden appendixsubsubsec
address@hidden subsubheading
address@hidden Subsub sectioning commands
+
+The fourth and lowest level sectioning commands in Texinfo are the
+`subsub' commands. They are:
+
address@hidden @code
address@hidden @@subsubsection
+Subsubsections are to subsections as subsections are to sections.
+(@address@hidden@@subsection}}.) Subsubsection titles appear in the
+table of contents.
+
address@hidden @@unnumberedsubsubsec
+Unnumbered subsubsection titles appear in the table of contents,
+but lack numbers. Otherwise, unnumbered subsubsections are the same
+as subsubsections.
+
address@hidden @@appendixsubsubsec
+Conventionally, appendix commands are used only for appendices and are
+lettered and numbered appropriately. They also appear in the table
+of contents.
+
address@hidden @@subsubheading
+The @code{@@subsubheading} command may be used anywhere that you want
+a small heading that will not appear in the table of contents.
address@hidden table
+
+As with subsections, @code{@@unnumberedsubsubsec} and
address@hidden@@appendixsubsubsec} do not need to be used in ordinary
+circumstances, because @code{@@subsubsection} may also be used within
+subsections of @code{@@unnumbered} and @code{@@appendix} chapters
+(@address@hidden@@section}}).
+
+In Info, `subsub' titles are underlined with periods. For example,
+
address@hidden
+@@subsubsection This is a subsubsection
address@hidden example
+
address@hidden
+might produce
+
address@hidden
address@hidden
+1.2.3.4 This is a subsubsection
+...............................
address@hidden group
address@hidden example
+
+The @TeX{}, HTML, Docbook, and XML output is all analogous to the
+chapter-level output, just ``three levels down''; @address@hidden@@chapter}}.
+
+
address@hidden @code{@@part}
address@hidden @code{@@part}: Groups of Chapters
address@hidden part
address@hidden Part pages
+
+The final sectioning command is @code{@@part}, to mark a @dfn{part} of
+a manual, that is, a group of chapters or (rarely) appendices. This
+behaves quite differently from the other sectioning commands, to fit
+with the way such ``parts'' are conventionally used in books.
+
+No @code{@@node} command is associated with @code{@@part}. Just write
+the command on a line by itself, including the part title, at the
+place in the document you want to mark off as starting that part. For
+example:
+
address@hidden
+@@part Part I:@@* The beginning
address@hidden example
+
+As can be inferred from this example, no automatic numbering or
+labeling of the @code{@@part} text is done. The text is taken as-is.
+
+Because parts are not associated with nodes, no general text can
+follow the @code{@@part} line. To produce the intended output, it
+must be followed by a chapter-level command (including its node).
+Thus, to continue the example:
+
address@hidden
+@@part Part I:@@* The beginning
+
+@@node Introduction
+@@chapter Introduction
+...
address@hidden example
+
+In the @TeX{} output, the @code{@@part} text is included in both the
+normal and short tables of contents (@pxref{Contents}), without a page
+number (since that is the normal convention). In addition, a ``part
+page'' is output in the body of the document, with just the
address@hidden@@part} text. In the example above, the @code{@@*} causes a
+line break on the part page (but is replaced with a space in the
+tables of contents). This part page is always forced to be on an odd
+(right-hand) page, regardless of the chapter pagination
+(@address@hidden@@setchapternewpage}}).
+
+In the HTML output, the @code{@@part} text is similarly included in
+the tables of contents, and a heading is included in the main document
+text, as part of the following chapter or appendix node.
+
+In the XML and Docbook output, the @code{<part>} element includes all
+the following chapters, up to the next @code{<part>}. A @code{<part>}
+containing chapters is also closed at an appendix.
+
+In the Info and plain text output, @code{@@part} has no effect.
+
address@hidden@@part} is ignored when raising or lowering sections (see next
+section). That is, it is never lowered and nothing can be raised to it.
+
+
address@hidden Raise/lower sections
address@hidden Raise/lower Sections: @code{@@raisesections} and
@code{@@lowersections}
address@hidden raisesections
address@hidden lowersections
address@hidden Raising and lowering sections
address@hidden Lowering and raising sections
address@hidden Sections, raising and lowering
+
+The @code{@@raisesections} and @code{@@lowersections} commands
+implicitly raise and lower the hierarchical level of following
+chapters, sections and the other sectioning commands (excluding parts).
+
+That is, the @code{@@raisesections} command changes sections to
+chapters, subsections to sections, and so on. Conversely, the
address@hidden@@lowersections} command changes chapters to sections, sections
+to subsections, and so on. Thus, a @code{@@lowersections} command
+cancels a @code{@@raisesections} command, and vice versa.
+
address@hidden Include files, and section levels
+You can use @code{@@lowersections} to include text written as an outer
+or standalone Texinfo file in another Texinfo file as an inner,
+included file (@pxref{Include Files}). Typical usage looks like this:
+
address@hidden
+@@lowersections
+@@include somefile.texi
+@@raisesections
address@hidden example
+
address@hidden (Without the @code{@@raisesections}, all the subsequent
+sections in the main file would also be lowered.)
+
+If the included file being lowered has a @code{@@top} node, you'll
+need to conditionalize its inclusion with a flag (@address@hidden@@set
+@@value}}).
+
+As a practical matter, you generally only want to raise or lower large
+chunks, usually in external files as shown above. The final result has
+to have menus that take the raising and lowering into account, so you
+cannot just arbitrarily sprinkle @code{@@raisesections} and
address@hidden@@lowersections} commands throughout the document.
+
+Repeated use of the commands continues to raise or lower the
+hierarchical level a step at a time. An attempt to raise above
+`chapter' reproduces chapter commands; an attempt to lower below
+`subsubsection' reproduces subsubsection commands. Also, lowered
+subsubsections and raised chapters will not work with
address@hidden's feature of implicitly determining node pointers,
+since the menu structure cannot be represented correctly.
+
+Write each @code{@@raisesections} and @code{@@lowersections} command
+on a line of its own.
+
+
@node Cross References
@chapter Cross References
@cindex Making cross references
@@ -4911,6 +4809,7 @@
* Top Node Naming:: How to refer to the beginning of another file.
* @code{@@ref}:: A reference for the last part of a
sentence.
* @code{@@pxref}:: How to write a parenthetical cross
reference.
+* @code{@@anchor}:: Defining arbitrary cross-reference
targets
* @code{@@inforef}:: How to refer to an Info-only file.
* @code{@@url}:: How to refer to a uniform resource
locator.
* @code{@@cite}:: How to refer to books not in the Info
system.
@@ -5829,6 +5728,65 @@
that location breaks up the flow of reading.
address@hidden @code{@@anchor}
address@hidden @code{@@anchor}: Defining Arbitrary Cross Reference Targets
+
address@hidden@c old name
address@hidden anchor
address@hidden Anchors
address@hidden Cross reference targets, arbitrary
address@hidden Targets for cross references, arbitrary
+
+An @dfn{anchor} is a position in your document, labelled so that
+cross-references can refer to it, just as they can to nodes. You
+create an anchor with the @code{@@anchor} command, and give the label
+as a normal brace-delimited argument. For example:
+
address@hidden
+This marks the @@address@hidden@}spot.
address@hidden
+@@address@hidden,,the address@hidden
address@hidden example
+
address@hidden produces:
+
address@hidden
+This marks the spot.
address@hidden
+See [the spot], page 1.
address@hidden example
+
+As you can see, the @code{@@anchor} command itself produces no output.
+This example defines an anchor `x-spot' just before the word `spot'.
+You can refer to it later with an @code{@@xref} or other cross
+reference command, as shown (@pxref{Cross References}).
+
+It is best to put @code{@@anchor} commands just before the position you
+wish to refer to; that way, the reader's eye is led on to the correct
+text when they jump to the anchor. You can put the @code{@@anchor}
+command on a line by itself if that helps readability of the source.
+Whitespace (including newlines) is ignored after @code{@@anchor}.
+
+Anchor names and node names may not conflict. Anchors and nodes are
+given similar treatment in some ways; for example, the
address@hidden command takes either an anchor name or a node name as
+an argument. (@xref{Go to node,,, info, Info}.)
+
+Also like node names, anchor names cannot include some characters
+(@pxref{Node Line Requirements}).
+
address@hidden Nodes, deleting or renaming
+Because of this duality, when you delete or rename a node, it is
+usually a good idea to define an @code{@@anchor} with the old name.
+That way, any links to the old node, whether from other Texinfo
+manuals or general web pages, keep working. You can also do this with
+the @file{RENAMED_NODES_FILE} feature of @command{makeinfo}
+(@pxref{HTML Xref Link Preservation}). Both methods keep links
+on the web working; the only substantive difference is that defining
+anchors also makes the old node names available when reading the
+document in Info.
+
+
@node @code{@@inforef}
@section @code{@@inforef}: Cross References to Info-only Material
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [6571] some reorganization of introductory material in manual,
Gavin D. Smith <=