1132 lines
49 KiB
Plaintext
1132 lines
49 KiB
Plaintext
This is Info file texi.info, produced by Makeinfo-1.55 from the input
|
||
file texi.texi.
|
||
|
||
This file documents Texinfo, a documentation system that uses a
|
||
single source file to produce both on-line information and a printed
|
||
manual.
|
||
|
||
Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
|
||
Inc.
|
||
|
||
This is the second edition of the Texinfo documentation,
|
||
and is consistent with version 2 of `texinfo.tex'.
|
||
|
||
Permission is granted to make and distribute verbatim copies of this
|
||
manual provided the copyright notice and this permission notice are
|
||
preserved on all copies.
|
||
|
||
Permission is granted to copy and distribute modified versions of
|
||
this manual under the conditions for verbatim copying, provided that
|
||
the entire resulting derived work is distributed under the terms of a
|
||
permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this
|
||
manual into another language, under the above conditions for modified
|
||
versions, except that this permission notice may be stated in a
|
||
translation approved by the Free Software Foundation.
|
||
|
||
|
||
File: texi.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
|
||
|
||
Texinfo
|
||
*******
|
||
|
||
Texinfo is a documentation system that uses a single source file to
|
||
produce both on-line information and printed output.
|
||
|
||
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.
|
||
|
||
This is Edition 2.18 of the Texinfo documentation, 26 March 1993,
|
||
for Texinfo Version 2.
|
||
|
||
* Menu:
|
||
|
||
* Copying:: Your rights.
|
||
* Overview:: Texinfo in brief.
|
||
* Texinfo Mode:: How to use 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?
|
||
* Structuring:: How to create chapters, sections, subsections,
|
||
appendices, and other parts.
|
||
* Nodes:: How to write nodes.
|
||
* Menus:: How to write menus.
|
||
* Cross References:: How to write cross references.
|
||
* Marking Text:: How to mark words and phrases as code,
|
||
keyboard input, meta-syntactic
|
||
variables, and the like.
|
||
* Quotations and Examples:: How to write quotations, examples, etc.
|
||
* Lists and Tables:: How to write lists and tables.
|
||
* Indices:: How to create indices.
|
||
* Insertions:: How to insert @-signs, braces, etc.
|
||
* Glyphs:: How to indicate results of evaluation,
|
||
expansion of macros, errors, etc.
|
||
* Breaks:: How to force and prevent line and page breaks.
|
||
* Definition Commands:: How to describe functions and the like
|
||
in a uniform manner.
|
||
* Footnotes:: How to write footnotes.
|
||
* Conditionals:: How to specify text for either TeX or Info.
|
||
* Format/Print Hardcopy:: How to convert a Texinfo file to a file
|
||
for printing and how to print that file.
|
||
* Create an Info File:: Convert a Texinfo file into an Info file.
|
||
* Install an Info File:: Make an Info file accessible to users.
|
||
* Command List:: All the Texinfo @-commands.
|
||
* Tips:: Hints on how to write a Texinfo document.
|
||
* Sample Texinfo File:: A sample Texinfo file to look at.
|
||
* Sample Permissions:: Tell readers they have the right to copy
|
||
and distribute.
|
||
* Include Files:: How to incorporate other Texinfo files.
|
||
* Headings:: How to write page headings and footings.
|
||
* Catching Mistakes:: How to find formatting mistakes.
|
||
* Refilling Paragraphs:: All about paragraph refilling.
|
||
* Command Syntax:: A description of @-Command syntax.
|
||
* Obtaining TeX:: How to Obtain TeX.
|
||
* New Features:: Texinfo second edition features.
|
||
* Command and Variable Index:: A menu containing commands and variables.
|
||
* Concept Index:: A menu covering many topics.
|
||
|
||
-- The Detailed Node Listing --
|
||
|
||
Overview of Texinfo
|
||
|
||
* Using Texinfo:: Create a conventional printed book
|
||
or an Info file.
|
||
* 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:: How to write comments and mark regions that
|
||
the formatting commands will ignore.
|
||
* Minimum:: What a Texinfo file must have.
|
||
* Six Parts:: Usually, a Texinfo file has six parts.
|
||
* Short Sample:: A short sample Texinfo file.
|
||
* Acknowledgements::
|
||
|
||
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
|
||
|
||
* Four Parts:: Four parts begin a Texinfo file.
|
||
* Sample Beginning:: Here is a sample beginning for a Texinfo file.
|
||
* Header:: The very beginning of a Texinfo file.
|
||
* Info Summary and Permissions:: Summary and copying permissions for Info.
|
||
* Titlepage & Copyright Page:: Creating the title and copyright pages.
|
||
* The Top Node:: Creating the `Top' node and master menu.
|
||
* Software Copying Permissions:: Ensure that you and others continue to
|
||
have the right to use and share software.
|
||
|
||
The 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.
|
||
* setchapternewpage:: Start chapters on right-hand pages.
|
||
* paragraphindent:: An option to specify paragraph indentation.
|
||
* End of Header:: Formatting a region requires this.
|
||
|
||
The 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 & Permissions:: How to write the copyright notice and
|
||
include copying permissions.
|
||
* end titlepage:: Turn on page headings after the title and
|
||
copyright pages.
|
||
* headings on off:: An option for turning headings on and off
|
||
and double or single sided printing.
|
||
|
||
The `Top' Node and Master Menu
|
||
|
||
* Title of Top Node:: Sketch what the file is about.
|
||
* Master Menu Parts:: A master menu has three or more parts.
|
||
|
||
Ending a Texinfo File
|
||
|
||
* Printing Indices & Menus:: How to print an index in hardcopy and
|
||
generate index menus in Info.
|
||
* Contents:: How to create a table of contents.
|
||
* 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.
|
||
* makeinfo top:: The `@top' command, part of the `Top' node.
|
||
* chapter::
|
||
* unnumbered & appendix::
|
||
* majorheading & chapheading::
|
||
* section::
|
||
* unnumberedsec appendixsec heading::
|
||
* subsection::
|
||
* unnumberedsubsec appendixsubsec subheading::
|
||
* subsubsection:: Commands for the lowest level sections.
|
||
|
||
Nodes
|
||
|
||
* Two Paths:: Different commands to structure
|
||
Info output and printed output.
|
||
* Node Menu Illustration:: A diagram, and sample nodes and menus.
|
||
* node:: How to write a node, in detail.
|
||
* makeinfo Pointer Creation:: How to create node pointers with `makeinfo'.
|
||
|
||
The `@node' Command
|
||
|
||
* Node Names:: How to choose node and pointer names.
|
||
* Writing a Node:: How to write an `@node' line.
|
||
* Node Line Tips:: Keep names short.
|
||
* Node Line Requirements:: Keep names unique, without @-commands.
|
||
* First Node:: How to write a `Top' node.
|
||
* makeinfo top command:: How to use the `@top' command.
|
||
* Top Node Summary:: Write a brief description for readers.
|
||
|
||
Menus
|
||
|
||
* Menu Location:: Put a menu in a short node.
|
||
* 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.
|
||
|
||
`@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 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:: How to indicate code.
|
||
* kbd:: How to show keyboard input.
|
||
* key:: How to specify keys.
|
||
* samp:: How to show a literal sequence of characters.
|
||
* var:: How to indicate a metasyntactic variable.
|
||
* file:: How to indicate the name of a file.
|
||
* dfn:: How to specify a definition.
|
||
* cite:: How to refer to a book that is not in Info.
|
||
|
||
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:: Use different constructs for
|
||
different purposes.
|
||
* quotation:: How to write a quotation.
|
||
* example:: How to write an example in a fixed-width font.
|
||
* noindent:: How to prevent paragraph indentation.
|
||
* Lisp Example:: How to illustrate Lisp code.
|
||
* smallexample & smalllisp:: Forms for the `@smallbook' option.
|
||
* display:: How to write an example in the current font.
|
||
* format:: How to write an example that does not narrow
|
||
the margins.
|
||
* exdent:: How to undo the indentation of a line.
|
||
* flushleft & flushright:: How to push text flushleft or flushright.
|
||
* cartouche:: How to draw cartouches around examples.
|
||
|
||
Making 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.
|
||
|
||
Making a Two-column Table
|
||
|
||
* table:: How to construct a two-column table.
|
||
* ftable vtable:: How to construct a two-column table
|
||
with automatic indexing.
|
||
* itemx:: How to put more entries in the first column.
|
||
|
||
Creating Indices
|
||
|
||
* Index Entries:: Choose different words for index entries.
|
||
* Predefined Indices:: Use different indices for different kinds
|
||
of entry.
|
||
* 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
|
||
default font of the merged-to index.
|
||
|
||
Special Insertions
|
||
|
||
* Braces Atsigns Periods:: How to insert braces, `@' and periods.
|
||
* dmn:: How to format a dimension.
|
||
* Dots Bullets:: How to insert dots and bullets.
|
||
* TeX and copyright:: How to insert the TeX logo
|
||
and the copyright symbol.
|
||
* minus:: How to insert a minus sign.
|
||
|
||
Inserting `@', Braces, and Periods
|
||
|
||
* Inserting An Atsign::
|
||
* Inserting Braces:: How to insert `{' and `}'
|
||
* Controlling Spacing:: How to insert the right amount of space
|
||
after punctuation within a sentence.
|
||
|
||
Inserting Ellipsis, Dots, and Bullets
|
||
|
||
* dots:: How to insert dots ...
|
||
* bullet:: How to insert a bullet.
|
||
|
||
Inserting TeX and the Copyright Symbol
|
||
|
||
* tex:: How to insert the TeX logo.
|
||
* copyright symbol:: How to use `@copyright'{}.
|
||
|
||
Glyphs for Examples
|
||
|
||
* Glyphs Summary::
|
||
* result:: How to show the result of expression.
|
||
* expansion:: How to indicate an expansion.
|
||
* Print Glyph:: How to indicate printed output.
|
||
* Error Glyph:: How to indicate an error message.
|
||
* Equivalence:: How to indicate equivalence.
|
||
* Point Glyph:: How to indicate the location of point.
|
||
|
||
Making and Preventing Breaks
|
||
|
||
* Break Commands:: Cause and prevent splits.
|
||
* Line Breaks:: How to force a single line to use two lines.
|
||
* w:: How to prevent unwanted line breaks.
|
||
* sp:: How to insert blank lines.
|
||
* page:: How to force the start of a new page.
|
||
* group:: How to prevent unwanted page breaks.
|
||
* need:: Another way to prevent unwanted page breaks.
|
||
|
||
Definition Commands
|
||
|
||
* Def Cmd Template:: How to structure a description using a
|
||
definition command.
|
||
* Optional Arguments:: How to handle optional and repeated arguments.
|
||
* deffnx:: How to group two or more `first' lines.
|
||
* Def Cmds in Detail:: All the definition commands.
|
||
* Def Cmd Conventions:: Conventions for writing definitions.
|
||
* Sample Function Definition::
|
||
|
||
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.
|
||
* Abstract Objects:: Commands for object-oriented programming.
|
||
* Data Types:: The definition command for data types.
|
||
|
||
Conditionally Visible Text
|
||
|
||
* Conditional Commands:: How to specify text for Info or TeX.
|
||
* Using Ordinary TeX Commands:: You can use any and all TeX commands.
|
||
* set clear value:: How to designate which text to format (for
|
||
both Info and TeX); and how to set a
|
||
flag to a string that you can insert.
|
||
|
||
`@set', `@clear', and `@value'
|
||
|
||
* ifset ifclear:: Format a region if a flag is set.
|
||
* value:: Replace a flag with a string.
|
||
* value Example:: An easy way to update edition information.
|
||
|
||
Format and Print Hardcopy
|
||
|
||
* Use TeX:: Use TeX to format for hardcopy.
|
||
* Shell Format & Print:: How to format and print a hardcopy manual
|
||
with shell commands.
|
||
* 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 you need to do to 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 European A4 paper.
|
||
* Cropmarks and Magnification:: How to print marks to indicate the size
|
||
of pages and how to print scaled up output.
|
||
|
||
Creating an Info File
|
||
|
||
* makeinfo advantages:: `makeinfo' provides better error checking.
|
||
* Invoking makeinfo:: How to run `makeinfo' from a shell.
|
||
* makeinfo options:: Specify fill-column and other options.
|
||
* Pointer Validation:: How to check that pointers point somewhere.
|
||
* 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.
|
||
|
||
Sample Permissions
|
||
|
||
* Inserting Permissions:: How to put permissions in your document.
|
||
* ifinfo Permissions:: Sample `ifinfo' copying permissions.
|
||
* Titlepage Permissions:: Sample Titlepage copying permissions.
|
||
|
||
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 File Requirements:: What `texinfo-multiple-files-update' expects.
|
||
* 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.
|
||
|
||
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.
|
||
|
||
Formatting 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.
|
||
|
||
Second Edition Features
|
||
|
||
* New Texinfo Mode Commands:: The updating commands are especially useful.
|
||
* New Commands:: Many newly described @-commands.
|
||
|
||
|
||
File: texi.info, Node: Copying, Next: Overview, Prev: Top, Up: Top
|
||
|
||
Texinfo Copying Conditions
|
||
**************************
|
||
|
||
The programs currently being distributed that relate to Texinfo
|
||
include portions of GNU Emacs, plus other separate programs (including
|
||
`makeinfo', `info', `texindex', and `texinfo.tex'). These programs are
|
||
"free"; this means that everyone is free to use them and free to
|
||
redistribute them on a free basis. The Texinfo-related programs are
|
||
not in the public domain; they are copyrighted and there are
|
||
restrictions on their distribution, but these restrictions are designed
|
||
to permit everything that a good cooperating citizen would want to do.
|
||
What is not allowed is to try to prevent others from further sharing
|
||
any version of these programs that they might get from you.
|
||
|
||
Specifically, we want to make sure that you have the right to give
|
||
away copies of the programs that relate to Texinfo, that you receive
|
||
source code or else can get it if you want it, that you can change these
|
||
programs or use pieces of them in new free programs, and that you know
|
||
you can do these things.
|
||
|
||
To make sure that everyone has such rights, we have to forbid you to
|
||
deprive anyone else of these rights. For example, if you distribute
|
||
copies of the Texinfo related programs, you must give the recipients all
|
||
the rights that you have. You must make sure that they, too, receive or
|
||
can get the source code. And you must tell them their rights.
|
||
|
||
Also, for our own protection, we must make certain that everyone
|
||
finds out that there is no warranty for the programs that relate to
|
||
Texinfo. If these programs are modified by someone else and passed on,
|
||
we want their recipients to know that what they have is not what we
|
||
distributed, so that any problems introduced by others will not reflect
|
||
on our reputation.
|
||
|
||
The precise conditions of the licenses for the programs currently
|
||
being distributed that relate to Texinfo are found in the General Public
|
||
Licenses that accompany them.
|
||
|
||
|
||
File: texi.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: Top
|
||
|
||
Overview of Texinfo
|
||
*******************
|
||
|
||
"Texinfo"(1) is a documentation system that uses a single source
|
||
file to produce both on-line information and printed output. This
|
||
means that instead of writing two different documents, one for the
|
||
on-line help or other on-line information and the other for a typeset
|
||
manual or other printed work, you need write only one document. When
|
||
the work is revised, you need revise only one document. (You can read
|
||
the on-line information, known as an "Info file", with an Info
|
||
documentation-reading program.)
|
||
|
||
* Menu:
|
||
|
||
* Using Texinfo:: Create a conventional printed book
|
||
or an Info file.
|
||
* 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:: How to write comments and mark regions that
|
||
the formatting commands will ignore.
|
||
* Minimum:: What a Texinfo file must have.
|
||
* Six Parts:: Usually, a Texinfo file has six parts.
|
||
* Short Sample:: A short sample Texinfo file.
|
||
* Acknowledgements::
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) Note that the first syllable of "Texinfo" is pronounced like
|
||
"speck", not "hex". This odd pronunciation is derived from, but is not
|
||
the same as, the pronunciation of TeX. In the word TeX, the `X' is
|
||
actually the Greek letter "chi" rather than the English letter "ex".
|
||
Pronounce TeX as if the `X' were the last sound in the name `Bach'; but
|
||
pronounce Texinfo as if the `x' were a `k'. Spell "Texinfo" with a
|
||
capital "T" and write the other letters in lower case.
|
||
|
||
|
||
File: texi.info, Node: Using Texinfo, Next: Info Files, Up: Overview
|
||
|
||
Using Texinfo
|
||
=============
|
||
|
||
Using Texinfo, you can create a printed document with the normal
|
||
features of a book, including chapters, sections, cross references, and
|
||
indices. From the same Texinfo source file, you can create a
|
||
menu-driven, on-line Info file with nodes, menus, cross references, and
|
||
indices. You can, if you wish, make the chapters and sections of the
|
||
printed document correspond to the nodes of the on-line information;
|
||
and you use the same cross references and indices for both the Info
|
||
file and the printed work. `The GNU Emacs Manual' is a good example of
|
||
a Texinfo file, as is this manual.
|
||
|
||
To make a printed document, you process a Texinfo source file with
|
||
the TeX typesetting program. This creates a DVI file that you can
|
||
typeset and print as a book or report. (Note that the Texinfo language
|
||
is completely different from TeX's usual language, PlainTeX, which
|
||
Texinfo replaces.) If you do not have TeX, but do have `troff' or
|
||
`nroff', you can use the `texi2roff' program instead.
|
||
|
||
To make an Info file, you process a Texinfo source file with the
|
||
`makeinfo' utility or Emacs's `texinfo-format-buffer' command; this
|
||
creates an Info file that you can install on-line.
|
||
|
||
TeX and `texi2roff' work with many types of printer; similarly, Info
|
||
works with almost every type of computer terminal. This power makes
|
||
Texinfo a general purpose system, but brings with it a constraint,
|
||
which is that a Texinfo file may contain only the customary
|
||
"typewriter" characters (letters, numbers, spaces, and punctuation
|
||
marks) but no special graphics.
|
||
|
||
A Texinfo file is a plain ASCII file containing text and
|
||
"@-commands" (words preceded by an `@') that tell the typesetting and
|
||
formatting programs what to do. You may edit a Texinfo file with any
|
||
text editor; but it is especially convenient to use GNU Emacs since
|
||
that editor has a special mode, called Texinfo mode, that provides
|
||
various Texinfo-related features. (*Note Texinfo Mode::.)
|
||
|
||
Before writing a Texinfo source file, you should become familiar with
|
||
the Info documentation reading program and learn about nodes, menus,
|
||
cross references, and the rest. (*note info: (info)Top, for more
|
||
information.)
|
||
|
||
You can use Texinfo to create both on-line help and printed manuals;
|
||
moreover, Texinfo is freely redistributable. For these reasons, Texinfo
|
||
is the format in which documentation for GNU utilities and libraries is
|
||
written.
|
||
|
||
|
||
File: texi.info, Node: Info Files, Next: Printed Books, Prev: Using Texinfo, Up: Overview
|
||
|
||
Info files
|
||
==========
|
||
|
||
An Info file is a Texinfo file formatted so that the Info
|
||
documentation reading program can operate on it. (`makeinfo' and
|
||
`texinfo-format-buffer' are two commands that convert a Texinfo file
|
||
into an Info file.)
|
||
|
||
Info files are divided into pieces called "nodes", each of which
|
||
contains the discussion of one topic. Each node has a name, and
|
||
contains both text for the user to read and pointers to other nodes,
|
||
which are identified by their names. The Info program displays one node
|
||
at a time, and provides commands with which the user can move to other
|
||
related nodes.
|
||
|
||
*note info: (info)Top, for more information about using Info.
|
||
|
||
Each node of an Info file may have any number of child nodes that
|
||
describe subtopics of the node's topic. The names of child nodes are
|
||
listed in a "menu" within the parent node; this allows you to use
|
||
certain Info commands to move to one of the child nodes. Generally, an
|
||
Info file is organized like a book. If a node is at the logical level
|
||
of a chapter, its child nodes are at the level of sections; likewise,
|
||
the child nodes of sections are at the level of subsections.
|
||
|
||
All the children of any one parent are linked together in a
|
||
bidirectional chain of `Next' and `Previous' pointers. The `Next'
|
||
pointer provides a link to the next section, and the `Previous' pointer
|
||
provides a link to the previous section. This means that all the nodes
|
||
that are at the level of sections within a chapter are linked together.
|
||
Normally the order in this chain is the same as the order of the
|
||
children in the parent's menu. Each child node records the parent node
|
||
name as its `Up' pointer. The last child has no `Next' pointer, and the
|
||
first child has the parent both as its `Previous' and as its `Up'
|
||
pointer.(1)
|
||
|
||
The book-like structuring of an Info file into nodes that correspond
|
||
to chapters, sections, and the like is a matter of convention, not a
|
||
requirement. The `Up', `Previous', and `Next' pointers of a node can
|
||
point to any other nodes, and a menu can contain any other nodes.
|
||
Thus, the node structure can be any directed graph. But it is usually
|
||
more comprehensible to follow a structure that corresponds to the
|
||
structure of chapters and sections in a printed book or report.
|
||
|
||
In addition to menus and to `Next', `Previous', and `Up' pointers,
|
||
Info provides pointers of another kind, called references, that can be
|
||
sprinkled throughout the text. This is usually the best way to
|
||
represent links that do not fit a hierarchical structure.
|
||
|
||
Usually, you will design a document so that its nodes match the
|
||
structure of chapters and sections in the printed output. But there
|
||
are times when this is not right for the material being discussed.
|
||
Therefore, Texinfo uses separate commands to specify the node structure
|
||
for the Info file and the section structure for the printed output.
|
||
|
||
Generally, you enter an Info file through a node that by convention
|
||
is called `Top'. This node normally contains just a brief summary of
|
||
the file's purpose, and a large menu through which the rest of the file
|
||
is reached. From this node, you can either traverse the file
|
||
systematically by going from node to node, or you can go to a specific
|
||
node listed in the main menu, or you can search the index menus and
|
||
then go directly to the node that has the information you want.
|
||
|
||
If you want to read through an Info file in sequence, as if it were a
|
||
printed manual, you can get the whole file with the advanced Info
|
||
command `g* RET'. (*note Advanced Info commands: (info)Expert.)
|
||
|
||
The `dir' file in the `info' directory serves as the departure point
|
||
for the whole Info system. From it, you can reach the `Top' nodes of
|
||
each of the documents in a complete Info system.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) In some documents, the first child has no `Previous' pointer.
|
||
Occasionally, the last child has the node name of the next following
|
||
higher level node as its `Next' pointer.
|
||
|
||
|
||
File: texi.info, Node: Printed Books, Next: Formatting Commands, Prev: Info Files, Up: Overview
|
||
|
||
Printed Books
|
||
=============
|
||
|
||
A Texinfo file can be formatted and typeset as a printed book or
|
||
manual. To do this, you need TeX, a powerful, sophisticated typesetting
|
||
program written by Donald Knuth.(1)
|
||
|
||
A Texinfo-based book is similar to any other typeset, printed work:
|
||
it can have a title page, copyright page, table of contents, and
|
||
preface, as well as chapters, numbered or unnumbered sections and
|
||
subsections, page headers, cross references, footnotes, and indices.
|
||
|
||
You can use Texinfo to write a book without ever having the intention
|
||
of converting it into on-line information. You can use Texinfo for
|
||
writing a printed novel, and even to write a printed memo, although
|
||
this latter application is not recommended since electronic mail is so
|
||
much easier.
|
||
|
||
TeX is a general purpose typesetting program. Texinfo provides a
|
||
file called `texinfo.tex' that contains information (definitions or
|
||
"macros") that TeX uses when it typesets a Texinfo file.
|
||
(`texinfo.tex' tells TeX how to convert the Texinfo @-commands to TeX
|
||
commands, which TeX can then process to create the typeset document.)
|
||
`texinfo.tex' contains the specifications for printing a document.
|
||
|
||
Most often, documents are printed on 8.5 inch by 11 inch pages
|
||
(216mm by 280mm; this is the default size), but you can also print for
|
||
7 inch by 9.25 inch pages (178mm by 235mm; the `@smallbook' size) or on
|
||
European A4 size paper (`@afourpaper'). (*Note Printing "Small" Books:
|
||
smallbook. Also, see *Note Printing on A4 Paper: A4 Paper.)
|
||
|
||
By changing the parameters in `texinfo.tex', you can change the size
|
||
of the printed document. In addition, you can change the style in
|
||
which the printed document is formatted; for example, you can change the
|
||
sizes and fonts used, the amount of indentation for each paragraph, the
|
||
degree to which words are hyphenated, and the like. By changing the
|
||
specifications, you can make a book look dignified, old and serious, or
|
||
light-hearted, young and cheery.
|
||
|
||
TeX is freely distributable. It is written in a dialect of Pascal
|
||
called WEB and can be compiled either in Pascal or (by using a
|
||
conversion program that comes with the TeX distribution) in C. (*Note
|
||
TeX Mode: (emacs)TeX Mode, for information about TeX.)
|
||
|
||
TeX is very powerful and has a great many features. Because a
|
||
Texinfo file must be able to present information both on a
|
||
character-only terminal in Info form and in a typeset book, the
|
||
formatting commands that Texinfo supports are necessarily limited.
|
||
|
||
*Note How to Obtain TeX: Obtaining TeX.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) You can also use the `texi2roff' program if you do not have
|
||
TeX; since Texinfo is designed for use with TeX, `texi2roff' is not
|
||
described here. `texi2roff' is part of the standard GNU distribution.
|
||
|
||
|
||
File: texi.info, Node: Formatting Commands, Next: Conventions, Prev: Printed Books, Up: Overview
|
||
|
||
@-commands
|
||
==========
|
||
|
||
In a Texinfo file, the commands that tell TeX how to typeset the
|
||
printed manual and tell `makeinfo' and `texinfo-format-buffer' how to
|
||
create an Info file are preceded by `@'; they are called "@-commands".
|
||
For example, `@node' is the command to indicate a node and `@chapter'
|
||
is the command to indicate the start of a chapter.
|
||
|
||
*Please note:* All the @-commands, with the exception of the
|
||
`@TeX{}' command, must be written entirely in lower case.
|
||
|
||
The Texinfo @-commands are a strictly limited set of constructs. The
|
||
strict limits make it possible for Texinfo files to be understood both
|
||
by TeX and by the code that converts them into Info files. You can
|
||
display Info files on any terminal that displays alphabetic and numeric
|
||
characters. Similarly, you can print the output generated by TeX on a
|
||
wide variety of printers.
|
||
|
||
Depending on what they do or what arguments(1) they take, you need
|
||
to write @-commands on lines of their own or as part of sentences:
|
||
|
||
* Write a command such as `@noindent' at the beginning of a line as
|
||
the only text on the line. (`@noindent' prevents the beginning of
|
||
the next line from being indented as the beginning of a paragraph.)
|
||
|
||
* Write a command such as `@chapter' at the beginning of a line
|
||
followed by the command's arguments, in this case the chapter
|
||
title, on the rest of the line. (`@chapter' creates chapter
|
||
titles.)
|
||
|
||
* Write a command such as `@dots{}' wherever you wish but usually
|
||
within a sentence. (`@dots{}' creates dots ...)
|
||
|
||
* Write a command such as `@code{SAMPLE-CODE}' wherever you wish
|
||
(but usually within a sentence) with its argument, SAMPLE-CODE in
|
||
this example, between the braces. (`@code' marks text as being
|
||
code.)
|
||
|
||
* Write a command such as `@example' at the beginning of a line of
|
||
its own; write the body-text on following lines; and write the
|
||
matching `@end' command, `@end example' in this case, at the
|
||
beginning of a line of its own after the body-text. (`@example'
|
||
... `@end example' indents and typesets body-text as an example.)
|
||
|
||
As a general rule, a command requires braces if it mingles among other
|
||
text; but it does not need braces if it starts a line of its own. The
|
||
non-alphabetic commands, such as `@:', are exceptions to the rule; they
|
||
do not need braces.
|
||
|
||
As you gain experience with Texinfo, you will rapidly learn how to
|
||
write the different commands: the different ways to write commands make
|
||
it easier to write and read Texinfo files than if all commands followed
|
||
exactly the same syntax. (For details about @-command syntax, see
|
||
*Note @-Command Syntax: Command Syntax.)
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) The word "argument" comes from the way it is used in
|
||
mathematics and does not refer to a disputation between two people; it
|
||
refers to the information presented to the command. According to the
|
||
`Oxford English Dictionary', the word derives from the Latin for "to
|
||
make clear, prove"; thus it came to mean `the evidence offered as
|
||
proof', which is to say, `the information offered', which led to its
|
||
mathematical meaning. In its other thread of derivation, the word came
|
||
to mean `to assert in a manner against which others may make counter
|
||
assertions', which led to the meaning of `argument' as a disputation.
|
||
|
||
|
||
File: texi.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview
|
||
|
||
General Syntactic Conventions
|
||
=============================
|
||
|
||
All ASCII printing characters except `@', `{' and `}' can appear in
|
||
a Texinfo file and stand for themselves. `@' is the escape character
|
||
which introduces commands. `{' and `}' should be used only to surround
|
||
arguments to certain commands. To put one of these special characters
|
||
into the document, put an `@' character in front of it, like this:
|
||
`@@', `@{', and `@}'.
|
||
|
||
It is customary in TeX to use doubled single-quote characters to
|
||
begin and end quotations: ` ` and ' ' (but without a space between the
|
||
two single-quote characters). This convention should be followed in
|
||
Texinfo files. TeX converts doubled single-quote characters to left-
|
||
and right-hand doubled quotation marks and Info converts doubled
|
||
single-quote characters to ASCII double-quotes: ` ` and ' ' to " .
|
||
|
||
Use three hyphens in a row, `---', for a dash--like this. In TeX, a
|
||
single or even a double hyphen produces a printed dash that is shorter
|
||
than the usual typeset dash. Info reduces three hyphens to two for
|
||
display on the screen.
|
||
|
||
To prevent a paragraph from being indented in the printed manual, put
|
||
the command `@noindent' on a line by itself before the paragraph.
|
||
|
||
If you mark off a region of the Texinfo file with the `@iftex' and
|
||
`@end iftex' commands, that region will appear only in the printed
|
||
copy; in that region, you can use certain commands borrowed from
|
||
PlainTeX that you cannot use in Info. Likewise, if you mark off a
|
||
region with the `@ifinfo' and `@end ifinfo' commands, that region will
|
||
appear only in the Info file; in that region, you can use Info commands
|
||
that you cannot use in TeX. (*Note Conditionals::.)
|
||
|
||
*Caution:* Do not use tabs in a Texinfo file! TeX uses
|
||
variable-width fonts, which means that it cannot predefine a tab
|
||
to work in all circumstances. Consequently, TeX treats tabs like
|
||
single spaces, and that is not what they look like.
|
||
|
||
To avoid this problem, Texinfo mode causes GNU Emacs to insert
|
||
multiple spaces when you press the TAB key.
|
||
|
||
Also, you can run `untabify' in Emacs to convert tabs in a region
|
||
to multiple spaces.
|
||
|
||
|
||
File: texi.info, Node: Comments, Next: Minimum, Prev: Conventions, Up: Overview
|
||
|
||
Comments
|
||
========
|
||
|
||
You can write comments in a Texinfo file that will not appear in
|
||
either the Info file or the printed manual by using the `@comment'
|
||
command (which may be abbreviated to `@c'). Such comments are for the
|
||
person who reads the Texinfo file. All the text on a line that follows
|
||
either `@comment' or `@c' is a comment; the rest of the line does not
|
||
appear in either the Info file or the printed manual. (Often, you can
|
||
write the `@comment' or `@c' in the middle of a line, and only the text
|
||
that follows after the `@comment' or `@c' command does not appear; but
|
||
some commands, such as `@settitle' and `@setfilename', work on a whole
|
||
line. You cannot use `@comment' or `@c' in a line beginning with such
|
||
a command.)
|
||
|
||
You can write long stretches of text that will not appear in either
|
||
the Info file or the printed manual by using the `@ignore' and `@end
|
||
ignore' commands. Write each of these commands on a line of its own,
|
||
starting each command at the beginning of the line. Text between these
|
||
two commands does not appear in the processed output. You can use
|
||
`@ignore' and `@end ignore' for writing comments. Often, `@ignore' and
|
||
`@end ignore' is used to enclose a part of the copying permissions that
|
||
applies to the Texinfo source file of a document, but not to the Info
|
||
or printed version of the document.
|
||
|
||
|
||
File: texi.info, Node: Minimum, Next: Six Parts, Prev: Comments, Up: Overview
|
||
|
||
What a Texinfo File Must Have
|
||
=============================
|
||
|
||
By convention, the names of Texinfo files end with one of the
|
||
extensions `.texinfo', `.texi', or `.tex'. The longer extension is
|
||
preferred since it describes more clearly to a human reader the nature
|
||
of the file. The shorter extensions are for operating systems that
|
||
cannot handle long file names.
|
||
|
||
In order to be made into a printed manual and an Info file, a
|
||
Texinfo file *must* begin with lines like this:
|
||
|
||
\input texinfo
|
||
@setfilename INFO-FILE-NAME
|
||
@settitle NAME-OF-MANUAL
|
||
|
||
The contents of the file follow this beginning, and then you *must* end
|
||
a Texinfo file with a line like this:
|
||
|
||
@bye
|
||
|
||
The `\input texinfo' line tells TeX to use the `texinfo.tex' file,
|
||
which tells TeX how to translate the Texinfo @-commands into TeX
|
||
typesetting commands. (Note the use of the backslash, `\'; this is
|
||
correct for TeX.) The `@setfilename' line provides a name for the Info
|
||
file and the `@settitle' line specifies a title for the page headers (or
|
||
footers) of the printed manual.
|
||
|
||
The `@bye' line at the end of the file on a line of its own tells
|
||
the formatters that the file is ended and to stop formatting.
|
||
|
||
Usually, you will not use quite such a spare format, but will include
|
||
mode setting and start-of-header and end-of-header lines at the
|
||
beginning of a Texinfo file, like this:
|
||
|
||
\input texinfo @c -*-texinfo-*-
|
||
@c %**start of header
|
||
@setfilename INFO-FILE-NAME
|
||
@settitle NAME-OF-MANUAL
|
||
@c %**end of header
|
||
|
||
In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo
|
||
mode when you edit the file.
|
||
|
||
The `@c' lines which surround the `@setfilename' and `@settitle'
|
||
lines are optional, but you need them in order to run TeX or Info on
|
||
just part of the file. (*Note Start of Header::, for more information.)
|
||
|
||
Furthermore, you will usually provide a Texinfo file with a title
|
||
page, indices, and the like. But the minimum, which can be useful for
|
||
short documents, is just the three lines at the beginning and the one
|
||
line at the end.
|
||
|
||
|
||
File: texi.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview
|
||
|
||
Six Parts of a Texinfo File
|
||
===========================
|
||
|
||
Generally, a Texinfo file contains more than the minimal beginning
|
||
and end--it usually contains six parts:
|
||
|
||
1. Header
|
||
The "Header" names the file, tells TeX which definitions' file to
|
||
use, and performs other "housekeeping" tasks.
|
||
|
||
2. Summary Description and Copyright
|
||
The "Summary Description and Copyright" segment describes the
|
||
document and contains the copyright notice and copying permissions
|
||
for the Info file. The segment must be enclosed between `@ifinfo'
|
||
and `@end ifinfo' commands so that the formatters place it only in
|
||
the Info file.
|
||
|
||
3. Title and Copyright
|
||
The "Title and Copyright" segment contains the title and copyright
|
||
pages and copying permissions for the printed manual. The segment
|
||
must be enclosed between `@titlepage' and `@end titlepage'
|
||
commands. The title and copyright page appear only in the printed
|
||
manual.
|
||
|
||
4. `Top' Node and Master Menu
|
||
The "Master Menu" contains a complete menu of all the nodes in the
|
||
whole Info file. It appears only in the Info file, in the `Top'
|
||
node.
|
||
|
||
5. Body
|
||
The "Body" of the document may be structured like a traditional
|
||
book or encyclopedia or it may be free form.
|
||
|
||
6. End
|
||
The "End" contains commands for printing indices and generating
|
||
the table of contents, and the `@bye' command on a line of its own.
|
||
|
||
|
||
File: texi.info, Node: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview
|
||
|
||
A Short Sample Texinfo File
|
||
===========================
|
||
|
||
Here is a complete but very short Texinfo file, in 6 parts. The
|
||
first three parts of the file, from `\input texinfo' through to `@end
|
||
titlepage', look more intimidating than they are. Most of the material
|
||
is standard boilerplate; when you write a manual, simply insert the
|
||
names for your own manual in this segment. (*Note Beginning a File::.)
|
||
|
||
In the following, the sample text is *indented*; comments on it are
|
||
not. The complete file, without any comments, is shown in *Note Sample
|
||
Texinfo File::.
|
||
|
||
Part 1: Header
|
||
--------------
|
||
|
||
The header does not appear in either the Info file or the
|
||
printed output. It sets various parameters, including the
|
||
name of the Info file and the title used in the header.
|
||
|
||
\input texinfo @c -*-texinfo-*-
|
||
@c %**start of header
|
||
@setfilename sample.info
|
||
@settitle Sample Document
|
||
@c %**end of header
|
||
|
||
@setchapternewpage odd
|
||
|
||
Part 2: Summary Description and Copyright
|
||
-----------------------------------------
|
||
|
||
The summary description and copyright segment does not
|
||
appear in the printed document.
|
||
|
||
@ifinfo
|
||
This is a short example of a complete Texinfo file.
|
||
|
||
Copyright @copyright{} 1990 Free Software Foundation, Inc.
|
||
@end ifinfo
|
||
|
||
Part 3: Titlepage and Copyright
|
||
-------------------------------
|
||
|
||
The titlepage segment does not appear in the Info file.
|
||
|
||
@titlepage
|
||
@sp 10
|
||
@comment The title is printed in a large font.
|
||
@center @titlefont{Sample Title}
|
||
|
||
@c The following two commands start the copyright page.
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
Copyright @copyright{} 1990 Free Software Foundation, Inc.
|
||
@end titlepage
|
||
|
||
Part 4: `Top' Node and Master Menu
|
||
----------------------------------
|
||
|
||
The `Top' node contains the master menu for the Info file.
|
||
Since a printed manual uses a table of contents rather than
|
||
a menu, the master menu appears only in the Info file.
|
||
|
||
@node Top, First Chapter, (dir), (dir)
|
||
@comment node-name, next, previous, up
|
||
|
||
@menu
|
||
* First Chapter:: The first chapter is the
|
||
only chapter in this sample.
|
||
* Concept Index:: This index has two entries.
|
||
@end menu
|
||
|
||
Part 5: The Body of the Document
|
||
---------------------------------
|
||
|
||
The body segment contains all the text of the document, but not the
|
||
indices or table of contents. This example illustrates a node and a
|
||
chapter containing an enumerated list.
|
||
|
||
@node First Chapter, Concept Index, Top, Top
|
||
@comment node-name, next, previous, up
|
||
@chapter First Chapter
|
||
@cindex Sample index entry
|
||
|
||
This is the contents of the first chapter.
|
||
@cindex Another sample index entry
|
||
|
||
Here is a numbered list.
|
||
|
||
@enumerate
|
||
@item
|
||
This is the first item.
|
||
|
||
@item
|
||
This is the second item.
|
||
@end enumerate
|
||
|
||
The @code{makeinfo} and @code{texinfo-format-buffer}
|
||
commands transform a Texinfo file such as this into
|
||
an Info file; and @TeX{} typesets it for a printed
|
||
manual.
|
||
|
||
Part 6: The End of the Document
|
||
-------------------------------
|
||
|
||
The end segment contains commands both for generating an index in a node
|
||
and unnumbered chapter of its own and for generating the table of
|
||
contents; and it contains the `@bye' command that marks the end of the
|
||
document.
|
||
|
||
@node Concept Index, , First Chapter, Top
|
||
@comment node-name, next, previous, up
|
||
@unnumbered Concept Index
|
||
|
||
@printindex cp
|
||
|
||
@contents
|
||
@bye
|
||
|
||
The Results
|
||
-----------
|
||
|
||
Here is what the contents of the first chapter of the sample look
|
||
like:
|
||
|
||
This is the contents of the first chapter.
|
||
|
||
Here is a numbered list.
|
||
|
||
1. This is the first item.
|
||
|
||
2. This is the second item.
|
||
|
||
The `makeinfo' and `texinfo-format-buffer' commands transform a
|
||
Texinfo file such as this into an Info file; and TeX typesets it
|
||
for a printed manual.
|
||
|
||
|
||
File: texi.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview
|
||
|
||
Acknowledgements
|
||
================
|
||
|
||
Richard M. Stallman wrote Edition 1.0 of this manual.
|
||
Robert J. Chassell revised and extended it, starting with Edition 1.1.
|
||
|
||
Our thanks go out to all who helped improve this work, particularly
|
||
to Francois Pinard and David D. Zuhn, who tirelessly recorded and
|
||
reported mistakes and obscurities; our special thanks go to
|
||
Melissa Weisshaus for her frequent and often tedious reviews of nearly
|
||
similar editions. Our mistakes are our own.
|
||
|