Texinfo ¶

1.1 Reporting Bugs ¶

We welcome bug reports and suggestions for any aspect of the Texinfo system: programs, documentation, installation, etc. Please email them to bug-texinfo@gnu.org. You can get the latest version of Texinfo via its home page, http://www.gnu.org/software/texinfo.

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.
• The contents of any input files necessary to reproduce the bug.
• Precisely how you ran any program(s) involved.
• A description of the problem and samples of any erroneous output.
• Hardware and operating system names and versions.
• 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.

It is critical to send an actual input file that reproduces the problem.

Any problems with the Info reader in Emacs should be reported to the Emacs developers: see Bugs in The GNU Emacs Manual.

Patches are welcome; if possible, please make them with ‘diff -c’, ‘diff -u’ (see Comparing and Merging Files), or ‘git diff’ and include ChangeLog entries (see Change Log in GNU Coding Standards), and follow the existing coding style.

1.2 Output Formats ¶

Here is an overview of the output formats currently supported by Texinfo.

Info ¶

(Generated via texi2any.) Info format is mostly a plain text transliteration of the Texinfo source. It adds a few control characters to provide navigational information for cross-references, indices, and so on. The Emacs Info subsystem (see Info), and the standalone info program (see GNU Info), among others, can read these files. See Info Files, and Creating and Installing Info Files.

Plain text ¶

(Generated via texi2any --plaintext.) This is almost the same as Info output with the navigational control characters are omitted.

HTML ¶

(Generated via texi2any --html.) HTML, standing for Hyper Text Markup Language, is the language for writing documents on the World Wide Web. Web browsers can render this language online. There are many versions of HTML, both different standards and browser-specific variations. texi2any uses a subset of the language that can be interpreted by any common browser, intentionally not using many newer or less widely-supported tags. Although the native output is thus rather plain, it can be customized at various levels, if desired. See Generating HTML.

EPUB 3 ¶

(Generated via texi2any --epub3.) EPUB is a format designed for reading electronic books on portable devices. It is a derivative of HTML. The format was developed by the International Digital Publishing Forum (IDPF), which is now part of the World Wide Web Consortium (W3C). The latest major revision, EPUB 3, dates from 2011.

DVI ¶

(Generated via texi2dvi.) The DeVIce Independent binary format is output by the TeX typesetting program (http://tug.org). This is then read by a DVI ‘driver’, which knows the actual device-specific commands that can be viewed or printed, notably Dvips for translation to PostScript (see Dvips) and Xdvi for viewing on an X display (http://sourceforge.net/projects/xdvi/). See Formatting and Printing with TeX. (Be aware that the Texinfo language is very different from TeX’s usual languages: plain TeX, LaTeX, ConTeXt, etc.)

PostScript ¶

(Generated via texi2dvi --ps.) PostScript is a page description language that became widely used around 1985 and is still used today. https://en.wikipedia.org/wiki/PostScript gives a basic description and more preferences. By default, Texinfo uses the dvips program to convert TeX’s DVI output to PostScript. See Dvips.

PDF ¶

(Generated via texi2dvi --pdf or texi2pdf.) This format was developed by Adobe Systems for portable document interchange, based on their previous PostScript language. It can represent the exact appearance of a document, including fonts and graphics, and supporting arbitrary scaling. It is intended to be platform-independent and easily viewable, among other design goals; https://en.wikipedia.org/wiki/Portable_Document_Format and http://tug.org/TUGboat/tb22-3/tb72beebe-pdf.pdf have some background. By default, Texinfo uses the pdftex program, an extension of TeX, to output PDF; see http://tug.org/applications/pdftex. See PDF Output.

LaTeX ¶

(Generated via texi2any --latex.) This is a typesetting system built on top of TeX. It was originally released by Leslie Lamport in 1984. LaTeX adds more definitions to those of TeX and has a wide range of packages built on it. LaTeX is ubiquitous in academic literature. The current version of LaTeX is under active development; more information is available online at https://www.latex-project.org/.

The LaTeX output can be further processed into DVI, PostScript, or PDF. In theory, the LaTeX output should allow for much more customizability of the output than would be possible with the plain TeX implementation of Texinfo.

DocBook ¶

(Generated via texi2any --docbook.) This is an XML-based format, primarily for technical documentation. It therefore bears some resemblance, in broad outline, to Texinfo. See http://www.docbook.org. Various converters from DocBook to Texinfo have also been developed; see the Texinfo web pages.

XML ¶

(Generated via texi2any --xml.) The texi2any XML output, unlike all the other output formats, is a transliteration of the Texinfo source, rather than finished output. Texinfo XML files cannot be viewed in web browsers or other programs.

XML is a generic syntax specification usable for any sort of content. (A reference is at http://www.w3.org/XML.) The purpose of the Texinfo XML output is to allow further processing by XML tools. The output syntax is defined in an XML DTD, which is contained in a file texinfo.dtd included in the Texinfo source distribution.

The Texinfo source distribution includes a utility script txixml2texi to do a backward transformation to recreate the original Texinfo content (except for Texinfo macros and conditionals).

1.3 Info Files ¶

As mentioned above, Info format is mostly a plain text transliteration of the Texinfo source, with the addition of a few control characters to separate nodes and provide navigational information, so that Info-reading programs can operate on it.

Info files are nearly always created by processing a Texinfo source document. texi2any, also known as makeinfo, is the principal command that converts a Texinfo file into an Info file; see texi2any: The Translator for Texinfo.

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 (see Info).

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 *. (See Advanced Info commands in Info.)

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 via a URI, you can use the (unofficial) syntax exemplified by the following. This works with Emacs/W3, for example:

info:emacs#Dissociated%20Press
info:///usr/info/emacs#Dissociated%20Press
info://localhost/usr/info/emacs#Dissociated%20Press

The info program itself does not follow URIs of any kind.

1.4 Printed Books ¶

A Texinfo file can be formatted and typeset as a printed book or manual. To do this, you need TeX, a sophisticated typesetting program written by Donald Knuth of Stanford University. It is not part of the Texinfo distribution.

Texinfo provides a file texinfo.tex that contains the definitions that TeX uses when it typesets a Texinfo file. You can get the latest version of texinfo.tex from the Texinfo home page, http://www.gnu.org/software/texinfo/.

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.

TeX is very powerful and has a great many features. However, 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.

See Formatting and Printing with TeX, for more information on processing a manual with TeX.

1.5 Adding Output Formats ¶

The output formats in the previous sections handle a wide variety of usage, but of course there is always room for more.

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 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 tp/Texinfo/Convert/Converter.pm is a good place to start (see Texinfo::Convert::Converter in Texinfo modules documentation). See texi2any: The Translator for Texinfo.

Another viable approach is use the Texinfo XML output from texi2any as your input. This XML is an essentially complete representation of the input, but without the Texinfo syntax and option peculiarities, as described above.

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 texi2any give correct results with your new program.

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.

As an alternative way to support man pages, you may find the program help2man to be useful. It generates a traditional man page from the ‘--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 http://www.gnu.org/software/help2man.

1.6 History ¶

Richard M. Stallman invented the Texinfo format, wrote the initial processors, and created Edition 1.0 of this manual. Robert J. 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. Karl Berry continued maintenance from Texinfo 3.8 (manual edition 2.22), and Gavin Smith has continued maintenance since Texinfo 6.0.

Beginnings ¶

Richard Stallman included an on-line, hypertext help system called Info in the original implementation of Emacs (in 1975/6). Stallman had been inspired after seeing a presentation a couple of years earlier on the “NLS” hypertext system of Douglas Engelbart.

In another development, in the 1970’s at CMU, Brian Reid developed a program and format named Scribe to mark up documents for printing. It used the @ 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.

Meanwhile, people at MIT developed another format called Bolio. Richard Stallman (RMS) worked on converting Bolio to use TeX as its typesetting language, resulting in BoTeX. The earliest BoTeX version seems to have been 0.02 on October 31, 1984.

BoTeX could only be used as a markup language for documents to be printed, not for online documents. RMS combined BoTeX and Info to create Texinfo, a mark-up language for text that is intended to be read both online and as printed hard copy.

The original translator to create Info was written (primarily by RMS and Bob Chassell) in Emacs Lisp, namely the texinfo-format-buffer and other functions. In the early 1990s, Brian Fox reimplemented the conversion program in C, now called makeinfo, as well as the standalone info program.

Reimplementing in Perl ¶

In 2012, the C makeinfo was itself replaced by a Perl implementation generically called texi2any. This version supports the same level of output customization as texi2html, an independent program originally written by Lionel Cons, later with substantial work by many others. The many additional features needed to make texi2html a replacement for makeinfo were implemented by Patrice Dumas. The first, never-released version of texi2any was based on the texi2html code.

That implementation, however, was abandoned in favor of the current program (also written by Patrice Dumas), which parses the Texinfo input into a tree for processing. It inherited the design of customization and other features from texi2html (for more on texi2html compatibility, see texi2html: Ancestor of texi2any). However, texi2any is a full reimplementation: it constructs a tree-based representation of the input document for all back-ends to work from.

The new Perl program is much slower than the old C program. The speed gap has partially closed since first release, 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 makeinfo to extend to different output styles, back-end output formats, and all other customizations. In more detail:

• HTML customization. Many GNU and other free software packages had been happily using the HTML customization features in texi2html 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 texi2html to a C program would have been an enormous effort.
• Unicode, and multilingual support generally, especially of east Asian languages. At that time, doing it in C would have been tantamount to rewriting the entire program. Since then, the parser and bits of converter back-ends have been rewritten in C, but the converter back-ends are still mostly in Perl which has good multilingual support built in.
• Additional back-ends. The 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, the new 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, …); this change made them much more feasible to implement. Which leads to the last item:
• Making contributions easier. In general, due to the cleaner structure, the separate parser/back-ends implementation should be considerably easier than the former C makeinfo implementation for anyone to read and contribute to, with the resulting obvious benefits. After ten years, contributed back-ends were yet to happen, but it is still believed that this structure could in theory lend better to contributions.

texi2any is intended to be a reference implementation that defines parts of the language not fully specified by the manual. Without such a reference, alternative implementations would be very likely to have subtle, or not-so-subtle, differences in behavior, and thus Texinfo documents would become dependent on the processor. It is also important to have consistent command-line options for all processors. Extensive tests of the language and processor were developed at the same time as texi2any; we encourage anyone thinking of writing a program to parse Texinfo input to make use of these tests.

With the release of texi2any as the reference implementation, development of both the C implementation of makeinfo and texi2html has been halted. Going forward, we ask authors of Texinfo documents to use only texi2any.

2.1 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 ‘@}’.
• In a Texinfo file, the commands you write to describe the contents of the manual are preceded by an ‘@’ character; they are called @-commands. (The ‘@’ in Texinfo has the same meaning that ‘\’ has in plain TeX.)

  Depending on what they do or what arguments they take, you need to write @-commands on lines of their own, or as part of sentences. As a general rule, a command requires braces if it mingles among other text; but it does not need braces if it is on a line of its own. For more details of Texinfo command syntax, see @-Command Syntax.

