This is texinfo, produced by makeinfo version 4.2 from texinfo.txi.

This manual is for GNU Texinfo (version 4.2, 28 March 2002), 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.

     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."
  
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo).           The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Update info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi.      Print Texinfo documents.
* texindex: (texinfo)Format with tex/texindex.  Sort Texinfo index files.
* makeinfo: (texinfo)Invoking makeinfo.         Translate Texinfo source.
END-INFO-DIR-ENTRY


File: texinfo,  Node: Top,  Next: Copying Conditions,  Up: (dir)

Texinfo
*******

This manual is for GNU Texinfo (version 4.2, 28 March 2002), 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.

     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."
  
  The first part of this master menu lists the major nodes in this Info
document, including the @-command and concept indices.  The rest of the
menu lists all the lower level nodes in the document.

* Menu:

* Copying Conditions::          Your rights.
* Overview::                    Texinfo in brief.
* Texinfo Mode::                How to use Texinfo mode.
* Beginning a File::            What is at the beginning of a Texinfo file?
* Ending a File::               What is at the end of a Texinfo file?
* Structuring::                 How to create chapters, sections, subsections,
                                  appendices, and other parts.
* Nodes::                       How to write nodes.
* Menus::                       How to write menus.
* Cross References::            How to write cross references.
* Marking Text::                How to mark words and phrases as code,
                                  keyboard input, meta-syntactic
                                  variables, and the like.
* Quotations and Examples::     How to write quotations, examples, etc.
* Lists and Tables::            How to write lists and tables.
* Indices::                     How to create indices.
* Insertions::                  How to insert @-signs, braces, etc.
* Breaks::                      How to force and prevent line and page breaks.
* Definition Commands::         How to describe functions and the like
                                  in a uniform manner.
* Conditionals::                How to specify text for either TeX or Info.
* Internationalization::
* Defining New Texinfo Commands::
* Hardcopy::                    How to convert a Texinfo file to a file
                                  for printing and how to print that file.
* Creating and Installing Info Files::
* Command List::                All the Texinfo @-commands.
* Tips::                        Hints on how to write a Texinfo document.
* Sample Texinfo Files::        Complete examples, including full texts.
* Include Files::               How to incorporate other Texinfo files.
* Headings::                    How to write page headings and footings.
* Catching Mistakes::           How to find formatting mistakes.
* Refilling Paragraphs::        All about paragraph refilling.
* Command Syntax::              A description of @-Command syntax.
* Obtaining TeX::               How to Obtain TeX.
* Copying This Manual::         The GNU Free Documentation License.
* Command and Variable Index::  A menu containing commands and variables.
* Concept Index::               A menu covering many topics.

 --- The Detailed Node Listing ---

Overview of Texinfo

* Reporting Bugs::              Submitting effective bug reports.
* Using Texinfo::               Create printed or online output.
* Info Files::                  What is an Info file?
* Printed Books::               Characteristics of a printed book or manual.
* Formatting Commands::         @-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.

Using Texinfo Mode

* Texinfo Mode Overview::       How Texinfo mode can help you.
* Emacs Editing::               Texinfo mode adds to GNU Emacs' general
                                  purpose editing features.
* Inserting::                   How to insert frequently used @-commands.
* Showing the Structure::       How to show the structure of a file.
* Updating Nodes and Menus::    How to update or create new nodes and menus.
* Info Formatting::             How to format for Info.
* Printing::                    How to format and print part or all of a file.
* Texinfo Mode Summary::        Summary of all the Texinfo mode commands.

Updating Nodes and Menus

* Updating Commands::           Five major updating commands.
* Updating Requirements::       How to structure a Texinfo file for
                                  using the updating command.
* Other Updating Commands::     How to indent descriptions, insert
                                  missing nodes lines, and update
                                  nodes in sequence.

Beginning a Texinfo File

* Sample Beginning::            A sample beginning for a Texinfo file.
* Texinfo File Header::
* Document Permissions::
* Titlepage & Copyright Page::  Creating the title and copyright pages.
* The Top Node::                Creating the `Top' node and master menu.
* Global Document Commands::
* Software Copying Permissions::  Ensure that you and others continue to
                                    have the right to use and share software.

Texinfo File Header

* First Line::                  The first line of a Texinfo file.
* Start of Header::             Formatting a region requires this.
* setfilename::                 Tell Info the name of the Info file.
* settitle::                    Create a title for the printed work.
* End of Header::               Formatting a region requires this.

Document Permissions

* copying::                     Declare the document's copying permissions.
* insertcopying::               Where to insert the permissions.

Title and Copyright Pages

* titlepage::                   Create a title for the printed document.
* titlefont center sp::         The `@titlefont', `@center',
                                  and `@sp' commands.
* title subtitle author::       The `@title', `@subtitle',
                                  and `@author' commands.
* Copyright::                   How to write the copyright notice and
                                  include copying permissions.
* end titlepage::               Turn on page headings after the title and
                                  copyright pages.
* headings on off::             An option for turning headings on and off
                                  and double or single sided printing.

The `Top' Node and Master Menu

