\include texinfo.tex

What is Makeinfo?
*****************

Makeinfo is a program for converting texinfo files into info files.  Texinfo is a documentation language which allows a printed manual and online documentation (an info file) to be produced from a single source file.

This text does not explain how to write a texinfo file.  In order to usefully use this documentation, you should be familiar with the texinfo documentation language, and you should have used an info file reader to read some info files.  A good place to start is with info, a program for reading online documentation.  Just type info to get started. Documentation on the texinfo language is available in the node Texinfo. Type info texinfo to read it.

Controlling Paragraph Formats
=============================

In general, Makeinfo fills the paragraphs that it outputs to the info file.  Filling is the process of breaking up and connecting lines such that the output is nearly justified.  With Makeinfo, you can control:

  * The width of the paragraph (the fill-column).

  * The amount of indentation that the first line of the paragraph gets (the paragraph-indentation).

Command Line Options
====================

The following command line options are available for Makeinfo.

+error-limit NUM
     Sets the maximum number of errors that Makeinfo will print before exiting (on the assumption that continuing would be useless).  The default number of errors that can be printed before Makeinfo gives up on processing the input file is 100.

+fill-column NUM
     Specifies the maximum right-hand edge of a line.  Paragraphs that are filled will be filled to this width.  The default value for fill-column is 72.

+footnote-style STYLE

     Sets the footnote style to STYLE.  STYLE should either be `MN' for `make node', or `EN' for `bottom node'.  When the footnote style is `MN', Makeinfo makes a new node containing the footnotes found in the current node.  When the footnote style is `EN', Makeinfo places the footnote references at the end of the current node.

+no-split
     Suppress the splitting stage of Makeinfo.  In general, large output files (where the size is greater than 70k bytes) are split into smaller subfiles, each one apporximately 50k bytes.  By specifying +no-split, Makeinfo will not split up the output file.

+no-validate
     Suppress the validation phase of Makeinfo.  Normally, after the file is processed, some consistency checks are made to ensure that cross references can be resolved, etc.  See Validation.

+no-warn
     Suppress the output of warning messages.  This does not suppress the output of error messages, simply warnings.  You might want this if the file you are creating has texinfo examples in it, and the nodes that are referenced don't actually exist.

+no-number-footnotes
     Supress the automatic numbering of footnotes.  The default is number each footnote sequentially in a single node, resetting the current footnote number to 1 at the start of each node.

+paragraph-indent NUM
     Sets the paragraph indentation to NUM.  The value of NUM is interpreted as follows:

       * A value of 0 means don't change the existing indentation at the starts of paragraphs.

       * A value less than zero means indent paragraph starts to column zero by deleting the existing indentation.

       * A value greater than zero is the number of spaces to leave at the front of each paragraph start.

+verbose
     Causes Makeinfo to inform you as to what it is doing.  Normally Makeinfo only outputs text if there are errors or warnings.

+version
     Prints outs the version number of Makeinfo.

What makes a valid Info file?
=============================

If you have not suppressed validation (with the +no-validate option), Makeinfo will check the validity of the final info file.  Mostly, this means ensuring that nodes you have referenced really exist.  Here is a complete list of what is checked:

 1. If a node reference such as Prev, Next or Up is a reference to a node in this file (i.e., not an external reference such as `(DIR)'), then the referenced node must exist.

 2. In a given node, if the node referenced by the Prev is different than the node referenced by the Up, then the node referenced by the Prev must have a Next which references this node.

 3. Every node excepting Top must have an Up field.

 4. The node referenced by Up must contain a reference to this node, other than a Next reference.  Obviously, this includes menu items and followed references.

 5. If the Next reference is not the same as the Next reference of the Up reference, then the node referenced by Next must have a Prev reference pointing back at this node.  This rule still allows the last node in a section to point to the first node of the next chapter.

Defaulting the Prev, Next, and Up
=================================

Although the definition of an info file allows a great deal of flexibility, there are some conventions that you are urged to follow. By letting Makeinfo default the Next, Prev, and Up pointers you can follow these conventions with the minimum of effort.

A common error ocurrs when adding a new node to a menu; often the nodes which are referenced in the menu do not point to each other in the same order as they appear in the menu.

Makeinfo helps with this particular problem by defaulting Next, Prev, and Up pointers in a @node command if you leave off these pointers in the command.

The node to receive the defaulted pointers must be followed immediately by a sectioning command, such as @chapter or @section, and must appear in a menu that is one sectioning level or more above the sectioning level that this node is to have.

Here is an example of using this feature.

     @setfilename default-nodes-example.info
     @node Top
     @chapter Introduction
     @menu
     * foo::  the foo node
     * bar::  the bar node
     @end menu

     @node foo
     @section foo
     this is the foo node.

     @node bar
     @section Bar
     This is the Bar node.
     @bye

produces

     Info file default-nodes-example.info, produced by Makeinfo, -*- Text -*-
     from input file default-nodes.texinfo.

     File: default-nodes-example.info,  Node: Top

     Introduction
     ************

     * Menu:

     * foo::  the foo node
     * bar::  the bar node

     File: default-nodes-example.info,  Node: foo,  Next: bar,  Up: Top

     foo
     ===

     this is the foo node.

     File: default-nodes-example.info,  Node: bar,  Prev: foo,  Up: Top

     Bar
     ===

     This is the Bar node.