• Whitespace following an @-command name is optional and (usually) ignored if present. The exceptions are contexts when whitespace is significant, e.g., an @example environment.
• Texinfo supports the usual quotation marks used in English and in other languages; see Inserting Quotation Marks.
• Use three hyphens in a row, ‘---’, to produce a long dash—like this (called an em dash), used for punctuation in sentences. Use two hyphens, ‘--’, to produce a medium dash (called an en dash), used primarily for numeric ranges, as in “June 25–26”. Use a single hyphen, ‘-’, to produce a standard hyphen used in compound words. For display on the screen, Info reduces three hyphens to two and two hyphens to one (not transitively!). Of course, any number of hyphens in the source remain as they are in literal contexts, such as @code and @example.
• Whitespace. Texinfo files are plain text files composed of lines terminated by the usual newline character (line feed). Texinfo processors read input one line at a time. Paragraphs are terminated by an empty line or a line containing only spaces. A sequence of several spaces in text is usually treated the same as a single space (except in verbatim modes).

  Form feed (CTRL-l) characters in normal text end any open paragraph. Other ASCII whitespace (tab, carriage return) may be treated the same as space characters, although the results may differ depending on output format. Hence, there is not much point in using these in documents. Non-ASCII spaces, such as Unicode “em space”, are not recognized as whitespace at all and will be treated as regular, non-whitespace characters.

  However, in verbatim modes, for example in code samples, tab characters may produce the correct formatting in the output.

2.2 Comments ¶

You can write comments in a Texinfo file by using the @comment command, which may be abbreviated to @c. Such comments are for a person looking at the Texinfo source 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 the visible output. (To be precise, the character after the @c or @comment must be something other than a dash or alphanumeric, or it will be taken as part of the command.)

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, work on a whole line. You cannot use @comment or @c within a line beginning with such a command.

In cases of nested command invocations, complicated macro definitions, etc., @c and @comment may provoke an error when processing with TeX. Therefore, you can also use the DEL character (ASCII 127 decimal, 0x7f hex, 0177 octal) as a true TeX comment character (catcode 14, in TeX internals). Everything on the line after the DEL will be ignored and the next line will be merged.

You can also have long stretches of text ignored by the Texinfo processors with 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. (For some caveats regarding nesting of such commands, see Conditional Nesting.)

2.3 What a Texinfo File Must Have ¶

By convention, the name of a Texinfo file ends with one of the extensions .texi, .texinfo, .txi, or .tex. Using .tex is discouraged as this extension is already used by TeX and LaTeX input files. The most common and recommended extension is .texi. The name of a Texinfo file should only contain ASCII characters.

The output name is based on the input file name, in the default case. First, any of the extensions .texi, .tex, .txi, or .texinfo is removed from the input file name; then, the output format specific extension is added—.html when generating HTML, .info when generating Info, etc. The output name should only contain ASCII characters¹.

In order to be made into a printed manual, a Texinfo file must begin with a line like this:

\input texinfo

The contents of the file follow this beginning, and then you must end the Texinfo source with a line like this:

@bye

The @bye line at the end of the file on a line of its own tells TeX 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.

Furthermore, you will usually provide a Texinfo file with a title, 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 one line at the beginning and the one line at the end.

Without additional information, the input and output encodings are assumed to be UTF-8, an universal codeset compatible with 7-bit ASCII.

2.4 Short Sample ¶

Here is a short sample Texinfo file.

\input texinfo
@settitle Sample Manual 1.0

@copying
This is a short example of a complete Texinfo file.

Copyright @copyright{} 2016 Free Software Foundation, Inc.
@end copying

@titlepage
@title Sample Title
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@node Top
@top GNU Sample

This manual is for GNU Sample
(version @value{VERSION}, @value{UPDATED}).

@menu
* First Chapter::    The first chapter is the
                      only chapter in this sample.
* Index::            Complete index.
@end menu


@node First Chapter
@chapter First Chapter

@cindex chapter, first
This is the first chapter.
@cindex index entry, another

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate

@node First Section
@section First Section

First section of first chapter.


@node Second Section
@section Second Section

Second section of first chapter.


@node Index
@unnumbered Index

@printindex cp

@bye

2.5 Texinfo File Header ¶

Texinfo files start with the line:

\input texinfo

The ‘\input texinfo’ line tells TeX to use the texinfo.tex file, which tells TeX how to translate the Texinfo @-commands into TeX typesetting commands. (Note the use of the backslash, ‘\’; this is correct for TeX.)

It makes sense to include any command that affects document formatting as a whole in the header. The @settitle line is usually present at the beginning of the header:

@settitle Sample Manual 1.0

The @settitle line specifies a title for the page headers (or footers) of the printed manual, and the default title and document description for the ‘<head>’ in HTML. @synindex (see @synindex: Combining Indices), for instance, is another command often included in the header.

The start of the Texinfo file up to the first content that is output as part of the main body of the document is the preamble. It includes the header, Document Permissions and Title and Copyright Pages specification. It is important for the LaTeX output format as the end of preamble is where the \begin{document} line is output. In other output formats it may be used to determine how some special output is formatted, for example @copying: Declare Copying Permissions output as a comment at the beginning of output files, or the language used in file headers.

• The First Line of a Texinfo File
• @setfilename: Set the Output File Name
• @settitle: Set the Document Title
• Preamble
• Start and End of Header for Emacs

\input texinfo

\input texinfo   @c -*-texinfo-*-

@setfilename info-file-name

@settitle title

\input texinfo
@documentlanguage fr

@copying
The copying information @error{} some text
@end copying

@documentlanguage pt

Text ending the preamble

@documentlanguage de

@node Top

@c %**start of header

@c %**end of header

2.6 Directory Category ¶

Use the @dircategory command to specify a category for the manual. Here are a few examples of category names:

Basics
Text creation and manipulation
Archiving
Compression
Database
Editors
Emacs
Email
Graphics
Localization
Network applications
Printing
Science
Software development
Software libraries
Version control

@dircategory commands are usually followed by a @direntry blocks, which are used by install-info. See Installing Info Directory Files, for details.

The first @dircategory command in a manual is the category for the entire manual. Subsequent uses of @dircategory set the category for following @direntry blocks only.

2.7 Document Permissions ¶

This segment describes the document and contains the copyright notice and copying permissions. This is done with the @copying command. A real manual includes more text here, according to the license under which it is distributed.

@copying
This is a short example of a complete Texinfo file, version 1.0.

Copyright @copyright{} 2016 Free Software Foundation, Inc.
@end copying

The copyright notice and copying permissions for a document need to appear in several places in the various Texinfo output formats. Therefore, Texinfo provides a command (@copying) to declare this text once, and another command (@insertcopying) to insert the text at appropriate points.

If the document is a software manual, the software is typically under a different license—for GNU and many other free software packages, software is usually released under the GNU GPL, and manuals are released under the GNU FDL. It is helpful to state the license of the software of the manual, but giving the complete text of the software license is not necessarily required.

• @copying: Declare Copying Permissions
• @insertcopying: Include Permissions Text

@copying
This manual is for program (version version, updated
date), which ...

Copyright @copyright{} years copyright-owner.

@quotation
Permission is granted to ...
@end quotation
@end copying

Copyright © years copyright-owner.

@insertcopying

2.8 Title and Copyright Pages ¶

In hard copy output, the manual’s name and author are usually printed on a title page. Copyright information is usually printed on the back (verso) of the title page. This segment must be enclosed between @titlepage and @end titlepage commands:

@titlepage
@title Sample Title

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

We use the @insertcopying command to include the permission text from the previous section, instead of writing it out again.

The title and copyright pages appear in printed manuals, but not in most other output formats. In HTML, the best way to get a title page similar to printed manuals is to set the NO_TOP_NODE_OUTPUT customization variable (see NO_TOP_NODE_OUTPUT).

• @titlepage
• @title, @subtitle, and @author
• @titlefont, @center, and @sp
• Copyright Page
• Heading Generation

@title This Long Title@inlinefmt{tex,@*} Is Broken in @TeX{}

@author by Jane Smith and John Doe

@author Jane Smith
@author John Doe

@titlepage
@title name-of-manual-when-printed
@subtitle subtitle-if-any
@subtitle second-subtitle
@author author
@page
...
@end titlepage

@titlefont{Texinfo}

@center @titlefont{Texinfo}

@sp 2

@titlepage
@sp 10
@center @titlefont{name-of-manual-when-printed}
@sp 2
@center subtitle-if-any
@sp 2
@center author
...
@end titlepage

@vskip 0pt plus 1filll

@insertcopying

@titlepage
...
@page
@vskip 0pt plus 1filll
@insertcopying

Published by ...

Cover art by ...
@end titlepage

@ifplaintext
@insertcopying
@end ifplaintext

2.9 Generating a Table of Contents ¶

The @chapter, @section, and other structuring commands (see Chapter Structuring) supply the information to make up a table of contents, but they do not cause an actual table to appear in the manual. To do this, you must use the @contents and/or @summarycontents command(s).

@contents

Generates a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. Headings generated by @majorheading, @chapheading, and the other @…heading commands do not appear in the table of contents (see Structuring Command Types).

@shortcontents

@summarycontents

(@summarycontents is a synonym for @shortcontents.)

Generates a short or summary table of contents that lists only the chapters, appendices, and unnumbered chapters. Sections, subsections and subsubsections are omitted. Only a long manual needs a short table of contents in addition to the full table of contents.

Both contents commands should be written on a line by themselves, and placed near the beginning of the file, after the @end titlepage (see @titlepage), before any sectioning command. The contents commands automatically generate a chapter-like heading at the top of the first table of contents page, so don’t include any sectioning command such as @unnumbered before them.

Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the contents commands. But the contents are included in plain text output and in other output formats, such as HTML.

In HTML output, the links in the short table of contents point to corresponding entries in the full table of contents rather than the text of the document. The links in the full table of contents point to the main text of the document.

@shortcontents is not implemented for LaTeX output.

2.10 The ‘Top’ Node and Master Menu ¶

The ‘Top’ node is the node in which a reader enters an Info manual. As such, it should contain a very brief description of the manual (including the version number). The contents of the ‘Top’ node do not appear in printed output nor in DocBook output.

It is conventional to write a @top sectioning command line containing the title of the document immediately after the @node Top line (see The @top Sectioning Command).

We repeat the short description from the beginning of the ‘@copying’ text, but there’s no need to repeat the copyright information, so we don’t use ‘@insertcopying’ here.

The ‘Top’ node contains a top-level menu listing the chapters, and possibly a detailed menu listing all the nodes in the entire document.

@node Top
@top Short Sample

This is a short sample Texinfo file.

@menu
* First Chapter::    The first chapter is the
                       only chapter in this sample.
* Index::            Complete index.
@end menu

• Parts of a Master Menu

@menu
* Copying Conditions::  Your rights.
* Overview::            Texinfo in brief.
...

* Command and Variable Index::
* General Index::

@detailmenu
--- The Detailed Node Listing ---

Overview of Texinfo

* Reporting Bugs:: ...
...

Beginning a Texinfo File

* Sample Beginning:: ...
...
@end detailmenu
@end menu

2.11 The Body of the Document ¶

The body segment contains all the text of the document. A manual is divided into one or more nodes (see Nodes). The example illustrates a chapter made of three nodes, one for introductory material in the chapter, and two sections. The introductory material contains an enumerated list.