* Top Node Example::
* Master Menu Parts::

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.

Ending a Texinfo File

* Printing Indices & Menus::    How to print an index in hardcopy and
                                  generate index menus in Info.
* Contents::                    How to create a table of contents.
* File End::                    How to mark the end of a file.

Chapter Structuring

* Tree Structuring::            A manual is like an upside down tree ...
* Structuring Command Types::   How to divide a manual into parts.
* makeinfo top::                The `@top' command, part of the `Top' node.
* chapter::
* unnumbered & appendix::
* majorheading & chapheading::
* section::
* unnumberedsec appendixsec heading::
* subsection::
* unnumberedsubsec appendixsubsec subheading::
* subsubsection::               Commands for the lowest level sections.
* Raise/lower sections::        How to change commands' hierarchical level.

Nodes

* Two Paths::                   Different commands to structure
                                  Info output and printed output.
* Node Menu Illustration::      A diagram, and sample nodes and menus.
* node::                        Creating nodes, in detail.
* makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
* anchor::                      Defining arbitrary cross-reference targets.

The `@node' Command

* Node Names::                  How to choose node and pointer names.
* Writing a Node::              How to write an `@node' line.
* Node Line Tips::              Keep names short.
* Node Line Requirements::      Keep names unique, without @-commands.
* First Node::                  How to write a `Top' node.
* makeinfo top command::        How to use the `@top' command.

Menus

* Menu Location::               Put a menu in a short node.
* Writing a Menu::              What is a menu?
* Menu Parts::                  A menu entry has three parts.
* Less Cluttered Menu Entry::   Two part menu entry.
* Menu Example::                Two and three part menu entries.
* Other Info Files::            How to refer to a different Info file.

Cross References

* References::                  What cross references are for.
* Cross Reference Commands::    A summary of the different commands.
* Cross Reference Parts::       A cross reference has several parts.
* xref::                        Begin a reference with `See' ...
* Top Node Naming::             How to refer to the beginning of another file.
* ref::                         A reference for the last part of a sentence.
* pxref::                       How to write a parenthetical cross reference.
* inforef::                     How to refer to an Info-only file.
* uref::                        How to refer to a uniform resource locator.

`@xref'

* Reference Syntax::            What a reference looks like and requires.
* One Argument::                `@xref' with one argument.
* Two Arguments::               `@xref' with two arguments.
* Three Arguments::             `@xref' with three arguments.
* Four and Five Arguments::     `@xref' with four and five arguments.

Marking Words and Phrases

* Indicating::                  How to indicate definitions, files, etc.
* Emphasis::                    How to emphasize text.

Indicating Definitions, Commands, etc.

* Useful Highlighting::         Highlighting provides useful information.
* code::                        Indicating program code.
* kbd::                         Showing keyboard input.
* key::                         Specifying keys.
* samp::                        A literal sequence of characters.
* verb::                        A verbatim sequence of characters.
* var::                         Indicating metasyntactic variables.
* env::                         Indicating environment variables.
* file::                        Indicating file names.
* command::                     Indicating command names.
* option::                      Indicating option names.
* dfn::                         Specifying definitions.
* cite::                        Referring to books not in the  Info system.
* acronym::                     Indicating acronyms.
* url::                         Indicating a World Wide Web reference.
* email::                       Indicating an electronic mail address.

Emphasizing Text

* emph & strong::               How to emphasize text in Texinfo.
* Smallcaps::                   How to use the small caps font.
* Fonts::                       Various font commands for printed output.

Quotations and Examples

* Block Enclosing Commands::    Different constructs for different purposes.
* quotation::                   Writing a quotation.
* example::                     Writing an example in a fixed-width font.
* verbatim::                    Writing a verbatim example.
* verbatiminclude::             Including a file verbatim.
* lisp::                        Illustrating Lisp code.
* small::                       Forms for `@smallbook'.
* display::                     Writing an example in the current font.
* format::                      Writing an example without narrowed margins.
* exdent::                      Undo indentation on a line.
* flushleft & flushright::      Pushing text flush left or flush right.
* noindent::                    Preventing paragraph indentation.
* cartouche::                   Drawing rounded rectangles around examples.

Lists and Tables

* Introducing Lists::           Texinfo formats lists for you.
* itemize::                     How to construct a simple list.
* enumerate::                   How to construct a numbered list.
* Two-column Tables::           How to construct a two-column table.
* Multi-column Tables::         How to construct generalized tables.

Making a Two-column Table

* table::                       How to construct a two-column table.
* ftable vtable::               Automatic indexing for two-column tables.
* itemx::                       How to put more entries in the first column.

Multi-column Tables

* Multitable Column Widths::    Defining multitable column widths.
* Multitable Rows::             Defining multitable rows, with examples.

Indices

* Index Entries::               Choose different words for index entries.
* Predefined Indices::          Use different indices for different kinds
                                  of entry.
* Indexing Commands::           How to make an index entry.
* Combining Indices::           How to combine indices.
* New Indices::                 How to define your own indices.

Combining Indices

* syncodeindex::                How to merge two indices, using `@code'
                                  font for the merged-from index.
