GNU Texinfo 4.13

Texinfo

This manual is for GNU Texinfo (version 4.13, 18 September 2008), a documentation system that can produce both online information and a printed manual from a single source.

The first part of this master menu lists the major nodes in this Info document, including the @-command and concept indices. The rest of the menu lists all the lower level nodes in the document.

• Copying Conditions: Your rights.
• Overview: Texinfo in brief.
• Texinfo Mode: Using the GNU Emacs Texinfo mode.
• Beginning a File: What is at the beginning of a Texinfo file?
• Ending a File: What is at the end of a Texinfo file?
• Structuring: Creating chapters, sections, appendices, etc.
• Nodes: Writing nodes, the basic unit of Texinfo.
• Menus: Writing menus.
• Cross References: Writing cross references.
• Marking Text: Marking words and phrases as code, keyboard input, meta-syntactic variables, and the like.
• Quotations and Examples: Block quotations, examples, etc.
• Lists and Tables: Itemized or numbered lists, and tables.
• Special Displays: Floating figures and footnotes.
• Indices: Creating indices.
• Insertions: Inserting @-signs, braces, etc.
• Breaks: Forcing or preventing line and page breaks.
• Definition Commands: Describing functions and the like uniformly.
• Conditionals: Specifying text for only some output cases.
• Internationalization: Supporting languages other than English.
• Defining New Texinfo Commands: User-defined macros and aliases.
• Hardcopy: Output for paper, with TeX.
• Creating and Installing Info Files: Details on Info output.
• Generating HTML: Details on HTML output.
• Command List: All the Texinfo @-commands.
• Tips: Hints on how to write a Texinfo document.
• Sample Texinfo Files: Complete examples, including full texts.
• Include Files: How to incorporate other Texinfo files.
• Headings: How to write page headings and footings.
• Catching Mistakes: How to find formatting mistakes.
• GNU Free Documentation License: Copying this manual.
• Command and Variable Index: A menu containing commands and variables.
• General Index: A menu covering many topics.

--- The Detailed Node Listing ---

Overview of Texinfo

• Reporting Bugs: Submitting effective bug reports.
• Using Texinfo: Create printed or online output.
• Output Formats: Overview of the supported output formats.
• Info Files: What is an Info file?
• Printed Books: Characteristics of a printed book or manual.
• Formatting Commands: @-commands are used for formatting.
• Conventions: General rules for writing a Texinfo file.
• Comments: Writing comments and ignored text in general.
• Minimum: What a Texinfo file must have.
• Six Parts: Usually, a Texinfo file has six parts.
• Short Sample: A short sample Texinfo file.
• History: Acknowledgements, contributors and genesis.

Using Texinfo Mode

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

Updating Nodes and Menus

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

Beginning a Texinfo File

• Sample Beginning: A sample beginning for a Texinfo file.
• Texinfo File Header: The first lines.
• Document Permissions: Ensuring your manual is free.
• Titlepage & Copyright Page: Creating the title and copyright pages.
• Contents: How to create a table of contents.
• The Top Node: Creating the `Top' node and master menu.
• Global Document Commands: Affecting formatting throughout.
• Software Copying Permissions: Ensure that you and others continue to have the right to use and share software.

Texinfo File Header

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

Document Permissions

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

Title and Copyright Pages

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

The `Top' Node and Master Menu

• Top Node Example
• Master Menu Parts

Global Document Commands

• documentdescription: Document summary for the HTML output.
• setchapternewpage: Start chapters on right-hand pages.
• paragraphindent: Specify paragraph indentation.
• firstparagraphindent: Suppress indentation of the first paragraph.
• exampleindent: Specify environment indentation.

Ending a Texinfo File

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

Chapter Structuring

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

Nodes

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

The @node Command

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

Menus

• Menu Location: Menus go at the ends of short nodes.
• Writing a Menu: What is a menu?
• Menu Parts: A menu entry has three parts.
• Less Cluttered Menu Entry: Two part menu entry.
• Menu Example: Two and three part menu entries.
• Other Info Files: How to refer to a different Info file.

Cross References

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

@xref

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

Marking Words and Phrases

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

Indicating Definitions, Commands, etc.

• Useful Highlighting: Highlighting provides useful information.
• code: Indicating program code.
• kbd: Showing keyboard input.
• key: Specifying keys.
• samp: A literal sequence of characters.
• verb: A verbatim sequence of characters.
• var: Indicating metasyntactic variables.
• env: Indicating environment variables.
• file: Indicating file names.
• command: Indicating command names.
• option: Indicating option names.
• dfn: Specifying definitions.
• abbr: Indicating abbreviations.
• acronym: Indicating acronyms.
• indicateurl: Indicating a World Wide Web reference.
• email: Indicating an electronic mail address.