@node First Chapter
@chapter First Chapter

@cindex chapter, first
This is the first chapter.
@cindex index entry, another

Here is a numbered list.

@enumerate
@item
This is the first item.

@item
This is the second item.
@end enumerate


@node First Section
@section First Section

First section of first chapter.


@node Second Section
@section Second Section

Second section of first chapter.

In the Info output, the ‘First Chapter’ node will contain a menu listing the two sections in the chapter. Similarly, when this node is output in its own HTML file, it will contain a table of contents for the chapter.

Here is what the contents of this chapter will look like:

1. First Chapter ¶

This is the first chapter.

Here is a numbered list.

1. This is the first item.
2. This is the second item.

1.1 First Section ¶

First section of first chapter.

1.2 Second Section ¶

Second section of first chapter.

(In the Info and HTML output, the chapter would also be split into nodes.)

2.12 Ending a Texinfo File ¶

The end of a Texinfo file should include commands to create indices (see Printing Indices and Menus), and the @bye command to mark the last line to be processed. For example:

@node Index
@unnumbered Index

@printindex cp

@bye

A @bye command terminates Texinfo processing. It should be on a line by itself. Anything following @bye is completely ignored.

3.1 Writing a @node Line ¶

Write @node at the beginning of a line followed by the name of the node, like this:

@node node-name

After you have inserted a @node line, you should immediately write the @-command for the associated chapter or section (if any) and insert its name.

You may optionally follow the node name argument to @node with up to three optional arguments on the rest of the same line, separating the arguments with commas. These are the names of the ‘Next’, ‘Previous’, and ‘Up’ pointers, in that order. Hence, the template for a fully-written-out node line with ‘Next’, ‘Previous’, and ‘Up’ pointers looks like this:

@node node-name, next, previous, up

The node-name argument must be present, but the others are optional. If you wish to specify some but not others, just insert commas as needed, as in: ‘@node mynode,,,uppernode’. Any spaces before or after each name on the @node line are ignored. However, if your Texinfo document is hierarchically organized, as virtually all are, we recommend leaving off all the pointers and letting texi2any determine them.

The texi2any program automatically determines node pointers for a hierarchically organized document. For it to do this, each @node command should be followed immediately by a sectioning command such as @chapter or @section (except that comment lines may intervene). Finally, you must follow the ‘Top’ @node line with a line beginning with @top to mark the top-level node in the file. See The @top Sectioning Command.

Even when you explicitly specify all pointers, you cannot write the nodes in the Texinfo source file in an arbitrary order. You must write the nodes in the order you wish them to appear in the output. For Info format one can imagine that the order may not matter, but it matters for the other formats.

In most cases, you will want to take advantage of the pointer creation feature, and not redundantly specify node pointers that the programs can determine. However, Texinfo documents are not required to be organized hierarchically or in fact to contain sectioning commands at all (for example, if you never intend the document to be printed), so node pointers may still be specified explicitly, in full generality.

If you are using GNU Emacs, and want explicit pointers, you can use the update node commands provided by Texinfo mode to insert the names of the pointers. (See Updating Nodes and Menus.)

Alternatively, you can insert the ‘Next’, ‘Previous’, and ‘Up’ pointers yourself. If you do this in Emacs, you may find it helpful to use the Texinfo mode keyboard command C-c C-c n. This command inserts ‘@node’ and a comment line listing the names of the pointers in their proper order. The comment line helps you keep track of which arguments are for which pointers.

3.2 Choosing Node Names ¶

The name of a node identifies the node. For all the details of node names, see @node Line Requirements).

Here are some suggestions for node names:

• Try to pick node names that are informative but short.

  In the Info file, the file name, node name, and pointer names are all inserted on one line, which may run into the right edge of the window. (This does not cause a problem with Info, but is ugly.)

• Try to pick node names that differ from each other near the beginnings of their names. This way, it is easy to use automatic name completion in Info.
• Conventionally, node names are capitalized in the same way as section and chapter titles. In this manual, initial and significant words are capitalized; others are not. In other manuals, just initial words and proper nouns are capitalized. Either way is fine; we recommend just being consistent.
• In HTML output, any characters in the node name other than plain ASCII letters, numbers or spaces will be changed in the file name. (See HTML Cross-reference Node Name Expansion.) This can make the URLs for the pages in your manual less user-friendly; for example, in this manual the ‘@dots’ node is output as __0040dots.html.

Because node names are used in cross-references, it is not desirable to casually change them once published. When you delete or rename a node, it is usually a good idea to define an @anchor with the old name. That way, references from other manuals, from mail archives, and so on are not invalidated. See @anchor: Defining Arbitrary Cross-reference Targets.

The pointers from a given node enable you to reach other nodes and consist simply of the names of those nodes.

Normally, a node’s ‘Up’ pointer contains the name of the node whose menu mentions that node. The node’s ‘Next’ pointer contains the name of the node that follows the present node in that menu and its ‘Previous’ pointer contains the name of the node that precedes it in that menu. When a node’s ‘Previous’ node is the same as its ‘Up’ node, both pointers name the same node.

Usually, the first node of a Texinfo file is the ‘Top’ node, and its ‘Up’ pointer points to the dir file, which contains the main menu for all of Info.

3.3 @node Line Requirements ¶

Names used with @node have several requirements:

• All the node names in a single Texinfo file must be unique.

  This means, for example, that if you end every chapter with a summary, you must name each summary node differently. You cannot just call them all “Summary”. You may, however, duplicate the titles of chapters, sections, and the like. Thus you can end each chapter with a section called “Summary”, so long as the node names for those sections are all different.

  Node names, anchor names (see @anchor: Defining Arbitrary Cross-reference Targets), and float labels (see @float [type][,label]: Floating Material) must all be unique.

• Node names can contain @-commands³. For example, using @TeX{} in a node name results in the TeX logo being output, as it would be in normal text. Cross-references should use @TeX{} just as the node name does.

  Some commands do not make sense in node names; for instance, environments (e.g., @quotation), commands that read a whole line as their argument (e.g., @sp), and plenty of others. For the complete list of commands that are allowed, and their expansion for HTML identifiers and file names, see HTML Cross-reference Command Expansion.

• A node name may not start with a left parenthesis preceding a right parenthesis, as in (not)allowed, since this syntax is used to specify an external manual.
• Unfortunately, you cannot reliably use periods, commas, or colons within a node name; these can confuse some Info readers. texi2any quotes problematic node names and labels by default, but some Info readers do not recognize this syntax. Node name and label quoting causes DEL characters (‘CTRL-?’, character number 127, often rendered as ‘^?’) to appear around the name. To remove node names and labels quoting, you can set the customization variable INFO_SPECIAL_CHARS_QUOTE to ‘0’ (see Other Customization Variables).

  texi2any warns about such problematic usage in node names, menu items, and cross-references. If you don’t want to see the warnings, you can set the customization variable INFO_SPECIAL_CHARS_WARNING to ‘0’ (see Other Customization Variables).

  If you insist on using these characters in node names, in order not to confuse the Texinfo processors you must still escape those characters, by using either special insertions (see Inserting ‘,’ with @comma{}) or @asis (see @asis). For example:

  @node foo@asis{::}bar@comma{} baz
  

  As an example of avoiding the special characters, the following is a section title in this manual:

  @section @code{@@unnumbered}, @code{@@appendix}: Chapters with...
  

  But the corresponding node name lacks the commas and the subtitle:

  @node @code{@@unnumbered @@appendix}
  

• Case is significant in node names.
• Spaces before and after names on the ‘@node’ line are ignored. Multiple whitespace characters “inside” a name are collapsed to a single space. For example:

  @node foo bar
  @node  foo bar,
  @node foo bar ,
  @node foo  bar,
  @node  foo  bar ,
  

  all define the same node, namely ‘foo bar’. In menu entries, a single internal space should be used in node names or some versions of some Info readers will not find the node.

3.4 The First Node ¶

The first node of a Texinfo file is the Top node, except in an included file (see Include Files). The Top node should contain a short summary and a master menu. See The ‘Top’ Node and Master Menu for more information on the Top node contents and examples. Straight text before the Top node outside of any node should be avoided. Such text, if present, is not output for DocBook.

Here is a description of the node pointers to be used in the Top node:

• The Top node (which must be named ‘top’ or ‘Top’) should have as its ‘Up’ node the name of a node in another file, where there is a menu that leads to this file. Specify the file name in parentheses.

  Usually, all Info files are available through a single virtual Info tree, constructed from multiple directories. In this case, use ‘(dir)’ as the parent of the Top node; this specifies the top-level node in the dir file, which contains the main menu for the Info system as a whole. (Each directory with Info files is intended to contain a file named dir.)

  That’s fine for Info, but for HTML output, one might well want the Up link from the Top node to go to some specific place. For example, for GNU the natural place would be http://www.gnu.org/manual/ (a web page collecting links to most GNU manuals), better specified as just /manual/ if the manual will be installed on www.gnu.org. This can be specified with the TOP_NODE_UP_URL customization variable (see HTML Customization Variables), as in

  $ texi2any --html -c TOP_NODE_UP_URL=/manual/ ...
  

• The ‘Prev’ node of the Top node is usually omitted.
• The ‘Next’ node of the Top node should be the first chapter in your document.

See Installing an Info File, for more information about installing an Info file in the info directory.

It is usually best to leave the pointers off entirely and let the tools implicitly define them, with this simple result:

@node Top

3.5 The @top Sectioning Command ¶

The @top command is a special sectioning command that you should only use after a ‘@node Top’ line at the beginning of a Texinfo file.

It produces the same sort of output as @unnumbered (see @unnumbered, @appendix: Chapters with Other Labeling). In LaTeX \part* is used.

@top is ignored when raising or lowering sections. That is, it is never lowered and nothing can be raised to it (see Raise/lower Sections: @raisesections and @lowersections).

It used to be conventional to wrap the ‘Top’ node in an @ifnottex conditional so that it would not appear in printed output (see Conditionally Visible Text). Thus, a Top node often looked like this:

@ifnottex
@node Top
@top your-manual-title

very-high-level-summary
@end ifnottex

This is no longer necessary, as the ‘Top’ node is now never output for printed output. The ‘Top’ node is not output for DocBook either.

3.6 Texinfo Document Structure ¶

Nodes can contain menus, which contain the names of child nodes 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 the Info output.

In addition, nodes contain node pointers that name other nodes. The ‘Next’ and ‘Previous’ pointers link nodes at the same sectioning level into a chain. As you might imagine, the ‘Next’ pointer links to the next node, and the ‘Previous’ pointer links to the previous node. In general, ‘Next’ and ‘Previous’ refer to nodes at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may be at a lower level—a section-level node most often follows a chapter-level node, for example. 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 the parent chapter. Each child node records the parent node name as its ‘Up’ pointer.

Since the ‘Top’ node is the only node at that level, ‘Next’ refers to the first following node, which is almost always a chapter or chapter-level node. This is an exception to the rule of ‘Next’ being at the same hierarchical level.