* synindex::                    How to merge two indices, using the
                                  default font of the merged-to index.

Special Insertions

* Braces Atsigns::              How to insert braces, `@'.
* Inserting Space::             How to insert the right amount of space
                                  within a sentence.
* Inserting Accents::           How to insert accents and special characters.
* Dots Bullets::                How to insert dots and bullets.
* TeX and copyright::           How to insert the TeX logo
                                  and the copyright symbol.
* pounds::                      How to insert the pounds currency symbol.
* minus::                       How to insert a minus sign.
* math::                        How to format a mathematical expression.
* Glyphs::                      How to indicate results of evaluation,
                                  expansion of macros, errors, etc.
* Footnotes::                   How to include footnotes.
* Images::                      How to include graphics.

Inserting @ and Braces

* Inserting An Atsign::         How to insert `@'.
* Inserting Braces::            How to insert `{' and `}'.

Inserting Space

* Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
* Ending a Sentence::           Sometimes it does.
* Multiple Spaces::             Inserting multiple spaces.
* dmn::                         How to format a dimension.

Inserting Ellipsis and Bullets

* dots::                        How to insert dots ...
* bullet::                      How to insert a bullet.

Inserting TeX and the Copyright Symbol

* tex::                         How to insert the TeX logo.
* copyright symbol::            How to use `@copyright'{}.

Glyphs for Examples

* Glyphs Summary::
* result::                      How to show the result of expression.
* expansion::                   How to indicate an expansion.
* Print Glyph::                 How to indicate printed output.
* Error Glyph::                 How to indicate an error message.
* Equivalence::                 How to indicate equivalence.
* Point Glyph::                 How to indicate the location of point.

Glyphs Summary

* result::
* expansion::
* Print Glyph::
* Error Glyph::
* Equivalence::
* Point Glyph::

Footnotes

* Footnote Commands::           How to write a footnote in Texinfo.
* Footnote Styles::             Controlling how footnotes appear in Info.

Making and Preventing Breaks

* Break Commands::              Cause and prevent splits.
* Line Breaks::                 How to force a single line to use two lines.
* - and hyphenation::           How to tell TeX about hyphenation points.
* w::                           How to prevent unwanted line breaks.
* sp::                          How to insert blank lines.
* page::                        How to force the start of a new page.
* group::                       How to prevent unwanted page breaks.
* need::                        Another way to prevent unwanted page breaks.

Definition Commands

* Def Cmd Template::            How to structure a description using a
                                  definition command.
* Optional Arguments::          How to handle optional and repeated arguments.
* deffnx::                      How to group two or more `first' lines.
* Def Cmds in Detail::          All the definition commands.
* Def Cmd Conventions::         Conventions for writing definitions.
* Sample Function Definition::

The Definition Commands

* Functions Commands::          Commands for functions and similar entities.
* Variables Commands::          Commands for variables and similar entities.
* Typed Functions::             Commands for functions in typed languages.
* Typed Variables::             Commands for variables in typed languages.
* Abstract Objects::            Commands for object-oriented programming.
* Data Types::                  The definition command for data types.

Conditionally Visible Text

* Conditional Commands::        Specifying text for HTML, Info, or TeX.
* Conditional Not Commands::    Specifying text for not HTML, Info, or TeX.
* Raw Formatter Commands::      Using raw TeX or HTML commands.
* set clear value::             Designating which text to format (for
                                  all output formats); and how to set a
                                  flag to a string that you can insert.

`@set', `@clear', and `@value'

* set value::                   Expand a flag variable to a string.
* ifset ifclear::               Format a region if a flag is set.
* value Example::               An easy way to update edition information.

Internationalization

* documentlanguage::            Declaring the current language.
* documentencoding::            Declaring the input encoding.

Defining New Texinfo Commands

* Defining Macros::             Defining and undefining new commands.
* Invoking Macros::             Using a macro, once you've defined it.
* Macro Details::               Beyond basic macro usage.
* alias::                       Command aliases.
* definfoenclose::              Customized highlighting.

