GNU Texinfo 6.7

Short Table of Contents

Table of Contents

Next:   [Contents][Index]

Texinfo

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

• Copying Conditions  Your rights.
• Overview  Texinfo in brief.
• Writing a Texinfo File  Format of a Texinfo source file.
• Beginning and Ending a File  Beginning and end of a Texinfo file.
• Nodes  Writing nodes, the basic unit of Texinfo.
• Chapter Structuring  Creating chapters, sections, appendices, etc.
• 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. 

Appendices
• @-Command Details  Details of the Texinfo @-commands.
• Tips  Hints on how to write a Texinfo document.
• Sample Texinfo Files  Complete examples, including full texts.
• Texinfo Mode  Using the GNU Emacs Texinfo mode.
• 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.
• Output Formats  Overview of the supported output formats.
• Info Files  What is an Info file?
• Printed Books  Characteristics of a printed book or manual.
• Adding Output Formats  Man pages and implementing new formats.
• History  Acknowledgements, contributors and genesis. 

Writing a Texinfo File
• Command Syntax  @-commands are used for formatting.
• Conventions  General rules for writing a Texinfo file.
• Comments  Writing comments and ignored text in general.
• Minimum  What a Texinfo file must have.
• Short Sample  A short sample Texinfo file. 

Beginning and Ending 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.
• Ending a File  What is at the end of a Texinfo file? 

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. 

Nodes
• Texinfo Document Structure  How Texinfo manuals are usually arranged.
• Node Names  How to choose node 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.
• Node Menu Illustration  A diagram, and sample nodes and menus.
• makeinfo Pointer Creation  Letting makeinfo determine node pointers.
• Menus  Listing subordinate nodes. 

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

Chapter Structuring
• Tree Structuring  A manual is like an upside down tree …
• 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. 

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’ …
• Referring to a Manual as a Whole  Refer to an entire manual.
• @ref  A reference for the last part of a sentence.
• @pxref  How to write a parenthetical cross-reference.
• @anchor  Defining arbitrary cross-reference targets
• @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
• 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. 

@url, @uref{url[, text][, replacement]}
• @url Examples  Examples of using all the forms of @url.
• URL Line Breaking  How lines are broken within @url text.
• @url PDF Output Format  A special option to hide links in PDF output.
• PDF Colors  Colorizing urls and other links in PDF output. 

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.
• Advanced Indexing  Advanced indexing commands.
• Printing Indices & Menus  How to print an index in hardcopy and generate index menus in Info.
• 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 Subscripts and Superscripts  Inserting sub/superscripts.
• 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.
• Inserting Unicode  Inserting a Unicode character by code point. 

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 an Ampersand  & and @ampchar{}. 

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. 

Flags: @set, @clear, conditionals, and @value
• @set @value  Expand a flag variable to a string.
• @ifset @ifclear  Format a region if a flag is set.
• @inlineifset @inlineifclear  Brace-delimited flag conditionals.
• @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 texi2dvi  The simplest way to format.
• Format with tex/texindex  Formatting with explicit shell commands.
• 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.
• Magnification  How to print scaled up output.
• PDF Output  Portable Document Format output.
• Obtaining TeX  How to obtain TeX. 

Format with tex/texindex
• Formatting Partial Documents  
• Details of texindex   

texi2any: The Generic Translator for Texinfo
• Reference Implementation  texi2any: the reference implementation.
• Invoking texi2any  Running the translator from a shell.
• texi2any Environment Variables  
• 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  
• HTML  
• 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. 

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

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. 

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
• Info Format Menu  
• Info Format Image  
• Info Format Printindex  
• Info Format Cross Reference  

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:   [Contents][Index]