The Info and HTML output for each node includes links to the ‘Next’, ‘Previous’, and ‘Up’ nodes. The HTML also uses the accesskey attribute with the values ‘n’, ‘p’, and ‘u’ respectively. This allows people using web browsers to follow the navigation using (typically) M-letter, e.g., M-n for the ‘Next’ node, from anywhere within the node. Node pointers and menus provide structure for Info files just as chapters, sections, subsections, and the like provide structure for printed books. The two structures are theoretically distinct; in practice, however, the tree structure of printed books is essentially always used for the node and menu structure also, as this leads to a document which is easy to follow.

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.

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 different from the conventional structure. To the best of our knowledge, however, all the Texinfo manuals currently in general use do follow the conventional parallel structure.

3.7 Node and Menu Illustration ¶

Here is a diagram that illustrates a Texinfo file with three chapters, each of which contains two sections.

The “root” is at the top of the diagram and the “leaves” are at the bottom. This is how such a diagram is drawn conventionally; it illustrates an upside-down tree. For this reason, the root node is called the ‘Top’ node, and ‘Up’ node pointers carry you closer to the root.

                         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

Using explicit pointers (not recommended, but shown for purposes of the example), the fully-written command to start Chapter 2 would be this:

@node     Chapter 2,  Chapter 3, Chapter 1, Top
@comment  node-name,  next,      previous,  up

This @node line says that the name of this node is “Chapter 2”, the name of the ‘Next’ node is “Chapter 3”, the name of the ‘Previous’ node is “Chapter 1”, and the name of the ‘Up’ node is “Top”. You can (and should) omit writing out these node names if your document is hierarchically organized, but the pointer relationships still obtain.

To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter 2. (See Menus.) You would write the menu just before the beginning of Section 2.1, like this:

   @menu
   * Sect. 2.1::    Description of this section.
   * Sect. 2.2::    Description.
   @end menu

The automatic pointers for the node for Sect. 2.1 correspond to:

@node     Sect. 2.1, Sect. 2.2, ,         Chapter 2
@comment  node-name, next,      previous, up

Note that no ‘Prev’ pointer is generated, since there is no other node at the same hierarchical level before Sect. 2.1.

Using explicit pointers, the node for Sect. 2.1 could be written like this:

@node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
@comment  node-name, next,      previous,  up