Formatting and Printing Hardcopy

* Use TeX::                     Use TeX to format for hardcopy.
* Format with tex/texindex::    How to format with explicit shell commands.
* Format with texi2dvi::        A simpler way to format.
* Print with lpr::              How to print.
* Within Emacs::                How to format and print from an Emacs shell.
* Texinfo Mode Printing::       How to format and print in Texinfo mode.
* Compile-Command::             How to print using Emacs's compile command.
* Requirements Summary::        TeX formatting requirements summary.
* Preparing for TeX::           What to do before you use TeX.
* Overfull hboxes::             What are and what to do with overfull hboxes.
* smallbook::                   How to print small format books and manuals.
* A4 Paper::                    How to print on A4 or A5 paper.
* pagesizes::                   How to print with customized page sizes.
* Cropmarks and Magnification::  How to print marks to indicate the size
                                of pages and how to print scaled up output.
* PDF Output::                  Portable Document Format output.

Creating and Installing Info Files

* Creating an Info File::
* Installing an Info File::

Creating an Info File

* makeinfo advantages::         `makeinfo' provides better error checking.
* Invoking makeinfo::           How to run `makeinfo' from a shell.
* makeinfo options::            Specify fill-column and other options.
* Pointer Validation::          How to check that pointers point somewhere.
* makeinfo in Emacs::           How to run `makeinfo' from Emacs.
* texinfo-format commands::     Two Info formatting commands written
                                  in Emacs Lisp are an alternative
                                  to `makeinfo'.
* Batch Formatting::            How to format for Info in Emacs Batch mode.
* Tag and Split Files::         How tagged and split files help Info
                                  to run better.
* makeinfo html::               Generating HTML output.

Installing an Info File

* Directory File::              The top level menu for all Info files.
* New Info File::               Listing a new Info file.
* Other Info Directories::      How to specify Info files that are
                                  located in other directories.
* Installing Dir Entries::      How to specify what menu entry to add
                                  to the Info directory.
* Invoking install-info::       `install-info' options.

Sample Texinfo Files

* Short Sample Texinfo File::
* GNU Sample Texts::

Include Files

* Using Include Files::         How to use the `@include' command.
* texinfo-multiple-files-update::  How to create and update nodes and
                                  menus when using included files.
* Include File Requirements::   What `texinfo-multiple-files-update' expects.
* Sample Include File::         A sample outer file with included files
                                  within it; and a sample included file.
* Include Files Evolution::     How use of the `@include' command
                                  has changed over time.

Page Headings

* Headings Introduced::         Conventions for using page headings.
* Heading Format::              Standard page heading formats.
* Heading Choice::              How to specify the type of page heading.
* Custom Headings::             How to create your own headings and footings.

Formatting Mistakes

* makeinfo Preferred::          `makeinfo' finds errors.
* Debugging with Info::         How to catch errors with Info formatting.
* Debugging with TeX::          How to catch errors with TeX formatting.
* Using texinfo-show-structure::  How to use `texinfo-show-structure'.
* Using occur::                 How to list all lines containing a pattern.
* Running Info-Validate::       How to find badly referenced nodes.

Finding Badly Referenced Nodes

* Using Info-validate::         How to run `Info-validate'.
* Unsplit::                     How to create an unsplit file.
* Tagifying::                   How to tagify a file.
* Splitting::                   How to split a file manually.

Copying This Manual

* GNU Free Documentation License::  License for copying this manual.

     Documentation is like sex: when it is good, it is very, very good;
     and when it is bad, it is better than nothing.  --Dick Brandon


File: texinfo,  Node: Copying Conditions,  Next: Overview,  Prev: Top,  Up: Top

Texinfo Copying Conditions
**************************

  The programs currently being distributed that relate to Texinfo
include `makeinfo', `info', `texindex', and `texinfo.tex'.  These
programs are "free"; this means that everyone is free to use them and
free to redistribute them on a free basis.  The Texinfo-related
programs are not in the public domain; they are copyrighted and there
are restrictions on their distribution, but these restrictions are
designed to permit everything that a good cooperating citizen would want
to do.  What is not allowed is to try to prevent others from further
sharing any version of these programs that they might get from you.

  Specifically, we want to make sure that you have the right to give
away copies of the programs that relate to Texinfo, that you receive
source code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

  To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of the Texinfo related programs, you must give the recipients all
the rights that you have.  You must make sure that they, too, receive or
can get the source code.  And you must tell them their rights.

  Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to Texinfo.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.

  The precise conditions of the licenses for the programs currently
