GNU Texinfo 5.2

Short Table of Contents

Table of Contents

Next: , Up: (dir)   [Contents][Index]

Texinfo

This manual is for GNU Texinfo (version 5.2, 26 September 2013), a documentation system that can produce both online information and a printed manual from a single source using semantic markup.

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?
• Chapter 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.
• Internationalization:  Supporting languages other than English.
• Conditionals:  Specifying text for only some output cases.
• Defining New Texinfo Commands:  User-defined macros and aliases.
• Include Files:  How to incorporate other Texinfo files. 
• Hardcopy:  Output for paper, with TeX.



• Generic Translator texi2any:  texi2any, an all-purpose converter.



• 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.



• Headings:  How to write page headings and footings.



• Catching Mistakes:  How to find mistakes in formatting.



• Info Format Specification:  Technical details of the Info file format.



• 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.



• Adding Output Formats:  Man pages and implementing new formats.



• Texinfo Document Structure:  How Texinfo manuals are usually arranged.



• Info Files:  What is an Info file?



• Printed Books:  Characteristics of a printed book or manual.



• 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.



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.



• Heading Generation:  Turn on page headings after the title and
                                 copyright pages.



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.



• @headings:  An option for turning headings on and off
                                        and double or single sided printing.



• @paragraphindent:  Specify paragraph indentation.



• @firstparagraphindent:  Suppressing first paragraph indentation.



• @exampleindent:  Specify environment indentation.



Ending a Texinfo File


• Printing Indices & Menus:  How to print an index in hardcopy and
                                 generate index menus in Info.



• 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.



• @chapter:  Chapter structuring.



• @unnumbered @appendix:  



• @majorheading @chapheading:  



• @section:  



• @unnumberedsec @appendixsec @heading:  



• @subsection:  



• @unnumberedsubsec @appendixsubsec @subheading:  



• @subsubsection:  Commands for the lowest level sections.



• @part:  Collections of chapters.



• Raise/lower sections:  How to change commands’ hierarchical level.



Nodes


• @node:  Creating nodes, in detail.



• makeinfo Pointer Creation:  Letting makeinfo determine node pointers.



• @anchor:  Defining arbitrary cross reference targets.



• Node Menu Illustration:  A diagram, and sample nodes and menus.



The @node Command


• Node Names:  How to choose node and pointer names.



• Writing a Node:  How to write an @node line.



• Node Line Requirements:  Keep names unique.



• First Node:  How to write a ‘Top’ node.



• @top Command:  How to use the @top command.



Menus


• Menu Location:  Menus go at the ends of 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.



• @url:  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 Text, 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:  Indicating a literal sequence of characters.



• @verb:  Indicating 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 an example url.



• @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.



• @indentedblock:  Block of text indented on left.



• @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.



• @raggedright:  Avoiding justification on the right.



• @noindent:  Preventing paragraph indentation.



• @indent:  Forcing paragraph indentation.



• @cartouche:  Drawing rounded rectangles around text.



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
                                 roman font for the merged-from index.



Special Insertions


• Special Characters:  Inserting @ {} , \ #



• Inserting Quote Characters:  Inserting left and right quotes, in code.



• Inserting Space:  Inserting the right amount of whitespace.



• Inserting Accents:  Inserting accents and special characters.



• Inserting Quotation Marks:  Inserting quotation marks.



• Inserting Math:  Formatting mathematical expressions.



• Glyphs for Text:  Inserting Dots, bullets, currencies, etc.



• Glyphs for Programming:  Indicating results of evaluation,
                                 expansion of macros, errors, etc.



Special Characters: Inserting @ {} , \ #


• Inserting an Atsign:  @@, @atchar{}.



• Inserting Braces:  @{ @}, @l rbracechar{}.



• Inserting a Comma:  , and @comma{}.



• Inserting a Backslash:  \ and @backslashchar{}.



• Inserting a Hashsign:  # and @hashchar{}.



Inserting Space


• Multiple Spaces:  Inserting multiple spaces.



• Not Ending a Sentence:  Sometimes a . doesn’t end a sentence.



• Ending a Sentence:  Sometimes it does.



• @frenchspacing:  Specifying end-of-sentence spacing.



• @dmn:  Formatting a dimension.



Glyphs for Text


• @TeX @LaTeX:  The TeX logos.



• @copyright:  The copyright symbol (c in a circle).



• @registeredsymbol:  The registered symbol (R in a circle).



• @dots:  How to insert ellipses: … and ...



• @bullet:  How to insert a bullet: •



• @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.



Glyphs for Programming


• Glyphs Summary:  



• @result:  How to show the result of expression.



• @expansion:  How to indicate an expansion.



• @print:  How to indicate generated output.



• @error:  How to indicate an error message.



• @equiv:  How to indicate equivalence.



• @point:  How to indicate the location of point.



• Click Sequences:  Inserting GUI usage sequences.



Forcing and Preventing Breaks


• Break Commands:  Summary of break-related commands.



• Line Breaks:  Forcing line breaks.



• @-  @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:  



Internationalization


• @documentlanguage:  Declaring the current language.



• @documentencoding:  Declaring the input encoding.



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.



• Inline Conditionals:  Brace-delimited conditional text.



• @set @clear @value:  Variable tests and substitutions.



• Testing for Texinfo Commands:  Testing if a Texinfo command is available.



• 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.



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.



• External Macro Processors:  #line directives.



External Macro Processors: Line Directives


• #line Directive:  



• TeX:  



• Syntax:  



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.



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.



texi2any: The Generic Translator for Texinfo


• Reference Implementation:  texi2any: the reference implementation.



• Invoking texi2any:  Running the translator from a shell.



• texi2any Printed Output:  Calling texi2dvi.



• Pointer Validation:  How to check that pointers point somewhere.



• Customization Variables:  Configuring texi2any.



• Internationalization of Document Strings:  Translating program-inserted text.



• Invoking pod2texi:  Translating Perl pod to Texinfo.



• texi2html:  An ancestor of texi2any.



Customization Variables


• Commands:  



• Options:  



• Other:  



Creating and Installing Info Files


• Creating an Info File:  



• Installing an Info File:  



Creating an Info File


• makeinfo Advantages:  makeinfo provides better error checking.



• 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:  



• Configuration:  htmlxref.cnf.



• Preserving links:  MANUAL-noderename.cnf.



@-Command List


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



• Command Contexts:  Guidelines for which commands can be used where.



Sample Texinfo Files


• Short Sample Texinfo File:  



• GNU Sample Texts:  



• Verbatim Copying License:  



• All-permissive Copying License:  



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.



Catching 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.



Info Format Specification


• General:  



• Text:  



Info Format General Layout


• Whole:  Split vs. nonsplit manuals.



• Preamble:  



• Indirect:  



• Tag table:  



• Local variables:  



• Regular nodes:  



Info Format Text Constructs


• Menu:  



• Image:  



• Printindex:  



• Xref:  








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










Next: , Up: (dir)   [Contents][Index]