With automatic pointers, the ‘Next’ and ‘Previous’ pointers of a node lead to other nodes at the same level—from chapter to chapter or from section to section. As shown, when using explicit pointers, the pointers can also lead somewhere else, here, for example, the ‘Previous’ pointer points up. An ‘Up’ pointer usually leads to a node at the level above (closer to the ‘Top’ node; and a ‘Menu’ leads to nodes at a level below (closer to ‘leaves’). (A cross-reference can point to a node at any level; see Cross-references.)

Technically, explicit node pointers can carry you to any node, regardless of the structure of the document; even to nodes in a different Info file. However, it would be very confusing for readers to have the ‘Next’, ‘Previous’ and ‘Up’ pointers lead to nodes that do not correspond, even loosely, to the next, previous and up node.

A @node command and a chapter structuring command are conventionally used together, in that order, often followed by indexing commands. (As shown in the example above, you may follow the @node line with a comment line, e.g., to show which pointer is which if explicit pointers are used.) The Texinfo processors use this construct to determine the relationships between nodes and sectioning commands.

Here is the beginning of the chapter in this manual called “Ending a Texinfo File”. This shows a @node line followed by a @chapter line, and then by indexing lines.

@node Ending a File
@chapter Ending a Texinfo File
@cindex Ending a Texinfo file
@cindex Texinfo file ending
@cindex File ending

3.8 Node Descriptions ¶

You can provide a short description of the purpose of a node by using the @nodedescription command following the @node line. Such a description might elaborate on or extend the information in the node name itself.

You can also use a @nodedescriptionblock environment to provide a node description. This may be useful for longer descriptions.

texi2any uses the content you provide with these commands when outputing menus for Info output format (and, optionally, for HTML). texi2any uses the description after a menu entry for the node if it is generating the menu automatically, or if no description for the menu entry was provided in an explicit @menu block. (See Menus).

Here is an example of using these commands:

@node Tools
@chapter Tools

This chapter is on different tools you can use.

@node Screwdrivers
@nodedescription Flathead and Phillips.
@section Screwdrivers

This section is about screwdrivers.

@node Drills
@nodedescriptionblock
Making holes in things with power screwdrivers, drill drivers, combi
drills, impact drivers, hammer drills, breakers and demolition drills.
@end nodedescriptionblock
@section Drills

This section is about drills.

In Info output, texi2any would output the ‘Tools’ node with a menu as follows:

* Menu:

* Screwdrivers::          Flathead and Phillips.
* Drills::                Making holes in things with power
                          screwdrivers, drill drivers, combi
                          drills, impact drivers, hammer drills,
                          breakers and demolition drills.

3.9 Menus ¶

Menus contain pointers to subordinate nodes. In Info output, you use menus to go to such nodes. texi2any can output menus in HTML output, but does not do so by default (see Other Customization Variables, under FORMAT_MENU). Menus have no role in printed manuals or other output formats.

Menus are automatically generated by texi2any when outputting Info for nodes followed by a sectioning command, without an explicit @menu block, and with automatic pointers.

It is often more convenient to let texi2any generate menus for you, as you do not then have the burden of updating menu blocks in your Texinfo source when you add, remove, or relocate nodes. In the usual case of a hierarchically organized manual with sectioning commands associated with nodes, and with node pointers left out, you should only write menus if you want exact control over the contents and formatting of menus in Info.

• Writing a Menu
• A Menu Example
• Menu Location
• The Parts of a Menu
• Less Cluttered Menu Entry
• Referring to Other Info Files

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                 several files at once.
@end menu

@menu
* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.
@end menu

* Menu:

* menu entry name: Node name.   A short description.
* Node name::                   This form is preferred.

@menu
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                 several files at once.
@end menu

* Menu:
Larger Units of Text

* Files::                       All about handling files.
* Multiples: Buffers.           Multiple buffers; editing
                                 several files at once.

* menu-entry-name: node-name.   description

* Name::                        description

* Name: Name.                   description

@menu
* first-entry-name:(filename)nodename.     description
* (filename)second-node::                  description
@end menu

@menu
* Outlining: (emacs)Outline Mode. The major mode for
                                   editing outlines.
* (emacs)Rebinding::              How to redefine the
                                   meaning of a key.
@end menu

* Info: (info).         Documentation browsing system.
* (emacs)::             The extensible, self-documenting
                         text editor.

4.1 Tree Structure of Sections ¶

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.

                         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

In a Texinfo file that has this structure, the beginning of Chapter 2 would be written like this:

@node    Chapter 2
@chapter Chapter 2

For purposes of example, here is how it would be written with explicit node pointers:

@node    Chapter 2,  Chapter 3, Chapter 1, Top
@chapter Chapter 2

The chapter structuring commands are described in the sections that follow; the @node command is described in the previous chapter (see Nodes).

4.2 Structuring Command Types ¶

The chapter structuring commands fall into four groups, each of which contains structuring commands at the levels of chapters, sections, subsections, and subsubsections:

• The @chapter-like commands and @appendix-like commands produce numbered or lettered entries both in the body of a document and in its table of contents.
• The @unnumbered-like commands produce unnumbered entries both in the body of a document and in its table of contents. The @top command, which has a special use, is a member of this group (see The @top Sectioning Command). An @unnumbered section is a normal part of the document structure.
• The @heading-like 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.

In printed output, the chapter structuring commands produce headings in the document. When a @setchapternewpage command says to do so, the @chapter, @unnumbered, and @appendix commands start new pages in the printed manual; the @heading commands do not. See @setchapternewpage: Blank Pages Before Chapters.

In Info and plain text output, the command causes the title to appear on a line by itself, with a line of an ASCII character (‘*’, ‘=’, …) inserted underneath. For example, the “Chapter Structuring” heading could be:

5 Chapter Structuring
*********************

The underlining character is the same for all the commands at the same level. For instance, it is the same for the chapter-level commands @chapter, @apppendix, @unnumbered and @chapheading.

In HTML, the chapter-level commands produce an <h2>-level header by default (controlled by the CHAPTER_HEADER_LEVEL customization variable, see Other Customization Variables). The heading element level is adjusted for the other commands.

In the DocBook output, the appropriate level of element is used. The produced element includes all following sections up to the next command at the same or higher level. For example, a <chapter> element is produced for @chapter, and contains any sections or subsections in the chapter.

Here is a summary:

4.3 @chapter: Chapter Structuring ¶

@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 from 1.

For example, the present chapter in this manual is entitled “Chapter Structuring”; the @chapter line looks like this:

@chapter Chapter Structuring

4.4 @unnumbered, @appendix: Chapters with Other Labeling ¶

Use the @unnumbered command to start a chapter-level element that appears without chapter numbers of any kind. Use the @appendix command to start an appendix that is labeled by letter (‘A’, ‘B’, …) instead of by number; appendices are also at the chapter level of structuring.

Write an @appendix or @unnumbered command at the beginning of a line and follow it on the same line by the title, just as with @chapter.

Texinfo also provides a command @centerchap, which is analogous to @unnumbered, but centers its argument in the printed and HTML outputs. This kind of stylistic choice is not usually offered by Texinfo. You are recommended not to use this command, as it may be removed in future releases of Texinfo.

With @unnumbered, if the name of the associated node is one of these English words (case-insensitive):

Acknowledgements  Colophon  Dedication  Preface

then the DocBook output uses corresponding special tags (<preface>, etc.) instead of the default <chapter>. The argument to @unnumbered itself can be anything, and is output as the element title as usual.

4.5 @majorheading, @chapheading: Chapter-level Headings ¶

The @majorheading and @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 @majorheading command generates a larger vertical whitespace before the heading than a @chapheading command but is otherwise the same.

In other output formats, the @majorheading and @chapheading commands produce a similar output to @chapter. The difference is the lack of numbering and the lack of any association with nodes. See @chapter: Chapter Structuring.

4.6 @section: Sections Below Chapters ¶

An @section command identifies a section within a chapter unit, whether created with @chapter, @unnumbered, or @appendix, following the numbering scheme of the chapter-level command. Thus, within a @chapter chapter numbered ‘1’, the sections are numbered ‘1.1’, ‘1.2’, etc.; within an @appendix “chapter” labeled ‘A’, the sections are numbered ‘A.1’, ‘A.2’, etc.; within an @unnumbered chapter, the section gets no number.

To make a section, write the @section command at the beginning of a line and follow it on the same line by the section title. For example:

@section This is a section

Section titles are listed in the table of contents.

4.7 @unnumberedsec, @appendixsec, @heading ¶

The @unnumberedsec, @appendixsec, and @heading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @section command (see the previous section).

@unnumberedsec and @appendixsec do not need to be used in ordinary circumstances, because @section may also be used within @unnumbered and @appendix chapters; again, see the previous section.

@unnumberedsec

The @unnumberedsec command may be used within an unnumbered chapter or within a regular chapter or appendix to produce an unnumbered section.

@appendixsec ¶

@appendixsection

@appendixsection is a longer spelling of the @appendixsec command; the two are synonymous.

Conventionally, the @appendixsec or @appendixsection command is used only within appendices.

@heading

You may use the @heading command (almost) anywhere for a section-style heading that will not appear in the table of contents. The @heading-series commands can appear inside most environments, for example, though pathological and useless locations such as an argument to another command, etc., are not allowed.

4.8 @subsection: Subsections Below Sections ¶

Subsections are to sections as sections are to chapters; see @section: Sections Below Chapters. For example:

@subsection This is a subsection

Subsection titles are listed in the table of contents.

4.9 The @subsection-like Commands ¶

The @unnumberedsubsec, @appendixsubsec, and @subheading commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the @subsection command. (See @subsection: Subsections Below Sections.)

@unnumberedsubsec and @appendixsubsec do not need to be used in ordinary circumstances, because @subsection may also be used within sections of @unnumbered and @appendix chapters (see @section: Sections Below Chapters).

An @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 @unnumberedsubsec command produces an unnumbered heading like that of a subsection and an @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.

4.10 @subsubsection and Other Subsub Commands ¶

The fourth and lowest level sectioning commands in Texinfo are the ‘subsub’ commands. They are:

@subsubsection

Subsubsections are to subsections as subsections are to sections. (See @subsection: Subsections Below Sections.) Subsubsection titles appear in the table of contents.

@unnumberedsubsubsec

Unnumbered subsubsection titles appear in the table of contents, but lack numbers. Otherwise, unnumbered subsubsections are the same as subsubsections.

@appendixsubsubsec

Conventionally, appendix commands are used only for appendices and are lettered and numbered appropriately. They also appear in the table of contents.

@subsubheading

The @subsubheading command may be used anywhere that you want a small heading that will not appear in the table of contents.

As with subsections, @unnumberedsubsubsec and @appendixsubsubsec do not need to be used in ordinary circumstances, because @subsubsection may also be used within subsections of @unnumbered and @appendix chapters (see @section: Sections Below Chapters).

4.11 @part: Groups of Chapters ¶

The final sectioning command is @part, to mark a 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 @node command is associated with @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:

@part Part I:@* The beginning

As can be inferred from this example, no automatic numbering or labeling of the @part text is done. The text is taken as-is.

Because parts are not associated with nodes, no general text can follow the @part line. To produce the intended output, it must be followed by a chapter-level command (including its node). Thus, to continue the example:

@part Part I:@* The beginning

@node Introduction
@chapter Introduction
...

In the TeX output, the @part text is included in both the normal and short tables of contents (see Generating a Table of 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 @part text. In the example above, the @* 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 (see @setchapternewpage: Blank Pages Before Chapters). In the LaTeX output, the @part is output as \part.

In the HTML output, the @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 DocBook output, the <part> element includes all the following chapters, up to the next <part>. A <part> containing chapters is also closed at an appendix.

In the Info and plain text output, @part has no effect.

@part is ignored when raising or lowering sections (see next section). That is, it is never lowered and nothing can be raised to it.

4.12 Raise/lower Sections: @raisesections and @lowersections ¶

The @raisesections and @lowersections commands implicitly raise and lower the hierarchical level of following chapters, sections and the other sectioning commands (excluding parts).

That is, the @raisesections command changes sections to chapters, subsections to sections, and so on. Conversely, the @lowersections command changes chapters to sections, sections to subsections, and so on. Thus, a @lowersections command cancels a @raisesections command, and vice versa.

As a practical matter, you generally only want to raise or lower large chunks, usually in external files. You can use @lowersections to include text written as an outer or standalone Texinfo file in another Texinfo file as an inner, included file (see Include Files). Typical usage looks like this:

@lowersections
@include somefile.texi
@raisesections

(Without the @raisesections, all the subsequent sections in the main file would also be lowered.)

If the included file being lowered has a @top node, you’ll need to conditionalize its inclusion with a flag (see @set and @value).

Any menus in the final result have to take the raising and lowering into account, so arbitrarily sprinkling @raisesections and @lowersections commands throughout the document will likely lead to errors (unless the menus in your document are all generated automatically).

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 texi2any’s feature of implicitly determining node pointers, since the menu structure cannot be represented correctly.

Write each @raisesections and @lowersections command on a line of its own.

5.1 Different Cross-reference Commands ¶

There are three different cross-reference commands:

@xref

Used to start a sentence with an Info cross-reference saying ‘*Note name: node.’ or with ‘See …’ in other output formats.

@ref

Used within or, more often, at the end of a sentence; produces an Info cross-reference saying ‘*note name: node.’, and just the reference in other output formats, without the preceding ‘See’.

@pxref

Used within parentheses, at the end of a sentence, or otherwise before punctuation, to make a reference. Its output starts with a lowercase ‘*note’ in Info, and with a lowercase ‘see’ in the other output formats. (‘p’ is for ‘parenthesis’.)

Additionally, there are commands to produce references to documents outside the Texinfo system. The @cite command is used to make references to books and manuals. @url produces a URL, for example a reference to a page on the World Wide Web.

5.2 Parts of a Cross-reference ¶

A cross-reference command requires only one argument, which is the name of the node to which it refers. A cross-reference command may contain up to four additional arguments. The template for a full five argument cross-reference looks like this:

@xref{node-name, online-label, printed-label,
manual-name, printed-manual-title}

The five possible arguments for a cross-reference are:

1. The node or anchor name. This is the location to which the cross-reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document. Use @node to define the node (see Writing a @node Line), @anchor (see @anchor: Defining Arbitrary Cross-reference Targets), or @float (see @float [type][,label]: Floating Material) with a label. This argument is required (except for reference to whole manuals).

   Write a node name in a cross-reference in exactly the same way as in the @node line, including the same capitalization; otherwise, the processors may not find the reference.

2. A label for online output. It is usually omitted; then the topic description (third argument) is used if it was specified; if that was omitted as well, the node name is used.
3. A label for printed output. Often, this is the title or topic of the section. This is used as the name of the reference in the printed manual. If omitted, the node name is used.
4. The name of the manual to which the reference refers, if it is outside the current manual, in a different Texinfo file.
5. The title of the printed manual to which the reference refers, from a different Texinfo file.

Whitespace before and after the commas separating these arguments is ignored. To include a comma in one of the arguments, use @comma{} (see Inserting ‘,’ with @comma{}).

Cross-references with one, two, three, four, and five arguments are described separately in following sections.

When processing with TeX, a comma is automatically inserted after the page number for cross-references to within the same manual, unless the closing brace of the argument is followed by non-whitespace (such as a comma or period). This gives you the choice of whether to have a comma there in other output formats. For example,

@xref{Another Section} for more info

with TeX produces ‘See Another Section, page ppp, for more info’, and in the Info output produces ‘*Note Another Section:: for more info’.

If an unwanted comma is added, follow the argument with a command such as ‘@:’. For example, ‘@xref{Hurricanes}@: --- for the details’ produces

See Hurricanes, page ppp — for the details

instead of ‘See Hurricanes, page ppp, — for the details’.

texi2any warns and protect names when the text of a cross-reference (and node names and menu items) contains a problematic construct that could interfere with its parsing in Info. See Info Node Names Constraints.

5.3 @xref with One Argument ¶

The simplest form of @xref takes one argument, the name of another node in the same Texinfo file.

For example,

@xref{Tropical Storms}.

produces

*Note Tropical Storms::.

in Info and

See Section 3.1 [Tropical Storms], page 24.

in a printed manual.

5.4 @xref with Two Arguments ¶

With two arguments, the second is used as a label for the online output.

The template is like this:

@xref{node-name, online-label}.

For example,

@xref{Electrical Effects, Lightning}.

produces:

*Note Lightning: Electrical Effects.

in Info and

See Section 5.2 [Electrical Effects], page 57.

in a printed manual, where the node name is printed.

The second argument to cross-references shares constraints with node names. The potentially problematic character in this context is the colon. See Info Node Names Constraints.

5.5 @xref with Three Arguments ¶

A third argument replaces the node name in the printed output. The third argument should be the name of the section in the printed output, or else state the topic discussed by that section.

The template is like this:

@xref{node-name, online-label, printed-label}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning},
for details.

produces

*Note Lightning: Electrical Effects, for details.

in Info and

See Section 5.2 [Thunder and Lightning], page 57, for details.

in a printed manual.

If a third argument is given and the second one is empty, then the third argument serves for both. (Note how two commas, side by side, mark the empty second argument.)

@xref{Electrical Effects, , Thunder and Lightning},
for details.

produces

*Note Thunder and Lightning: Electrical Effects, for details.

in Info and

See Section 5.2 [Thunder and Lightning], page 57, for details.

in a printed manual.

The third argument to cross-references shares constraints with node names. The potentially problematic character in this context is the colon. See Info Node Names Constraints.

As a practical matter, it is often best to write cross-references with just the first argument if the node name and the section title are the same (or nearly so), and with the first and third arguments only if the node name and title are different.

Texinfo offers a setting to use the section title instead of node names by default in cross-references (an explicitly specified third argument still takes precedence):

@xrefautomaticsectiontitle on

Typically this line would be given near the beginning of the document and used for the whole manual. But you can turn it off if you want (@xrefautomaticsectiontitle off), for example, if you’re including some other sub-document that doesn’t have suitable section names. This setting also applies to node headers in HTML, if @xrefautomaticsectiontitle is on, the sections names are used in node headers instead of the node names when possible.

5.6 @xref with Four and Five Arguments ¶

In a cross-reference, a fourth argument specifies the name of another manual, different from the file in which the reference appears, and a fifth argument specifies its title as a printed manual.

The full template is:

@xref{node-name, online-label, printed-label,
manual-name, printed-manual-title}.

For example,

@xref{Electrical Effects, Lightning, Thunder and Lightning,
weather, An Introduction to Meteorology}.

produces this output in Info:

*Note Lightning: (weather)Electrical Effects.

As you can see, the name of the manual is enclosed in parentheses and precedes the name of the node. In HTML, the manual name and the node name are used to construct the hyperlink URL (see HTML Cross-references), while the link text is based on the label.

In a printed manual, the reference looks like this:

See section “Thunder and Lightning” in An Introduction to Meteorology.

The title of the printed manual is typeset like @cite; and the reference lacks a page number since the page a reference refers when that reference is to another manual cannot be known.

Next case: often, you will leave out the second argument when you use the long version of @xref. In this case, the third argument, the topic description, will be used as the cross-reference name in online formats. For example,

@xref{Electrical Effects, , Thunder and Lightning,
weather, An Introduction to Meteorology}.

produces

*Note Thunder and Lightning: (weather)Electrical Effects.

in Info and

See section “Thunder and Lightning” in An Introduction to Meteorology.

in a printed manual.

Next case: If the node name and the section title are the same in the other manual, you may also leave out the section title. In this case, the node name is used in both instances. For example,

@xref{Electrical Effects,,,
weather, An Introduction to Meteorology}.

produces

*Note (weather)Electrical Effects::.

in Info and

See section “Electrical Effects” in An Introduction to Meteorology.

in a printed manual.

In general, there is no reason to have a manual name argument without a printed manual argument, unless no printed manual is generated. You may also want to refer to another manual file that is within a single printed manual—when multiple Texinfo files are incorporated into the same printed manual but can create separate output files in other output formats. In this case, you need to specify only the fourth argument, and not the fifth. If the printed manual title argument is missing, the manual name will be used instead in printed output.

A printed manual title argument without an online manual argument is of little use unless only a printed manual is generated from the Texinfo source. The result in online formats depends on the format, and can be, for example, an empty manual name or a reference to the printed manual formatted in a similar way to the printed output.

Finally, it’s also allowed to leave out all the arguments except the fourth and fifth, to refer to another manual as a whole. See the next section.

5.7 Referring to a Manual as a Whole ¶

Ordinarily, you must always name a node in a cross-reference. However, it’s not unusual to want to refer to another manual as a whole, rather than a particular section within it. In this case, giving any section name is an unnecessary distraction.

So, with cross-references to other manuals (see @xref with Four and Five Arguments), if the first argument is either ‘Top’ (capitalized just that way) or omitted entirely, and the third argument is omitted, the printed output includes no node or section name. (The Info output includes ‘Top’ if it was given.) For example,

@xref{Top,,, make, The GNU Make Manual}.

produces

*Note (make)Top::.

and

See The GNU Make Manual.

Info readers will go to the Top node of the manual whether or not the ‘Top’ node is explicitly specified.

It’s also possible (and is historical practice) to refer to a whole manual by specifying the ‘Top’ node and an appropriate entry for the third argument to the @xref command. Using this idiom, to make a cross-reference to The GNU Make Manual, you would write:

@xref{Top,, Overview, make, The GNU Make Manual}.

which produces

*Note Overview: (make)Top.

in Info and

See section “Overview” in The GNU Make Manual.

in a printed manual.

In this example, ‘Top’ is the name of the first node, and ‘Overview’ is the name of the first section of the manual. There is no widely-used convention for naming the first section in a printed manual, this is just what the Make manual happens to use. This arbitrariness of the first name is a principal reason why omitting the third argument in whole-manual cross-references is preferable.

5.8 @xref ¶

The @xref command generates a cross-reference for the beginning of a sentence. Examples of using @xref are in previous sections.

5.9 @ref ¶

@ref is nearly the same as @xref except that it does not generate a ‘See’ in the output, just the reference itself. This makes it useful as the last part of a sentence.

For example,

For more information, @pxref{This}, and @ref{That}.

produces in Info:

For more information, *note This::, and *note That::.

and in printed output:

For more information, see Section 1.1 [This], page 1, and Section 1.2 [That], page 2.

The @ref command can tempt writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. Bear in mind that your audience could be using both the printed and other output formats such as Info. For example:

Sea surges are described in @ref{Hurricanes}.

looks ok in the printed output:

Sea surges are described in Section 6.7 [Hurricanes], page 72.

but is awkward to read in Info, “note” being a verb:

Sea surges are described in *note Hurricanes::.

5.10 @pxref ¶

The parenthetical reference command, @pxref, is nearly the same as @xref, but it is best used within parentheses. The command differs from @xref in that the reference is typeset with a lowercase ‘see’ rather than an uppercase ‘See’. In Info, ‘*note’ is output.

With one argument, a parenthetical cross-reference looks like this:

... storms cause flooding (@pxref{Hurricanes}) ...

which produces

... storms cause flooding (*note Hurricanes::) ...

in Info and

… storms cause flooding (see Section 6.7 [Hurricanes], page 72) …

in a printed manual.

In past versions of Texinfo, it was not allowed to write punctuation after a @pxref, so it could be used only before a right parenthesis. This is no longer the case. The effect of ‘@pxref{node-name}’ is similar to that of ‘see @ref{node-name}’. However, in many circumstances the latter is preferable, as this makes it clear in the Info output that the word “see” should be present.

5.11 @anchor: Defining Arbitrary Cross-reference Targets ¶

An 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 @anchor command, and give the label as a normal brace-delimited argument. For example:

This marks the @anchor{x-spot}spot.
...
@xref{x-spot,,the spot}.

produces:

This marks the spot.
...
See [the spot], page 1.

As you can see, the @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 @xref or other cross reference command, as shown (see Cross-references).

It is best to put @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 @anchor command on a line by itself if that helps readability of the source. Whitespace (including newlines) is ignored after @anchor.

Anchor names, node names and float labels may not conflict. Anchors, nodes and float labels are given similar treatment in some ways; for example, the goto-node command takes either an anchor name or a node name as an argument. (See Go to node in Info.). Anchors names and float labels could also appear in menus (see Menus) and node direction pointers (see Writing a @node Line), although this is not recommended.

Anchor names share the same constraints as nodes on the characters that can be included (see Info Node Names Constraints).

Because of this duality, when you delete or rename a node, it is usually a good idea to define an @anchor with the old name. That way, any links to the old node, whether from other Texinfo manuals or general web pages, keep working.

5.12 @link: Plain, unadorned hyperlink ¶

@link produces a plain hyperlink in output formats that support it, including in HTML, DocBook, LaTeX and online PDF. The template is:

@link{node-name, label, manual-name}

node-name is the name of the target node or anchor. Either or both of label and manual-name can be omitted. label, if given, is the text to use for the link. manual-name is the name of the external manual that the target appears within; if not given, the reference is to the current manual.

@link has similar output to @ref, except that it does produce any extra text around the link label in Info or printed output that would mark it as a cross-reference.

Be careful about using @link to produce links that are necessary for a user to move around a manual, as these links will do nothing in these output formats. @link is best used to add convenience links that are nonetheless not essential for a reader to understand the text of the manual. For example, you might use @link in a code sample to reference documentation of a symbol in a programming library.

5.13 @inforef: Cross-references to Info-only Material ¶

@inforef is used for making cross-references to Info documents—even from a printed manual. This was originally used for Info files that were not generated from any Texinfo source. The command is now obsolete and should not be used. In addition to having little use, similar output can be obtained with @xref, @ref or @pxref with the Info file name as the fourth argument and no fifth argument.

The command takes either two or three arguments, in the following order:

1. The node name.
2. The cross-reference name (optional).
3. The Info file name.

The template is:

@inforef{node-name, cross-reference-name, info-file-name}

5.14 @url, @uref{url[, text][, replacement]} ¶

@url produces a reference to a uniform resource locator (URL). It takes one mandatory argument, the URL, and two optional arguments which control the text that is displayed. In HTML and PDF output, @url produces a link you can follow. (To merely indicate a URL without creating a link people can follow, use @indicateurl, see @indicateurl{uniform-resource-locator}.)

@uref is a synonym for @url. (Originally, @url had the meaning of @indicateurl and @uref was required to produce a working link, but in practice @url was almost always misused. So we’ve changed the meaning.)

The second argument, if specified, is the text to display (the default is the URL itself); in output formats other than HTML, the URL is output in addition to this text.

The third argument, if specified, is the text to display, but in this case the URL is not output in any format. This is useful when the text is already sufficiently referential, as in a man page. Also, if the third argument is given, the second argument is ignored.

• @url Examples
• URL Line Breaking
• @url PDF Output Format

The official GNU ftp site is @url{http://ftp.gnu.org/gnu}.

The official GNU ftp site is http://ftp.gnu.org/gnu.

The official @url{http://ftp.gnu.org/gnu, GNU ftp site}
holds programs and texts.

The official GNU ftp site
holds programs and texts.

The official <a href="http://ftp.gnu.org/gnu">GNU ftp site</a>
holds programs and texts.

The official GNU ftp site (http://ftp.gnu.org/gnu)
holds programs and texts.

The @url{/man.cgi/1/ls,,ls} program ...

The ls program ...

The <a href="/man.cgi/1/ls">ls</a> program ...

<URL:http://host/path>

@urefbreakstyle how

@tex
\global\urefurlonlylinktrue
@end tex

5.15 @cite{reference} ¶

Use the @cite command for the name of a book that lacks a companion Info file. For example, we could refer to A Book. The command selects a slanted font in the printed manual, and generates quotation marks in the Info file.

If a book is written in Texinfo, it is better to use a cross-reference command since a reader can easily follow such a reference in Info. See @xref.

5.16 PDF Colors ¶

By default, URLs and cross-reference links are printed in black in PDF output. Very occasionally, however, you may want to highlight such “live” links with a different color, as is commonly done on web pages. Texinfo provides a PDF-specific option for specifying these colors, which must be used inside @tex:

@tex
\global\def\linkcolor{1 0 0}  % red
\global\def\urlcolor{0 1 0}   % green
@end tex

\urlcolor changes the color of @url output (both the actual URL and any textual label), while \linkcolor changes the color for cross-references to nodes, etc. They are independent.

The three given values must be numbers between 0 and 1, specifying the amount of red, green, and blue respectively.

These definitions only have an effect when the PDF output is produced with the pdfTeX program, not with other ways of getting from Texinfo to PDF (e.g., TeX to DVI to PDF). Consequently, it is ok to specify this option unconditionally within @tex, as shown above. It is ignored when DVI is being produced.

We do not recommend colorizing just for fun; unless you have a specific reason to use colors, best to skip it.

6.1 Indicating Definitions, Commands, etc. ¶

Texinfo has commands for indicating just what kind of object a piece of text refers to. For example, email addresses are marked by @email; that way, the result can be a live link to send email when the output format supports it. If the email address was simply marked as “print in a typewriter font”, that would not be possible.

• Highlighting Commands are Useful
• @code{sample-code}
• @kbd{keyboard-characters}
• @key{key-name}
• @samp{text}
• @verb{chartextchar}
• @var{metasyntactic-variable}
• @env{environment-variable}
• @file{file-name}
• @command{command-name}
• @option{option-name}
• @dfn{term}
• @abbr{abbreviation[, meaning]}
• @acronym{acronym[, meaning]}
• @indicateurl{uniform-resource-locator}
• @email{email-address[, displayed-text]}

The function returns @code{nil}.

@kbd{M-a}

@kbd{M-x shell}

@kbd{r @key{RET}}

To give the @code{logout} command,
type the characters @kbd{l o g o u t @key{RET}}.

@key{RET}

@kbd{C-x @key{ESC}}
@kbd{M-@key{TAB}}

To match @samp{foo} at the end of the line,
use the regexp @samp{foo$}.

In English, the vowels are @samp{a}, @samp{e},
@samp{i}, @samp{o}, @samp{u}, and sometimes
@samp{y}.

How many @verb{|@|}-escapes does one need to print this
@verb{.@a @b.@c.} string or @verb{+@'e?`{}!`\+} this?

How many @-escapes does one need to print this
@a @b.@c string or @'e?`{}!`\ this?

To delete file @var{filename},
type @samp{rm @var{filename}}.

\input texinfo
@@settitle @var{name-of-manual}

\input texinfo
@settitle name-of-manual

..., type rm <filename>

The @env{PATH} environment variable ...

The @file{.el} files are in
the @file{/usr/local/emacs/lisp} directory.

The command @command{ls} lists directory contents.

The option @option{-l} produces a long listing.

Getting rid of a file is called @dfn{deleting} it.

@abbr{Comput. J., Computer Journal}

Comput. J. (Computer Journal)

@acronym{GNU, @acronym{GNU}'s Not Unix}

GNU (GNU’s Not Unix)

For example, the URL might be @indicateurl{http://example.org/path}.

For example, the URL might be ‘http://example.org/path’.

Send bug reports to @email{bug-texinfo@@gnu.org},
suggestions to the @email{bug-texinfo@@gnu.org, same place}.

Send bug reports to bug-texinfo@gnu.org,
suggestions to the same place.

6.2 Emphasizing Text ¶

Usually, Texinfo changes the font to mark words in the text according to the category the words belong to; an example is the @code command. Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which text will be output. These commands have no effect in Info and only one of them, the @r command, has any regular use.

• @emph{text} and @strong{text}
• @sc{text}: The Small Caps Font
• Fonts for Printing

@strong{Caution:} @samp{rm * .[^.]*}
removes @emph{all} files in the directory.

Richard @sc{Stallman} a commencé le projet GNU.

Richard STALLMAN a commencé le projet GNU.

@fonttextsize 10

@lisp
(+ 2 2)    ; @r{Add two plus two.}
@end lisp

(+ 2 2)    ; Add two plus two.

7.1 Block Enclosing Commands ¶

Here is a summary of commands that enclose blocks of text, also known as environments. They’re explained further in the following sections.

@quotation

Indicate text that is quoted. The text is filled, indented (from both margins), and printed in a roman font by default.

@indentedblock

Like @quotation, but the text is indented only on the left.

@example

Illustrate code, commands, and the like. The text is printed in a fixed-width font, and indented but not filled.

@lisp

Like @example, but specifically for illustrating Lisp code. The text is printed in a fixed-width font, and indented but not filled.

@verbatim

Mark a piece of text that is to be printed verbatim; no character substitutions are made and all commands are ignored, until the next @end verbatim. The text is printed in a fixed-width font, and not indented or filled. Extra spaces and blank lines are significant, and tabs are expanded.

@display

Display illustrative text. The text is indented but not filled, and no font is selected (so, by default, the font is roman).

@format

Like @display (the text is not filled and no font is selected), but the text is not indented.

@smallquotation

@smallindentedblock

@smallexample

@smalllisp

@smalldisplay

@smallformat

These @small... commands are just like their non-small counterparts, except that they output text in a smaller font size, where possible.

@flushleft

@flushright

Text is not filled, but is set flush with the left or right margin, respectively.

@raggedright

Text is filled, but only justified on the left, leaving the right margin ragged.

@cartouche

Highlight text, often an example or quotation, by drawing a box with rounded corners around it.

The @exdent command is used within the above constructs to undo the indentation of a line.

The @noindent command may be used after one of the above constructs (or at the beginning of any paragraph) to prevent the following text from being indented as a new paragraph.

7.2 @quotation: Block Quotations ¶

The text of a quotation is processed like normal text (regular font, text is filled) except that:

• the left margin is closer to the center of the page, so the whole of the quotation is indented; the right margin may also be closer to the center of the page
• the first lines of paragraphs are indented no more than other lines; and
• an @author command may be given to specify the author of the quotation.

This is an example of text written between a @quotation command and an @end quotation command. A @quotation command is most often used to indicate text that is excerpted from another (real or hypothetical) printed work.

Write a @quotation command as text on a line by itself. This line will disappear from the output. Mark the end of the quotation with a line beginning with and containing only @end quotation. The @end quotation line will likewise disappear from the output.

@quotation takes one optional argument, given on the remainder of the line. This text, if present, is included at the beginning of the quotation in bold or otherwise emphasized, and followed with a ‘:’. For example:

@quotation Note
This is
a foo.
@end quotation

produces

Note: This is a foo.

If the @quotation argument is one of these English words (case-insensitive):

Caution  Important  Note  Tip  Warning

then the DocBook output uses corresponding special tags (<note>, etc.) instead of the default <blockquote>.

If the author of the quotation is specified in the @quotation block with the @author command, a line with the author name is displayed after the quotation:

@quotation
People sometimes ask me if it is a sin in the Church of Emacs to use
vi.  Using a free version of vi is not a sin; it is a penance.  So happy
hacking.

@author Richard Stallman
@end quotation

produces

People sometimes ask me if it is a sin in the Church of Emacs to use vi. Using a free version of vi is not a sin; it is a penance. So happy hacking.

7.3 @indentedblock: Indented text blocks ¶

The @indentedblock environment is similar to @quotation, except that text is only indented on the left (and there is no optional argument for an author). Thus, the text font remains unchanged, and text is gathered and filled as usual, but the left margin is increased. For example:

This is an example of text written between an @indentedblock command and an @end indentedblock command. The @indentedblock environment can contain any text or other commands desired.

This is written in the Texinfo source as:

@indentedblock
This is an example ...
@end indentedblock

7.4 @example: Example Text ¶

The @example environment is used to indicate computer input or output that is not part of the running text. If you want to embed code fragments within sentences, use the @code command or its relatives instead (see @code{sample-code}).

Write an @example command at the beginning of a line by itself. Mark the end of the block with @end example. For example,

@example
cp foo @var{dest1}; \
 cp foo @var{dest2}
@end example

produces

cp foo dest1; \
 cp foo dest2

The output uses a fixed-width font and is indented. Each line in the input file is a line in the output; that is, the source text is not filled. Extra spaces and blank lines are significant. Texinfo commands are expanded; if you want the output to be the input verbatim, use the @verbatim environment instead (see @verbatim: Literal Text).

Examples are often, logically speaking, “in the middle” of a paragraph, and the text that continues afterwards should not be indented, as in the example above. The @noindent command prevents a piece of text from being indented as if it were a new paragraph (see @noindent: Omitting Indentation).

If you wish to use the normal roman font for a code comment, you can use the @r command (see Fonts for Printing).

You may optionally give arguments to the @example command, separated by commas if there is more than one. In the HTML output, any such arguments are output as class names, prefixed by the string ‘user-’. This may be useful for adding syntax highlighting to manuals for code samples.

We recommend that when you give multiple arguments to @example, you use the first argument to specify the language of the code (e.g. ‘C’, ‘lisp’, ‘Cplusplus’). You may find uses for other arguments, such as providing a formatting hint or marking code samples for extraction and further processing, but for now nothing definitive is recommended. Perhaps this will change in future Texinfo releases.

Caution: Do not use tabs in the lines of an example! (Or anywhere else in Texinfo, except in verbatim environments.) TeX treats tabs as single spaces, and that is not what they look like.

7.5 @verbatim: Literal Text ¶

Use the @verbatim environment for printing of text that may contain special characters or commands that should not be interpreted, such as computer input or output (@example interprets its text as regular Texinfo commands). This is especially useful for including automatically generated files in a Texinfo manual.

In general, the output will be just the same as the input. No character substitutions are made, e.g., all spaces and blank lines are significant, including tabs. The text is typeset in a fixed-width font, and not indented or filled.

Write a @verbatim command at the beginning of a line by itself. This line will disappear from the output. Mark the end of the verbatim block with an @end verbatim command, also written at the beginning of a line by itself. The @end verbatim will also disappear from the output.

For example:

@verbatim
{
<tab>@command with strange characters: @'e
expand<tab>me
}
@end verbatim

(where <tab> stands for a literal tab character). This produces:

{
	@command with strange characters: @'e
expand	me
}

Since the lines containing @verbatim and @end verbatim produce no output, typically you should put a blank line before the @verbatim and another blank line after the @end verbatim. Blank lines between the beginning @verbatim and the ending @end verbatim will appear in the output.

You can get a “small” verbatim by enclosing the @verbatim in an @smallformat environment, as shown here:

@smallformat
@verbatim
... still verbatim, but in a smaller font ...
@end verbatim
@end smallformat

Finally, a word of warning: it is not reliable to use @verbatim inside other Texinfo constructs.

See also @verbatiminclude file: Include a File Verbatim.

7.6 @lisp: Marking a Lisp Example ¶

The @lisp command was used for Lisp code:

@lisp
Example lisp code
@end lisp

This is now synonymous with the following:

@example lisp
Example lisp code
@end example

Use @lisp to preserve information regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.

7.7 @display: Examples Using the Text Font ¶

The @display command begins another kind of environment, where the font is left unchanged, not switched to typewriter as with @example. Each line of input still produces a line of output, and the output is still indented.

This is an example of text written between a @display command
and an @end display command.  The @display command
indents the text, but does not fill it.

7.8 @format: Examples Using the Full Line Width ¶

The @format command is similar to @display, except it leaves the text unindented. Like @display, it does not select the fixed-width font. Thus,

@format
This is an example of text written between a @code{@@format} command
and an @code{@@end format} command.  As you can see
from this example,
the @code{@@format} command does not fill the text.
@end format

produces

This is an example of text written between a @format command
and an @end format command.  As you can see
from this example,
the @format command does not fill the text.

7.9 @exdent: Undoing a Line’s Indentation ¶

The @exdent command removes any indentation a line might have. The command is written at the beginning of a line and applies only to the text that follows the command that is on the same line. Do not use braces around the text. The text on an @exdent line is also printed in the roman font where the output format allows this.

@exdent is usually used within examples. Thus,

@example
This line follows an @@example command.
@exdent This line is exdented.
This line follows the exdented line.
The @@end example comes on the next line.
@end example

produces

This line follows an @example command.

This line is exdented.

This line follows the exdented line.
The @end example comes on the next line.

In practice, the @exdent command is rarely used. Usually, you un-indent text by ending the example and returning the page to its normal width.

@exdent does not have an effect in all output formats.

7.10 @flushleft and @flushright ¶

The @flushleft and @flushright commands line up the ends of lines on the left and right margins of a page, but do not fill the text. The commands are written on lines of their own, without braces. The @flushleft and @flushright commands are ended by @end flushleft and @end flushright commands on lines of their own.

For example,

@flushleft
This text is
written flushleft.
@end flushleft

produces

This text is written flushleft.

@flushright produces the type of indentation often used in the return address of letters. For example,

@flushright
Here is an example of text written
flushright.  The @code{@flushright} command
right justifies every line but leaves the
left end ragged.
@end flushright

produces

7.11 @raggedright: Ragged Right Text ¶

The @raggedright fills text as usual, but the text is only justified on the left; the right margin is ragged. The command is written on a line of its own, without braces. The @raggedright command is ended by @end raggedright on a line of its own. This command only has an effect in output formats where text is justified on the left, but not in output formats where text is always set ragged right, such as Info or HTML.

The @raggedright command can be useful with paragraphs containing lists of commands with long names, when it is known in advance that justifying the text on both margins will make the paragraph look bad.

An example (from elsewhere in this manual):

@raggedright
Commands for double and single angle quotation marks:
@code{@@guillemetleft@{@}}, @code{@@guillemetright@{@}},
@code{@@guillemotleft@{@}}, @code{@@guillemotright@{@}},
@code{@@guilsinglleft@{@}}, @code{@@guilsinglright@{@}}.
@end raggedright

produces

7.12 @noindent: Omitting Indentation ¶

An example or other inclusion can break a paragraph into segments. Ordinarily, the formatters indent text that follows an example as a new paragraph. You can prevent this on a case-by-case basis by writing @noindent at the beginning of a line, preceding the continuation text. You can also disable indentation for all paragraphs globally with @paragraphindent (see @paragraphindent: Controlling Paragraph Indentation).

Here is an example showing how to eliminate the normal indentation of the text after an @example, a common situation:

@example
This is an example
@end example

@noindent
This line is not indented.  As you can see, the
beginning of the line is fully flush left with the
line that follows after it.

produces:

This is an example

This line is not indented.  As you can see, the
beginning of the line is fully flush left with the
line that follows after it.

The standard usage of @noindent is just as above: at the beginning of what would otherwise be a paragraph, to eliminate the indentation that normally happens there. It can either be followed by text or be on a line by itself. There is no reason to use it in other contexts, such as in the middle of a paragraph or inside an environment (see Quotations and Examples).

You can control the number of blank lines in the Info file output by adjusting the input as desired: a line containing just @noindent does not generate a blank line, and neither does an @end line for an environment.

Do not put braces after a @noindent command; they are not used, since @noindent is a command used outside of paragraphs (see @-Command Syntax).

7.13 @indent: Forcing Indentation ¶

To complement the @noindent command (see the previous section), Texinfo provides the @indent command to force a paragraph to be indented. For instance, this paragraph (the first in this section) is indented using an @indent command.

And indeed, the first paragraph of a section is the most likely place to use @indent, to override the normal behavior of no indentation there (see @paragraphindent: Controlling Paragraph Indentation). It can either be followed by text or be on a line by itself.

As a special case, when @indent is used in an environment where text is not filled, it produces a paragraph indentation space in the TeX output. (These environments are where a line of input produces a line of output, such as @example and @display; for a summary of all environments, see Block Enclosing Commands.)

Do not put braces after an @indent command; they are not used, since @indent is a command used outside of paragraphs (see @-Command Syntax).

7.14 @cartouche: Rounded Rectangles ¶

Where the output format allows, the @cartouche command draws a box with rounded corners around its contents. In HTML, a normal rectangle is drawn. You can use this command to isolate a portion of the manual from the main flow. You can also further highlight an example or quotation with @cartouche.

For instance, you could write a manual in which one type of example is surrounded by a cartouche for emphasis. For example,

@cartouche
@example
% pwd
/usr/local/share/emacs
@end example
@end cartouche

surrounds the two-line example with a box with rounded corners, in the printed manual.

The output from the example looks like this (if you’re reading this in Info, you’ll see the @cartouche had no effect):

% pwd
/usr/local/share/emacs

@cartouche takes one optional argument, given on the remainder of the line. This text, if present, is the cartouche title. It is output in bold or otherwise emphasized at the beginning of the cartouche, and is centered in some output formats.

The following example illustrates a cartouche with a title:

@cartouche Important
Text explaining something important out of the main
flow of the text.
@end cartouche

The cartouche with a title looks like this:

A cartouche is output on a single page in printed output, similarly to @group (see @group: Prevent Page Breaks).

7.15 @small… Block Commands ¶

In addition to the regular @example and similar commands, Texinfo has “small” example-style commands. These are @smallquotation, @smallindentedblock, @smalldisplay, @smallexample, @smallformat, and @smalllisp.

In most output formats, the @small… commands are equivalent to their non-small companion commands.

In printed output, however, the @small… commands typeset text in a smaller font than the non-small example commands. Thus, for instance, code examples can contain longer lines and still fit on a page without needing to be rewritten.

Mark the end of a @small… block with a corresponding @end small…. For example, pair @smallexample with @end smallexample.

Here is an example of the font used by the @smallexample command (in most output formats, the output will be the same as usual):

... to make sure that you have the freedom to
distribute copies of free software (and charge for
this service if you wish), that you receive source
code or can get it if you want it, that you can
change the software or use pieces of it in new free
programs; and that you know you can do these things.

The @small… commands use the same font style as their normal counterparts: @smallexample and @smalllisp use a fixed-width font, and everything else uses the regular font. They also have the same behavior in other respects—whether filling is done and whether margins are narrowed.

As a general rule, it’s better to just use the regular commands (such as @example instead of @smallexample), unless you have a good reason for it.

8.1 Introducing Lists ¶

Texinfo automatically indents the text in lists or tables, and numbers an enumerated list. This last feature is useful if you modify the list, since you do not need to renumber it yourself.

Numbered lists and tables begin with the appropriate @-command at the beginning of a line, and end with the corresponding @end command on a line by itself. The table and itemized-list commands also require that you write formatting information on the same line as the beginning @-command.

Begin an enumerated list, for example, with an @enumerate command and end the list with an @end enumerate command. Begin an itemized list with an @itemize command, followed on the same line by a formatting command such as @bullet, and end the list with an @end itemize command.

Precede each element of a list with an @item or @itemx command.

Here is an itemized list of the different kinds of table and lists:

• Itemized lists with and without bullets.
• Enumerated lists, using numbers or letters.
• Two-column tables with highlighting.

Here is an enumerated list with the same items:

1. Itemized lists with and without bullets.
2. Enumerated lists, using numbers or letters.
3. Two-column tables with highlighting.

And here is a two-column table with the same items and their @-commands:

@itemize

Itemized lists with and without bullets.

@enumerate

Enumerated lists, using numbers or letters.

@table

@ftable

@vtable

Two-column tables, optionally with indexing.

8.2 @itemize: Making an Itemized List ¶

The @itemize command produces a sequence of “items”, each starting with a bullet or other mark inside the left margin, and generally indented.

Begin an itemized list by writing @itemize at the beginning of a line. Follow the command, on the same line, with a character or a Texinfo command that generates a mark. Usually, you will use @bullet after @itemize, but you can use @minus, or any command or character that results in a single character in the Info file. (When you write the mark command such as @bullet after an @itemize command, you may omit the ‘{}’.) If you don’t specify a mark command, the default is @bullet. If you don’t want any mark at all, but still want logical items, use @w{} (in this case the braces are required).

After the @itemize, write your items, each starting with @item. Text can follow on the same line as the @item. The text of an item can continue for more than one paragraph.

There should be at least one @item inside the @itemize environment. If none are present, texi2any gives a warning. If you just want indented text and not a list of items, use @indentedblock; see @indentedblock: Indented text blocks.

Index entries and comments that are given before an @item including the first, are automatically moved (internally) to after the @item, so the output is as expected. Historically this has been a common practice.

Usually, you should put a blank line between items. This puts a blank line in the Info file. (TeX inserts the proper vertical space in any case.) Except when the entries are very brief, these blank lines make the list look better.

Here is an example of the use of @itemize, followed by the output it produces. @bullet produces an ‘*’ in Info and a round dot in other output formats.

@itemize @bullet
@item
Some text for foo.

@item
Some text
for bar.
@end itemize

This produces:

• Some text for foo.
• Some text for bar.

Itemized lists may be embedded within other itemized lists. Here is a list marked with dashes embedded in a list marked with bullets:

@itemize @bullet
@item
First item.

@itemize @minus
@item
Inner item.

@item
Second inner item.
@end itemize

@item
Second outer item.
@end itemize

This produces:

• First item.
  • Inner item.
  • Second inner item.
• Second outer item.

8.3 @enumerate: Making a Numbered or Lettered List ¶

@enumerate is like @itemize (see @itemize: Making an Itemized List), except that the labels on the items are successive integers or letters instead of bullets.

Write the @enumerate command at the beginning of a line. The command does not require an argument, but accepts either a number or a letter as an option. Without an argument, @enumerate starts the list with the number ‘1’. With a numeric argument, such as ‘3’, the command starts the list with that number. With an upper- or lowercase letter, such as ‘a’ or ‘A’, the command starts the list with that letter.

Write the text of the enumerated list in the same way as an itemized list: write a line starting with @item at the beginning of each item in the enumeration. It is ok to have text following the @item, and the text for an item can continue for several paragraphs.

You should put a blank line between entries in the list. This generally makes it easier to read the Info file.

Here is an example of @enumerate without an argument:

@enumerate
@item
Underlying causes.

@item
Proximate causes.
@end enumerate

This produces:

1. Underlying causes.
2. Proximate causes.

Here is an example with an argument of 3:

@enumerate 3
@item
Predisposing causes.

@item
Precipitating causes.

@item
Perpetuating causes.
@end enumerate

This produces:

3. Predisposing causes.
4. Precipitating causes.
5. Perpetuating causes.

Here is a summary:

1. @enumerate

   Without an argument, produce a numbered list, with the first item numbered 1.

2. @enumerate unsigned-integer

   With an (unsigned) numeric argument, start a numbered list with that number. You can use this to continue a list that you interrupted with other text.

3. @enumerate upper-case-letter

   With an uppercase letter as argument, start a list in which each item is marked by a letter, beginning with that uppercase letter.

4. @enumerate lower-case-letter

   With a lowercase letter as argument, start a list in which each item is marked by a letter, beginning with that lowercase letter.

You can also nest enumerated lists, as in an outline.

8.4 Making a Two-column Table ¶

@table is similar to @itemize (see @itemize: Making an Itemized List), but allows you to specify a name or heading line for each item. The @table command is used to produce two-column tables, and is especially useful for glossaries, explanatory exhibits, and command-line option summaries.

• Using the @table Command
• @ftable and @vtable
• @itemx: Second and Subsequent Items

@table @samp
@item foo
This is the text for
@samp{foo}.

@item bar
Text for @samp{bar}.
@end table

@table @code
@item upcase
@itemx downcase
These two functions accept a character or a string as
argument, and return the corresponding uppercase (lowercase)
character or string.
@end table

8.5 @multitable: Multi-column Tables ¶

@multitable allows you to construct tables with any number of columns, with each column having any width you like.

You define the column widths on the @multitable line itself, and write each row of the actual table following an @item command, with columns separated by a @tab command. Finally, @end multitable completes the table. Details in the sections below.

• Multitable Column Widths
• Multitable Rows

@multitable @columnfractions .15 .45 .4
@headitem Key @tab Command @tab Description
@item C-x 2
@tab @code{split-window-vertically}
@tab Split the selected window into two windows,
with one above the other.
@item C-x 3
@tab @code{split-window-horizontally}
@tab Split the selected window into two windows
positioned side by side.
@item C-Mouse-2
@tab
@tab In the mode line or scroll bar of a window,
split that window.
@end multitable

9.1 Floats ¶

A float is a display which is set off from the main text. It is typically labeled as being a “Figure”, “Table”, “Example”, or some similar type.

A float is so-named because, in principle, it can be moved to the bottom or top of the current page, or to a following page, in the printed output. (Floating does not make sense in other output formats.) In every output format except for LaTeX, however, this floating is unfortunately not yet implemented. Instead, the floating material is simply output at the current location, more or less as if it were an @group (see @group: Prevent Page Breaks).

• @float [type][,label]: Floating Material
• @caption & @shortcaption
• @listoffloats: Tables of Contents for Floats

@float Figure,fig:ex1
This is an example float.
@end float

@float
An example float, with caption.
@caption{Caption for example float.}
@end float

@float
... as above ...
@shortcaption{Text for list of floats.}
@end float

@node List of Figures
@unnumbered List of Figures
@listoffloats Figure

9.2 Inserting Images ¶

You can insert an image given in an external file with the @image command. Although images can be used anywhere, including the middle of a paragraph, we describe them in this chapter since they are most often part of a displayed figure or example.

• Image Syntax
• Image Scaling

@image{filename[, width[, height[, alttext[, extension]]]]}

@image{ridt,,1in}