being distributed that relate to Texinfo are found in the General Public
Licenses that accompany them.  This manual specifically is covered by
the GNU Free Documentation License (*note GNU Free Documentation
License::).


File: texinfo,  Node: Overview,  Next: Texinfo Mode,  Prev: Copying Conditions,  Up: Top

Overview of Texinfo
*******************

  "Texinfo"(1) (*note Overview-Footnote-1::)  is a documentation system
that uses a single source file to produce both online information and
printed output.  This means that instead of writing two different
documents, one for the online information and the other for a printed
work, you need write only one document.  Therefore, when the work is
revised, you need revise only that one document.

* Menu:

* Reporting Bugs::              Submitting effective bug reports.
* Using Texinfo::               Create printed or online output.
* Info Files::                  What is an Info file?
* Printed Books::               Characteristics of a printed book or manual.
* Formatting Commands::         @-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.


File: texinfo,  Node: Overview-Footnotes,  Up: Overview

  (1) The first syllable of "Texinfo" is pronounced like "speck", not
"hex".  This odd pronunciation is derived from, but is not the same as,
the pronunciation of TeX.  In the word TeX, the `X' is actually the
Greek letter "chi" rather than the English letter "ex".  Pronounce TeX
as if the `X' were the last sound in the name `Bach'; but pronounce
Texinfo as if the `x' were a `k'.  Spell "Texinfo" with a capital "T"
and the other letters in lower case.


File: texinfo,  Node: Reporting Bugs,  Next: Using Texinfo,  Up: Overview

Reporting Bugs
==============

  We welcome bug reports and suggestions for any aspect of the Texinfo
system, programs, documentation, installation, anything.  Please email
them to <bug-texinfo@gnu.org>.  You can get the latest version of
Texinfo from `ftp://ftp.gnu.org/gnu/texinfo/' and its mirrors worldwide.

  For bug reports, please include enough information for the maintainers
to reproduce the problem.  Generally speaking, that means:

   * the version number of Texinfo and the program(s) or manual(s)
     involved.

   * hardware and operating system names and versions.

   * the contents of any input files necessary to reproduce the bug.

   * a description of the problem and samples of any erroneous output.

   * any unusual options you gave to `configure'.

   * anything else that you think would be helpful.

  When in doubt whether something is needed or not, include it.  It's
better to include too much than to leave out something important.

  Patches are most welcome; if possible, please make them with
`diff -c' (*note Overview: (diffutils)Top.) and include `ChangeLog'
entries (*note Change Log: (emacs)Change Log.).

  When sending patches, if possible please do not encode or split them
