texinfo/makeinfo/makeinfo.texi

   1 \input texinfo    @c -*-texinfo-*-
   2 @comment %**start of header
   3 @setfilename makeinfo.info
   4 @set VERSION 1.61
   5 @paragraphindent none
   6 @comment %**start of header
   7 @comment $Id: makeinfo.texi,v 1.1.1.1 1997/08/21 22:58:08 jason Exp $
   8
   9 @ifinfo
  10 @format
  11 START-INFO-DIR-ENTRY
  12 * makeinfo: (makeinfo).          Making info files from texinfo files.
  13 END-INFO-DIR-ENTRY
  14 @end format
  15 @end ifinfo
  16
  17 @dircategory Texinfo documentation system
  18 @direntry
  19 * makeinfo: (makeinfo).         Convert Texinfo source to Info or plain ASCII.
  20 @end direntry
  21
  22 @ifinfo
  23 This file is an extract from the @cite{Texinfo} manual.@*
  24 It documents Makeinfo, a program that converts Texinfo
  25 files into Info files.
  26
  27 Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc.
  28
  29 Permission is granted to make and distribute verbatim copies of
  30 this manual provided the copyright notice and this permission notice
  31 are preserved on all copies.
  32
  33 @ignore
  34 Permission is granted to process this file through TeX and print the
  35 results, provided the printed document carries copying permission
  36 notice identical to this one except for the removal of this paragraph
  37 (this paragraph not being relevant to the printed manual).
  38
  39 @end ignore
  40 Permission is granted to copy and distribute modified versions of this
  41 manual under the conditions for verbatim copying, provided that the entire
  42 resulting derived work is distributed under the terms of a permission
  43 notice identical to this one.
  44
  45 Permission is granted to copy and distribute translations of this manual
  46 into another language, under the above conditions for modified versions,
  47 except that this permission notice may be stated in a translation approved
  48 by the Free Software Foundation.
  49 @end ifinfo
  50
  51 @titlepage
  52 @title GNU Makeinfo
  53 @author Brian J. Fox and Robert J. Chassell
  54
  55 @page
  56 @vskip 0pt plus 1filll
  57 Copyright @copyright{} 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
  58
  59 Permission is granted to make and distribute verbatim copies of
  60 this manual provided the copyright notice and this permission notice
  61 are preserved on all copies.
  62
  63 Permission is granted to copy and distribute modified versions of this
  64 manual under the conditions for verbatim copying, provided that the entire
  65 resulting derived work is distributed under the terms of a permission
  66 notice identical to this one.
  67
  68 Permission is granted to copy and distribute translations of this manual
  69 into another language, under the above conditions for modified versions,
  70 except that this permission notice may be stated in a translation approved
  71 by the Free Software Foundation.
  72 @end titlepage
  73
  74 @node Top
  75 @chapter What is @code{makeinfo}?
  76
  77 @iftex
  78 This file documents the use of the @code{makeinfo} program, versions
  79 @value{VERSION} and later.  It is an extract from the @cite{Texinfo} manual.
  80 @end iftex
  81
  82 @code{makeinfo} is a program for converting @dfn{Texinfo} files into @dfn{Info}
  83 files.  Texinfo is a documentation system that uses a single source file to
  84 produce both on-line information and printed output.
  85
  86 You can read the on-line information using Info; type @code{info} to
  87 learn about Info.
  88 @ifinfo
  89 @xref{Top, Texinfo, Overview of Texinfo, Texinfo, Texinfo},
  90 @end ifinfo
  91 @iftex
  92 See the @cite{Texinfo} manual,
  93 @end iftex
  94 to learn about the Texinfo documentation system.
  95
  96 @menu
  97 * Formatting Control::          Controlling the width of lines, paragraph
  98                                 indentation, and other similar formatting.
  99
 100 * Options::                     Command line options which control the
 101                                 behaviour of Makeinfo.
 102
 103 * Pointer Validation::          How Makeinfo can help you to track node
 104                                 references through complex Texinfo files.
 105
 106 * Index::                       Index of Concepts.
 107 @end menu
 108
 109 @c Removed this for 3.8 until it's time to rewrite it.
 110 @c * The Macro Facility::          Makeinfo allows the use of @dfn{macros}.
 111
 112 @node Formatting Control
 113 @section Controlling Paragraph Formats
 114
 115 Without any special options, @code{makeinfo} @dfn{fills} the paragraphs that
 116 it outputs to an Info file.  Filling is the process of breaking and connecting
 117 lines so that lines are the same length as or shorter than the number
 118 specified as the fill column.  Lines are broken between words.  With
 119 @code{makeinfo}, you can control:
 120
 121 @itemize @bullet
 122 @item
 123 The width of each paragraph (the @dfn{fill-column}).
 124 @item
 125 The amount of indentation that the first line of
 126 each paragraph receives (the @dfn{paragraph-indentation}).
 127 @end itemize
 128
 129 @node Options
 130 @section Command Line Options
 131
 132 The following command line options are available for @code{makeinfo}.
 133
 134 @need 100
 135 @table @code
 136 @item -D @var{var}
 137 Cause @var{var} to be defined.  This is equivalent to
 138 @code{@@set @var{var}} in the Texinfo file.
 139
 140 @need 150
 141 @item --error-limit @var{limit}
 142 Set the maximum number of errors that @code{makeinfo} will report
 143 before exiting (on the assumption that continuing would be useless).
 144 The default number of errors that can be reported before
 145 @code{makeinfo} gives up is 100.@refill
 146
 147 @need 150
 148 @item --fill-column @var{width}
 149 Specify the maximum number of columns in a line; this is the right-hand
 150 edge of a line.  Paragraphs that are filled will be filled to this
 151 width.  The default value for @code{fill-column} is 72.
 152 @refill
 153
 154 @item --footnote-style @var{style}
 155 Set the footnote style to @var{style}, either @samp{end} for the end
 156 node style or @samp{separate} for the separate node style.  The value
 157 set by this option overrides the value set in a Texinfo file by an
 158 @code{@@footnotestyle} command.  When the footnote style is
 159 @samp{separate}, @code{makeinfo} makes a new node containing the
 160 footnotes found in the current node.  When the footnote style is
 161 @samp{end}, @code{makeinfo} places the footnote references at the end
 162 of the current node.@refill
 163
 164 @need 150
 165 @item -I @var{dir}
 166 Add @code{dir} to the directory search list for finding files that are
 167 included using the @code{@@include} command.  By default,
 168 @code{makeinfo} searches only the current directory.
 169
 170 @need 150
 171 @item --no-headers
 172 Do not include menus or node lines in the output.  This results in an
 173 @sc{ascii} file that you cannot read in Info since it does not contain
 174 the requisite nodes or menus; but you can print such a file in a
 175 single, typewriter-like font and produce acceptable output.
 176
 177 @need 150
 178 @item --no-split
 179 Suppress the splitting stage of @code{makeinfo}.  Normally, large
 180 output files (where the size is greater than 70k bytes) are split into
 181 smaller subfiles, each one approximately 50k bytes.  If you specify
 182 @samp{--no-split}, @code{makeinfo} will not split up the output
 183 file.@refill
 184
 185 @need 100
 186 @item --no-pointer-validate
 187 @item --no-validate
 188 Suppress the pointer-validation phase of @code{makeinfo}.  Normally,
 189 after a Texinfo file is processed, some consistency checks are made to
 190 ensure that cross references can be resolved, etc.
 191 @xref{Pointer Validation}.@refill
 192
 193 @need 150
 194 @item --no-warn
 195 Suppress the output of warning messages.  This does @emph{not}
 196 suppress the output of error messages, only warnings.  You might
 197 want this if the file you are creating has examples of Texinfo cross
 198 references within it, and the nodes that are referenced do not actually
 199 exist.@refill
 200
 201 @item --no-number-footnotes
 202 Supress automatic footnote numbering.  By default, @code{makeinfo}
 203 numbers each footnote sequentially in a single node, resetting the
 204 current footnote number to 1 at the start of each node.
 205
 206 @need 150
 207 @item --output @var{file}
 208 @itemx -o @var{file}
 209 Specify that the output should be directed to @var{file} and not to the
 210 file name specified in the @code{@@setfilename} command found in the Texinfo
 211 source.  @var{file} can be the special token @samp{-}, which specifies
 212 standard output.
 213
 214 @need 150
 215 @item --paragraph-indent @var{indent}
 216 Set the paragraph indentation style to @var{indent}.  The value set by
 217 this option overrides the value set in a Texinfo file by an
 218 @code{@@paragraphindent} command.  The value of @var{indent} is
 219 interpreted as follows:@refill
 220
 221 @itemize @bullet
 222 @item
 223 If the value of @var{indent} is @samp{asis}, do not change the
 224 existing indentation at the starts of paragraphs.@refill
 225
 226 @item
 227 If the value of @var{indent} is zero, delete any existing
 228 indentation.@refill
 229
 230 @item
 231 If the value of @var{indent} is greater than zero, indent each
 232 paragraph by that number of spaces.@refill
 233 @end itemize
 234
 235 @need 100
 236 @item --reference-limit @var{limit}
 237 Set the value of the number of references to a node that
 238 @code{makeinfo} will make without reporting a warning.  If a node has more
 239 than this number of references in it, @code{makeinfo} will make the
 240 references but also report a warning.@refill
 241
 242 @need 150
 243 @item -U @var{var}
 244 Cause @var{var} to be undefined.  This is equivalent to
 245 @code{@@clear @var{var}} in the Texinfo file.
 246
 247 @need 100
 248 @item --verbose
 249 Cause @code{makeinfo} to display messages saying what it is doing.
 250 Normally, @code{makeinfo} only outputs messages if there are errors or
 251 warnings.@refill
 252
 253 @need 100
 254 @item --version
 255 Report the version number of this copy of @code{makeinfo}.@refill
 256
 257 @item --help
 258 Show a summary of the commend line arguments to @code{makeinfo}.
 259 @end table
 260
 261 @node Pointer Validation
 262 @section Pointer Validation
 263 @cindex Pointer validation with @code{makeinfo}
 264 @cindex Validation of pointers
 265
 266 If you do not suppress pointer-validation (by using the
 267 @samp{--no-pointer-validation} option), @code{makeinfo}
 268 will check the validity of the final Info file.  Mostly,
 269 this means ensuring that nodes you have referenced
 270 really exist.  Here is a complete list of what is
 271 checked:@refill
 272
 273 @enumerate
 274 @item
 275 If a `Next', `Previous', or `Up' node reference is a reference to a
 276 node in the current file and is not an external reference such as to
 277 @file{(dir)}, then the referenced node must exist.@refill
 278
 279 @item
 280 In every node, if the `Previous' node is different from the `Up' node,
 281 then the `Previous' node must also be pointed to by a `Next' node.@refill
 282
 283 @item
 284 Every node except the `Top' node must have an `Up' pointer.@refill
 285
 286 @item
 287 The node referenced by an `Up' pointer must contain a reference to the
 288 current node in some manner other than through a `Next' reference.
 289 This includes menu entries and cross references.@refill
 290
 291 @item
 292 If the `Next' reference of a node is not the same as the `Next' reference
 293 of the `Up' reference, then the node referenced by the `Next' pointer
 294 must have a `Previous' pointer that points back to the current node.
 295 This rule allows the last node in a section to point to the first node
 296 of the next chapter.@refill
 297 @end enumerate
 298
 299 @c We don't want to advertise redefining commands.
 300 @c lowersections
 301 @c include macro.texi
 302 @c raisesections
 303
 304 @lowersections
 305 @node Index
 306 @appendix Index
 307 @printindex cp
 308 @raisesections
 309
 310 @contents
 311 @bye