texinfo/makeinfo/macros/example.texi

   1 \input texinfo    @c -*-texinfo-*-
   2 @comment %**start of header
   3 @setfilename example.info
   4 @set VERSION 1.58
   5 @paragraphindent none
   6 @comment %**end of header
   7
   8 @include simpledoc.texi
   9
  10 @document {@makeinfo{}, Brian J. Fox,
  11 This file is an extract from the @cite{@texinfo{}} manual.@*
  12 It documents @makeinfo{}\, a program that converts @texinfo{} files into
  13 Info files.
  14 }
  15
  16 @menu
  17 * What is @makeinfo{}?::
  18 * Controlling Paragraph Formats::
  19 * Command Line Options::
  20 * Pointer Validation::
  21 @end menu
  22
  23 @section What is @makeinfo{}?
  24
  25 @iftex
  26 This file documents the use of the @code{makeinfo} program, versions
  27 @value{VERSION} and later.  It is an extract from the @cite{TeXinfo} manual.
  28 @end iftex
  29
  30 @makeinfo{} is a program for converting @dfn{@texinfo{}} files into
  31 @dfn{@Info{}} files.  @texinfo{} is a documentation system that uses a
  32 single source file to produce both on-line information and printed output.
  33
  34 You can read the on-line information using @Info{}; type @code{info} to
  35 learn about @Info{}.
  36 @ifinfo
  37 @xref{Top, Texinfo, Overview of Texinfo, texinfo, Texinfo},
  38 @end ifinfo
  39 @iftex
  40 See the @cite{TeXinfo} manual,
  41 @end iftex
  42 to learn about the TeXinfo documentation system.
  43
  44 @section Controlling Paragraph Formats
  45
  46 In general, @makeinfo{} @dfn{fills} the paragraphs that it outputs
  47 to an @Info{} file.  Filling is the process of breaking and connecting
  48 lines so that lines are the same length as or shorter than the number
  49 specified as the fill column.  Lines are broken between words.  With
  50 @makeinfo{}, you can control:
  51
  52 @itemize @bullet
  53 @item
  54 The width of each paragraph (the @dfn{fill-column}).
  55 @item
  56 The amount of indentation that the first line of
  57 each paragraph receives (the @dfn{paragraph-indentation}).
  58 @end itemize
  59
  60 @section Command Line Options
  61
  62 The following command line options are available for @makeinfo{}.
  63
  64 @need 100
  65 @table @code
  66 @item -D @var{var}
  67 Cause @var{var} to be defined.  This is equivalent to
  68 @code{@@set @var{var}} in the Texinfo file.
  69
  70 @need 150
  71 @item --error-limit @var{limit}
  72 Set the maximum number of errors that @makeinfo{} will report
  73 before exiting (on the assumption that continuing would be useless).
  74 The default number of errors that can be reported before
  75 @makeinfo{} gives up is 100.@refill
  76
  77 @need 150
  78 @item --fill-column @var{width}
  79 Specify the maximum number of columns in a line; this is the right-hand
  80 edge of a line.  Paragraphs that are filled will be filled to this
  81 width.  The default value for @code{fill-column} is 72.
  82
  83 @item --footnote-style @var{style}
  84 Set the footnote style to @var{style}, either @samp{end} for the end
  85 node style or @samp{separate} for the separate node style.  The value
  86 set by this option overrides the value set in a Texinfo file by an
  87 @code{@@footnotestyle} command.  When the footnote style is
  88 @samp{separate}, @makeinfo{} makes a new node containing the
  89 footnotes found in the current node.  When the footnote style is
  90 @samp{end}, @makeinfo{} places the footnote references at the end
  91 of the current node.
  92
  93 @need 150
  94 @item -I @var{dir}
  95 Add @code{dir} to the directory search list for finding files that are
  96 included using the @code{@@include} command.  By default,
  97 @makeinfo{} searches only the current directory.
  98
  99 @need 150
 100 @item --no-headers
 101 Do not include menus or node lines in the output.  This results in an
 102 @sc{ascii} file that you cannot read in Info since it does not contain
 103 the requisite nodes or menus; but you can print such a file in a
 104 single, typewriter-like font and produce acceptable output.
 105
 106 @need 150
 107 @item --no-split
 108 Suppress the splitting stage of @makeinfo{}.  Normally, large
 109 output files (where the size is greater than 70k bytes) are split into
 110 smaller subfiles, each one approximately 50k bytes.  If you specify
 111 @samp{--no-split}, @makeinfo{} will not split up the output
 112 file.
 113
 114 @need 100
 115 @item --no-pointer-validate
 116 @item --no-validate
 117 Suppress the pointer-validation phase of @makeinfo{}.  Normally,
 118 after a Texinfo file is processed, some consistency checks are made to
 119 ensure that cross references can be resolved, etc.
 120 @xref{Pointer Validation}.
 121
 122 @need 150
 123 @item --no-warn
 124 Suppress the output of warning messages.  This does @emph{not}
 125 suppress the output of error messages, only warnings.  You might
 126 want this if the file you are creating has examples of Texinfo cross
 127 references within it, and the nodes that are referenced do not actually
 128 exist.
 129
 130 @item --no-number-footnotes
 131 Supress automatic footnote numbering.  By default, @makeinfo{}
 132 numbers each footnote sequentially in a single node, resetting the
 133 current footnote number to 1 at the start of each node.
 134
 135 @need 150
 136 @item --output @var{file}
 137 @itemx -o @var{file}
 138 Specify that the output should be directed to @var{file} and not to the
 139 file name specified in the @code{@@setfilename} command found in the Texinfo
 140 source.  @var{file} can be the special token @samp{-}, which specifies
 141 standard output.
 142
 143 @need 150
 144 @item --paragraph-indent @var{indent}
 145 Set the paragraph indentation style to @var{indent}.  The value set by
 146 this option overrides the value set in a Texinfo file by an
 147 @code{@@paragraphindent} command.  The value of @var{indent} is
 148 interpreted as follows:
 149
 150 @itemize @bullet
 151 @item
 152 If the value of @var{indent} is @samp{asis}, do not change the
 153 existing indentation at the starts of paragraphs.
 154
 155 @item
 156 If the value of @var{indent} is zero, delete any existing
 157 indentation.
 158
 159 @item
 160 If the value of @var{indent} is greater than zero, indent each
 161 paragraph by that number of spaces.
 162 @end itemize
 163
 164 @need 100
 165 @item --reference-limit @var{limit}
 166 Set the value of the number of references to a node that
 167 @makeinfo{} will make without reporting a warning.  If a node has more
 168 than this number of references in it, @makeinfo{} will make the
 169 references but also report a warning.
 170
 171 @need 150
 172 @item -U @var{var}
 173 Cause @var{var} to be undefined.  This is equivalent to
 174 @code{@@clear @var{var}} in the Texinfo file.
 175
 176 @need 100
 177 @item --verbose
 178 Cause @makeinfo{} to display messages saying what it is doing.
 179 Normally, @makeinfo{} only outputs messages if there are errors or
 180 warnings.
 181
 182 @need 100
 183 @item --version
 184 Report the version number of this copy of @makeinfo{}.
 185 @end table
 186
 187 @section Pointer Validation
 188 @cindex Pointer validation with @makeinfo{}
 189 @cindex Validation of pointers
 190
 191 If you do not suppress pointer-validation (by using the
 192 @samp{--no-pointer-validation} option), @makeinfo{}
 193 will check the validity of the final Info file.  Mostly,
 194 this means ensuring that nodes you have referenced
 195 really exist.  Here is a complete list of what is
 196 checked:
 197
 198 @enumerate
 199 @item
 200 If a `Next', `Previous', or `Up' node reference is a reference to a
 201 node in the current file and is not an external reference such as to
 202 @file{(dir)}, then the referenced node must exist.
 203
 204 @item
 205 In every node, if the `Previous' node is different from the `Up' node,
 206 then the `Previous' node must also be pointed to by a `Next' node.
 207
 208 @item
 209 Every node except the `Top' node must have an `Up' pointer.
 210
 211 @item
 212 The node referenced by an `Up' pointer must contain a reference to the
 213 current node in some manner other than through a `Next' reference.
 214 This includes menu entries and cross references.
 215
 216 @item
 217 If the `Next' reference of a node is not the same as the `Next' reference
 218 of the `Up' reference, then the node referenced by the `Next' pointer
 219 must have a `Previous' pointer that points back to the current node.
 220 This rule allows the last node in a section to point to the first node
 221 of the next chapter.
 222 @end enumerate
 223
 224 @bye