in any way; it's much easier to deal with one plain text message,
however large, than many small ones.  GNU shar
(ftp://ftp.gnu.org/gnu/sharutils/) is a convenient way of packaging
multiple and/or binary files for email.


File: texinfo,  Node: Using Texinfo,  Next: Info Files,  Prev: Reporting Bugs,  Up: Overview

Using Texinfo
=============

  Using Texinfo, you can create a printed document with the normal
features of a book, including chapters, sections, cross references, and
indices.  From the same Texinfo source file, you can create a
menu-driven, online Info file with nodes, menus, cross references, and
indices.  You can also create from that same source file an HTML output
file suitable for use with a web browser, or an XML file.  `The GNU
Emacs Manual' is a good example of a Texinfo file, as is this manual.

  To make a printed document, you process a Texinfo source file with the
TeX typesetting program (but the Texinfo language is very different 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 (*note
Hardcopy::).

  To output an Info file, process your Texinfo source with the
`makeinfo' utility or Emacs's `texinfo-format-buffer' command.  You can
install the result in your Info tree (*note Installing an Info File::).

  To output an HTML file, run `makeinfo --html' on your Texinfo source.
You can (for example) install the result on your web site.

  To output an XML file, run `makeinfo --xml' on your Texinfo source.
To output DocBook (a particular form of XML), run `makeinfo --docbook'.
If you want to convert from Docbook _to_ Texinfo, please see
`http://docbook2X.sourceforge.net/'.

  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.  But please do not write a separate translator
texi2foo for your favorite format foo!  That is the hard way to do the
job, and makes extra work in subsequent maintenance, since the Texinfo
language is continually being enhanced and updated.  Instead, the best
approach is modify `makeinfo' to generate the new format, as it does
now for Info, plain text, HTML, XML, and DocBook.

  TeX works with virtually all printers; Info works with virtually all
computer terminals; the HTML output works with virtually all web
browsers.  Thus Texinfo can be used by almost any computer user.

  A Texinfo source file is a plain ASCII file containing text and
"@-commands" (words preceded by an `@') that tell the typesetting and
formatting programs what to do.  You may edit a Texinfo file with any
text editor; but it is especially convenient to use GNU Emacs since
that editor has a special mode, called Texinfo mode, that provides
various Texinfo-related features.  (*Note Texinfo Mode::.)

  Before writing a Texinfo source file, you should learn about nodes,
menus, cross references, and the rest, for example by reading this
manual.

  You can use Texinfo to create both online help and printed manuals;
moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
is the official documentation format of the GNU project.  More
information is available at the GNU documentation web page
(http://www.gnu.org/doc/).

  From time to time, proposals are made to generate traditional Unix man
pages from Texinfo source.  This is not likely to ever be supported,
because man pages have a very strict conventional format.  Merely
enhancing `makeinfo' to output troff format would be insufficient.
Generating a good man page therefore requires a completely different
source than the typical Texinfo applications of writing a good user
tutorial 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 just write the man page directly.

  Man pages still have their place, and if you wish to support them, the
program `help2man' may be useful; it generates a traditional man page
from the `--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
`ftp://ftp.gnu.org/gnu/help2man/'.


File: texinfo,  Node: Info Files,  Next: Printed Books,  Prev: Using Texinfo,  Up: Overview

Info files
==========

  An Info file is a Texinfo file formatted so that the Info
documentation reading program can operate on it.  (`makeinfo' and
`texinfo-format-buffer' are two commands that convert a Texinfo file
into an Info file.)

  Info files are divided into pieces called "nodes", each of which
contains the discussion of one topic.  Each node has a name, and
contains both text for the user to read and pointers to other nodes,
which are identified by their names.  The Info program displays one node
at a time, and provides commands with which the user can move to other
related nodes.

  *note info: (info)Top, for more information about using Info.

  Each node of an Info file may have any number of child nodes that
describe subtopics of the node's topic.  The names of child nodes are
listed in a "menu" within the parent node; this allows you to use
certain Info commands to move to one of the child nodes.  Generally, an
Info file is organized like a book.  If a node is at the logical level
of a chapter, its child nodes are at the level of sections; likewise,
the child nodes of sections are at the level of subsections.

  All the children of any one parent are linked together in a
bidirectional chain of `Next' and `Previous' pointers.  The `Next'
pointer provides a link to the next section, and the `Previous' pointer
provides a link to the previous section.  This means that all the nodes
that are at the level of sections within a chapter are linked together.
Normally the order in this chain is the same as the order of the
children in the parent's menu.  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.(1) (*note Info Files-Footnote-1::)

  The book-like structuring of an Info file into nodes that correspond
to chapters, sections, and the like is a matter of convention, not a
requirement.  The `Up', `Previous', and `Next' pointers of a node can
point to any other nodes, and a menu can contain any other nodes.
Thus, the node structure can be any directed graph.  But it is usually
more comprehensible to follow a structure that corresponds to the
structure of chapters and sections in a printed book or report.

  In addition to menus and to `Next', `Previous', and `Up' pointers,
Info provides pointers of another kind, called references, that can be
sprinkled throughout the text.  This is usually the best way to
represent links that do not fit a hierarchical structure.

  Usually, you will design a document so that its nodes match the
structure of chapters and sections in the printed output.  But
occasionally there are times when this is not right for the material
being discussed.  Therefore, Texinfo uses separate commands to specify
the node structure for the Info file and the section structure for the
printed output.

  Generally, you enter an Info file through a node that by convention is
named `Top'.  This node normally contains just a brief summary of the
file's purpose, and a large menu through which the rest of the file is
reached.  From this node, you can either traverse the file
systematically by going from node to node, or you can go to a specific
node listed in the main menu, or you can search the index menus and then
go directly to the node that has the information you want.
Alternatively, with the standalone Info program, you can specify
specific menu items on the command line (*note Top: (info)Top.).

  If you want to read through an Info file in sequence, as if it were a
printed manual, you can hit <SPC> repeatedly, or you get the whole file
with the advanced Info command `g *'.  (*note Advanced Info commands:
(info)Expert.)

  The `dir' file in the `info' directory serves as the departure point
for the whole Info system.  From it, you can reach the `Top' nodes of
each of the documents in a complete Info system.

  If you wish to refer to an Info file in a URI, you can use the
(unofficial) syntax exemplified in the following.  This works with
Emacs/W3, for example:
     info:///usr/info/emacs#Dissociated%20Press
     info:emacs#Dissociated%20Press
     info://localhost/usr/info/emacs#Dissociated%20Press

  The `info' program itself does not follow URI's of any kind.


File: texinfo,  Node: Info Files-Footnotes,  Up: Info Files

  (1) In some documents, the first child has no `Previous' pointer.
Occasionally, the last child has the node name of the next following
higher level node as its `Next' pointer.


File: texinfo,  Node: Printed Books,  Next: Formatting Commands,  Prev: Info Files,  Up: Overview

Printed Books
=============

  A Texinfo file can be formatted and typeset as a printed book or
manual.  To do this, you need TeX, a powerful, sophisticated typesetting
program written by Donald Knuth.(1) (*note Printed Books-Footnote-1::)

  A Texinfo-based book is similar to any other typeset, printed work: it
can have a title page, copyright page, table of contents, and preface,
as well as chapters, numbered or unnumbered sections and subsections,
page headers, cross references, footnotes, and indices.

  You can use Texinfo to write a book without ever having the intention
of converting it into online information.  You can use Texinfo for
writing a printed novel, and even to write a printed memo, although
this latter application is not recommended since electronic mail is so
much easier.

  TeX is a general purpose typesetting program.  Texinfo provides a
file `texinfo.tex' that contains information (definitions or "macros")
that TeX uses when it typesets a Texinfo file.  (`texinfo.tex' tells
TeX how to convert the Texinfo @-commands to TeX commands, which TeX
can then process to create the typeset document.)  `texinfo.tex'
contains the specifications for printing a document.  You can get the
latest version of `texinfo.tex' from
`ftp://ftp.gnu.org/gnu/texinfo.tex'.

  In the United States, documents are most often printed on 8.5 inch by
11 inch pages (216mm by 280mm); this is the default size.  But you can
also print for 7 inch by 9.25 inch pages (178mm by 235mm, the
`@smallbook' size; or on A4 or A5 size paper (`@afourpaper',
`@afivepaper').  (*Note Printing "Small" Books: smallbook.  Also, see
*Note Printing on A4 Paper: A4 Paper.)

  By changing the parameters in `texinfo.tex', you can change the size