Emphasizing Text

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

Quotations and Examples

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

Lists and Tables

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

Making a Two-column Table

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

@multitable: Multi-column Tables

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

Special Displays

• Floats: Figures, tables, and the like.
• Images: Including graphics and images.
• Footnotes: Writing footnotes.

Floats

• float: Producing floating material.
• caption shortcaption: Specifying descriptions for floats.
• listoffloats: A table of contents for floats.

Inserting Images

• Image Syntax
• Image Scaling

Footnotes

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

Indices

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

Combining Indices

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

Special Insertions

• Atsign Braces Comma: Inserting @ and {} and ,.
• Inserting Quote Characters: Inserting left and right quotes, in code.
• Inserting Space: How to insert the right amount of space within a sentence.
• Inserting Accents: How to insert accents and special characters.
• Inserting Quotation Marks: How to insert quotation marks.
• Dots Bullets: How to insert dots and bullets.
• TeX and copyright: How to insert the TeX logo and the copyright symbol.
• euro: How to insert the Euro currency symbol.
• pounds: How to insert the pounds currency symbol.
• textdegree: How to insert the degrees symbol.
• minus: How to insert a minus sign.
• geq leq: How to insert greater/less-than-or-equal signs.
• math: How to format a mathematical expression.
• Click Sequences: Inserting GUI usage sequences.
• Glyphs: How to indicate results of evaluation, expansion of macros, errors, etc.

Inserting @ and {} and ,

• Inserting an Atsign
• Inserting Braces
• Inserting a Comma

Inserting Space

• Not Ending a Sentence: Sometimes a . doesn't end a sentence.
• Ending a Sentence: Sometimes it does.
• Multiple Spaces: Inserting multiple spaces.
• frenchspacing: Specifying end-of-sentence spacing.
• dmn: How to format a dimension.

Inserting Ellipsis and Bullets

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

Inserting TeX and Legal Symbols: ©, ®

• tex: The TeX logos.
• copyright symbol: The copyright symbol (c in a circle).
• registered symbol: The registered symbol (R in a circle).

Glyphs for Examples

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

Glyphs Summary

• result
• expansion
• Print Glyph
• Error Glyph
• Equivalence
• Point Glyph

Forcing and Preventing Breaks

• Break Commands: Summary of break-related commands.
• Line Breaks: Forcing line breaks.
• - and hyphenation: Helping TeX with hyphenation points.
• allowcodebreaks: Controlling line breaks within @code text.
• w: Preventing unwanted line breaks in text.
• tie: Inserting an unbreakable but varying space.
• sp: Inserting blank lines.
• page: Forcing the start of a new page.
• group: Preventing unwanted page breaks.
• need: Another way to prevent unwanted page breaks.

Definition Commands

• Def Cmd Template: Writing descriptions using definition commands.
• Def Cmd Continuation Lines: Continuing the heading over source lines.
• Optional Arguments: Handling optional and repeated arguments.
• deffnx: Group two or more `first' lines.
• Def Cmds in Detail: Reference for all the definition commands.
• Def Cmd Conventions: Conventions for writing definitions.
• Sample Function Definition: An example.

The Definition Commands

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

Object-Oriented Programming

• Variables
• Methods

Conditionally Visible Text

• Conditional Commands: Text for a given format.
• Conditional Not Commands: Text for any format other than a given one.
• Raw Formatter Commands: Using raw formatter commands.
• set clear value: Variable tests and substitutions.
• Conditional Nesting: Using conditionals inside conditionals.

@set, @clear, and @value

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

Internationalization

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

Defining New Texinfo Commands

• Defining Macros: Defining and undefining new commands.
• Invoking Macros: Using a macro, once you've defined it.
• Macro Details: Limitations of Texinfo macros.
• alias: Command aliases.
• definfoenclose: Customized highlighting.

Formatting and Printing Hardcopy

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

Creating and Installing Info Files

• Creating an Info File
• Installing an Info File

Creating an Info File

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

Installing an Info File

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

Generating HTML

• HTML Translation: Details of the HTML output.
• HTML Splitting: How HTML output is split.
• HTML CSS: Influencing HTML output with Cascading Style Sheets.
• HTML Xref: Cross-references in HTML output.

HTML Cross-references

• Link Basics
• Node Expansion
• Command Expansion
• 8-bit Expansion
• Mismatch

@-Command List

• Command Syntax: General syntax for varieties of @-commands.

Sample Texinfo Files

• Short Sample Texinfo File
• GNU Sample Texts
• Verbatim Copying License
• All-permissive Copying License

GNU Free Documentation License

Include Files

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

Page Headings

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

Formatting Mistakes

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

Finding Badly Referenced Nodes

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

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