of the printed document.  In addition, you can change the style in
which the printed document is formatted; for example, you can change the
sizes and fonts used, the amount of indentation for each paragraph, the
degree to which words are hyphenated, and the like.  By changing the
specifications, you can make a book look dignified, old and serious, or
light-hearted, young and cheery.

  TeX is freely distributable.  It is written in a superset of Pascal
called WEB and can be compiled either in Pascal or (by using a
conversion program that comes with the TeX distribution) in C.  (*Note
TeX Mode: (emacs)TeX Mode, for information about TeX.)

  TeX is very powerful and has a great many features.  Because a
Texinfo file must be able to present information both on a
character-only terminal in Info form and in a typeset book, the
formatting commands that Texinfo supports are necessarily limited.

  To get a copy of TeX, see *Note How to Obtain TeX: Obtaining TeX.


File: texinfo,  Node: Printed Books-Footnotes,  Up: Printed Books

  (1) You can also use the `texi2roff' (ftp://tug.org/texi2roff.tar.gz)
program if you do not have TeX; since Texinfo is designed for use with
TeX, `texi2roff' is not described here.  `texi2roff' is not part of the
standard GNU distribution and is not maintained or up-to-date with all
the Texinfo features described in this manual.


File: texinfo,  Node: Formatting Commands,  Next: Conventions,  Prev: Printed Books,  Up: Overview

@-commands
==========

  In a Texinfo file, the commands that tell TeX how to typeset the
printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
create an Info file are preceded by `@'; they are called "@-commands".
For example, `@node' is the command to indicate a node and `@chapter'
is the command to indicate the start of a chapter.

     *Please note:* All the @-commands, with the exception of the
     `@TeX{}' command, must be written entirely in lower case.

  The Texinfo @-commands are a strictly limited set of constructs.  The
strict limits make it possible for Texinfo files to be understood both
by TeX and by the code that converts them into Info files.  You can
display Info files on any terminal that displays alphabetic and numeric
characters.  Similarly, you can print the output generated by TeX on a
wide variety of printers.

  Depending on what they do or what arguments(1) (*note Formatting
Commands-Footnote-1::) they take, you need to write @-commands on lines
of their own or as part of sentences:

   * Write a command such as `@noindent' at the beginning of a line as
     the only text on the line.  (`@noindent' prevents the beginning of
     the next line from being indented as the beginning of a paragraph.)

   * Write a command such as `@chapter' at the beginning of a line
     followed by the command's arguments, in this case the chapter
     title, on the rest of the line.  (`@chapter' creates chapter
     titles.)

   * Write a command such as `@dots{}' wherever you wish but usually
     within a sentence. (`@dots{}' creates dots ...)

   * Write a command such as `@code{SAMPLE-CODE}' wherever you wish
     (but usually within a sentence) with its argument, SAMPLE-CODE in
     this example, between the braces.  (`@code' marks text as being
     code.)

   * Write a command such as `@example' on a line of its own; write the
     body-text on following lines; and write the matching `@end'
     command, `@end example' in this case, at the on a line of its own
     after the body-text. (`@example' ... `@end example' indents and
     typesets body-text as an example.)  It's usually ok to indent
     environment commands like this, but in complicated and
     hard-to-define circumstances the extra spaces cause extra space to
     appear in the output, so beware.

As a general rule, a command requires braces if it mingles among other
text; but it does not need braces if it starts a line of its own.  The
non-alphabetic commands, such as `@:', are exceptions to the rule; they
do not need braces.

  As you gain experience with Texinfo, you will rapidly learn how to
write the different commands: the different ways to write commands make
it easier to write and read Texinfo files than if all commands followed
exactly the same syntax.  (For details about @-command syntax, see
*Note @-Command Syntax: Command Syntax.)


File: texinfo,  Node: Formatting Commands-Footnotes,  Up: Formatting Commands

  (1) The word "argument" comes from the way it is used in mathematics
and does not refer to a dispute between two people; it refers to the
information presented to the command.  According to the `Oxford English
Dictionary', the word derives from the Latin for "to make clear,
prove"; thus it came to mean `the evidence offered as proof', which is
to say, `the information offered', which led to its mathematical
meaning.  In its other thread of derivation, the word came to mean `to
assert in a manner against which others may make counter assertions',
which led to the meaning of `argument' as a dispute.


File: texinfo,  Node: Conventions,  Next: Comments,  Prev: Formatting Commands,  Up: Overview

General Syntactic Conventions
=============================

  This section describes the general conventions used in all Texinfo
documents.

   * All printable ASCII characters except `@', `{' and `}' can appear
     in a Texinfo file and stand for themselves.  `@' is the escape
     character which introduces commands, while `{' and `}' are used to
     surround arguments to certain commands.  To put one of these
     special characters into the document, put an `@' character in
     front of it, like this: `@@', `@{', and `@}'.

   * It is customary in TeX to use doubled single-quote characters to
     begin and end quotations: ``...''.  This convention should be
     followed in Texinfo files.  TeX converts two single quotes to
     left- and right-hand doubled quotation marks, and Info converts
     doubled single-quote characters to ASCII double-quotes: ``...''
     becomes "...".

   * Use three hyphens in a row, `---', for a dash--like this.  In TeX,
     a single or double hyphen produces a printed dash that is shorter
     than the usual typeset dash. Info reduces three hyphens to two for
     display on the screen.

   * To prevent a paragraph from being indented in the printed manual,
     put the command `@noindent' on a line by itself before the
     paragraph.

   * If you mark off a region of the Texinfo file with the `@iftex' and
     `@end iftex' commands, that region will appear only in the printed
     copy; in that region, you can use certain commands borrowed from
     plain TeX that you cannot use in Info.  Conversely, text
     surrounded by `@ifnottex' and `@end ifnottex' will appear in all
     output formats _except_ TeX.

     Each of the other output formats (`html', `info', `plaintext')
     have an analogous pair of commands.  *Note Conditionals::.

     *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.  Consequently, TeX treats tabs like single spaces,
     and that is not what they look like.  Furthermore, `makeinfo' does
     nothing special with tabs, and thus a tab character in your input
     file may appear differently in the output, for example, in
     indented text.

     To avoid this problem, Texinfo mode causes GNU Emacs to insert
     multiple spaces when you press the <TAB> key.

     Also, you can run `untabify' in Emacs to convert tabs in a region
     to multiple spaces.


File: texinfo,  Node: Comments,  Next: Minimum,  Prev: Conventions,  Up: Overview

Comments
========

  You can write comments in a Texinfo file that will not appear in
either the Info file or the printed manual by using the `@comment'
command (which may be abbreviated to `@c').  Such comments are for the
person who revises the Texinfo file.  All the text on a line that
follows either `@comment' or `@c' is a comment; the rest of the line
does not appear in either the Info file or the printed manual.

  Often, you can write the `@comment' or `@c' in the middle of a line,
and only the text that follows after the `@comment' or `@c' command
does not appear; but some commands, such as `@settitle' and
`@setfilename', work on a whole line.  You cannot use `@comment' or
`@c' in a line beginning with such a command.

  You can write long stretches of text that will not appear in either
the Info file or the printed manual by using the `@ignore' and `@end
ignore' commands.  Write each of these commands on a line of its own,
starting each command at the beginning of the line.  Text between these
two commands does not appear in the processed output.  You can use
`@ignore' and `@end ignore' for writing comments.

  Text enclosed by `@ignore' or by failing `@ifset' or `@ifclear'
conditions is ignored in the sense that it will not contribute to the
formatted output.  However, TeX and makeinfo must still parse the
ignored text, in order to understand when to _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.

