15627 lines
532 KiB
Plaintext
15627 lines
532 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@comment %**start of header
|
|
@setfilename texi.info
|
|
@settitle Texinfo @value{edition}
|
|
@syncodeindex vr fn
|
|
@c footnotestyle separate
|
|
@c paragraphindent 2
|
|
@smallbook
|
|
@comment %**end of header
|
|
|
|
@ignore
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* Texinfo: (texi.info). The documentation format for the GNU Project.
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
@end ignore
|
|
|
|
@c Set smallbook if printing in smallbook format so the example of the
|
|
@c smallbook font is actually written using smallbook; in bigbook, a kludge
|
|
@c is used for TeX output.
|
|
@c set smallbook
|
|
@clear smallbook
|
|
|
|
@set edition 2.18
|
|
@set update-date 26 March 1993
|
|
@set update-month March 1993
|
|
|
|
@c Experiment with smaller amounts of whitespace between chapters
|
|
@c and sections.
|
|
@tex
|
|
\global\chapheadingskip = 15pt plus 4pt minus 2pt
|
|
\global\secheadingskip = 12pt plus 3pt minus 2pt
|
|
\global\subsecheadingskip = 9pt plus 2pt minus 2pt
|
|
@end tex
|
|
|
|
@c Experiment with smaller amounts of whitespace between paragraphs in
|
|
@c the 8.5 by 11 inch format.
|
|
@ifclear smallbook
|
|
@tex
|
|
\global\parskip 6pt plus 1pt
|
|
@end tex
|
|
@end ifclear
|
|
|
|
@finalout
|
|
|
|
@c Currently undocumented commands, 24 March 1993:
|
|
@c See documentation in `texinfmt.el' file.
|
|
@c
|
|
@c raisesections (Two useful commands.)
|
|
@c lowersections
|
|
@c nwnode (Same as node, but no warnings; for `makeinfo'.)
|
|
@c math (Unsatisfactory TeX definition; no processing for Info.)
|
|
@c definfoenclose (For ifinfo text only; not supported by `makeinfo';
|
|
@c each instance requires a corresponding TeX definition.)
|
|
|
|
@ifinfo
|
|
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 @file{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.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
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.
|
|
@end ifinfo
|
|
|
|
@setchapternewpage odd
|
|
@titlepage
|
|
@c use the new format for titles
|
|
@title Texinfo
|
|
@subtitle The GNU Documentation Format
|
|
@subtitle Edition @value{edition}, for Texinfo Version Two
|
|
@subtitle @value{update-month}
|
|
|
|
@author by Robert J. Chassell and Richard M. Stallman
|
|
|
|
@comment Include the Distribution inside the titlepage so
|
|
@c that headings are turned off.
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1988, 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
|
|
@sp 2
|
|
This is the second edition of the Texinfo documentation,@*
|
|
and is consistent with version 2 of @file{texinfo.tex}.
|
|
@sp 2
|
|
|
|
Published by the Free Software Foundation @*
|
|
675 Massachusetts Avenue, @*
|
|
Cambridge, MA 02139 USA @*
|
|
Printed copies are available for $15 each.@*
|
|
ISBN-1882114-12-4
|
|
|
|
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.
|
|
@sp 2
|
|
Cover art by Etienne Suvasa.
|
|
@end titlepage
|
|
|
|
@ifinfo
|
|
@node Top, Copying, (dir), (dir)
|
|
@top Texinfo
|
|
|
|
Texinfo is a documentation system that uses a single source file to
|
|
produce both on-line information and printed output.@refill
|
|
|
|
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.@refill
|
|
|
|
This is Edition @value{edition} of the Texinfo documentation,
|
|
@w{@value{update-date},} for Texinfo Version 2.
|
|
@end ifinfo
|
|
|
|
@c Here is a spare copy of the chapter menu entry descriptions,
|
|
@c in case they are accidently deleted
|
|
@ignore
|
|
Your rights.
|
|
Texinfo in brief.
|
|
How to use Texinfo mode.
|
|
What is at the beginning of a Texinfo file?
|
|
What is at the end of a Texinfo file?
|
|
How to create chapters, sections, subsections,
|
|
appendices, and other parts.
|
|
How to provide structure for a document.
|
|
How to write nodes.
|
|
How to write menus.
|
|
How to write cross references.
|
|
How to mark words and phrases as code,
|
|
keyboard input, meta-syntactic
|
|
variables, and the like.
|
|
How to write quotations, examples, etc.
|
|
How to write lists and tables.
|
|
How to create indices.
|
|
How to insert @@-signs, braces, etc.
|
|
How to indicate results of evaluation,
|
|
expansion of macros, errors, etc.
|
|
How to force and prevent line and page breaks.
|
|
How to describe functions and the like in a uniform manner.
|
|
How to write footnotes.
|
|
How to specify text for either @TeX{} or Info.
|
|
How to print hardcopy.
|
|
How to create an Info file.
|
|
How to install an Info file
|
|
A list of all the Texinfo @@-commands.
|
|
Hints on how to write a Texinfo document.
|
|
A sample Texinfo file to look at.
|
|
Tell readers they have the right to copy
|
|
and distribute.
|
|
How to incorporate other Texinfo files.
|
|
How to write page headings and footings.
|
|
How to find formatting mistakes.
|
|
All about paragraph refilling.
|
|
A description of @@-Command syntax.
|
|
Texinfo second edition features.
|
|
A menu containing commands and variables.
|
|
A menu covering many topics.
|
|
@end ignore
|
|
|
|
@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 @code{@@titlefont}, @code{@@center},
|
|
and @code{@@sp} commands.
|
|
* title subtitle author:: The @code{@@title}, @code{@@subtitle},
|
|
and @code{@@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 @dots{}
|
|
* Structuring Command Types:: How to divide a manual into parts.
|
|
* makeinfo top:: The @code{@@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 @code{makeinfo}.
|
|
|
|
The @code{@@node} Command
|
|
|
|
* Node Names:: How to choose node and pointer names.
|
|
* Writing a Node:: How to write an @code{@@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 @code{@@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' @dots{}
|
|
* 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.
|
|
|
|
@code{@@xref}
|
|
|
|
* Reference Syntax:: What a reference looks like and requires.
|
|
* One Argument:: @code{@@xref} with one argument.
|
|
* Two Arguments:: @code{@@xref} with two arguments.
|
|
* Three Arguments:: @code{@@xref} with three arguments.
|
|
* Four and Five Arguments:: @code{@@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 @code{@@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{@@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, @samp{@@} 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 @samp{@@}, Braces, and Periods
|
|
|
|
* Inserting An Atsign::
|
|
* Inserting Braces:: How to insert @samp{@{} and @samp{@}}
|
|
* 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 @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 @code{@@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.
|
|
|
|
@code{@@set}, @code{@@clear}, and @code{@@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:: @code{makeinfo} provides better error checking.
|
|
* Invoking makeinfo:: How to run @code{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 @code{makeinfo} from Emacs.
|
|
* texinfo-format commands:: Two Info formatting commands written
|
|
in Emacs Lisp are an alternative
|
|
to @code{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 @samp{ifinfo} copying permissions.
|
|
* Titlepage Permissions:: Sample Titlepage copying permissions.
|
|
|
|
Include Files
|
|
|
|
* Using Include Files:: How to use the @code{@@include} command.
|
|
* texinfo-multiple-files-update:: How to create and update nodes and
|
|
menus when using included files.
|
|
* Include File Requirements:: What @code{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 @code{@@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:: @code{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 @code{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 @code{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.
|
|
@end menu
|
|
|
|
@node Copying, Overview, Top, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Texinfo Copying Conditions
|
|
@cindex Copying conditions
|
|
@cindex Conditions for copying Texinfo
|
|
|
|
The programs currently being distributed that relate to Texinfo include
|
|
portions of GNU Emacs, plus other separate programs (including
|
|
@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
|
|
These programs are @dfn{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.@refill
|
|
|
|
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.@refill
|
|
|
|
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.@refill
|
|
|
|
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.@refill
|
|
|
|
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.@refill
|
|
|
|
@node Overview, Texinfo Mode, Copying, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Overview of Texinfo
|
|
@cindex Overview of Texinfo
|
|
@cindex Texinfo overview
|
|
|
|
@dfn{Texinfo}@footnote{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 @samp{X} is actually the Greek letter ``chi''
|
|
rather than the English letter ``ex''. Pronounce @TeX{} as if the
|
|
@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo
|
|
as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T''
|
|
and write the other letters in lower case.}
|
|
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
|
|
@dfn{Info file}, with an Info documentation-reading program.)@refill
|
|
|
|
@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::
|
|
@end menu
|
|
|
|
@node Using Texinfo, Info Files, , Overview
|
|
@ifinfo
|
|
@heading Using Texinfo
|
|
@end ifinfo
|
|
|
|
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. @cite{The GNU
|
|
Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill
|
|
|
|
To make a printed document, you process a Texinfo source file with the
|
|
@TeX{} typesetting program. This creates a @sc{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, Plain@TeX{}, which
|
|
Texinfo replaces.) If you do not have @TeX{}, but do have
|
|
@code{troff} or @code{nroff}, you can use the @code{texi2roff} program
|
|
instead.@refill
|
|
|
|
To make an Info file, you process a Texinfo source file with the
|
|
@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command;
|
|
this creates an Info file that you can install on-line.@refill
|
|
|
|
@TeX{} and @code{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.@refill
|
|
|
|
A Texinfo file is a plain @sc{ascii} file containing text and
|
|
@dfn{@@-commands} (words preceded by an @samp{@@}) 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. (@xref{Texinfo
|
|
Mode}.)@refill
|
|
|
|
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. (@inforef{Top, info, info},
|
|
for more information.)@refill
|
|
|
|
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.@refill
|
|
|
|
@node Info Files, Printed Books, Using Texinfo, Overview
|
|
@comment node-name, next, previous, up
|
|
@section Info files
|
|
@cindex Info files
|
|
|
|
An Info file is a Texinfo file formatted so that the Info documentation
|
|
reading program can operate on it. (@code{makeinfo}
|
|
and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
|
|
into an Info file.)@refill
|
|
|
|
Info files are divided into pieces called @dfn{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.@refill
|
|
|
|
@ifinfo
|
|
@inforef{Top, info, info}, for more information about using Info.@refill
|
|
@end ifinfo
|
|
|
|
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 @dfn{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.@refill
|
|
|
|
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.@footnote{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.}@refill
|
|
|
|
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.@refill
|
|
|
|
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.@refill
|
|
|
|
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.@refill
|
|
|
|
Generally, you enter an Info file through a node that by convention is
|
|
called @samp{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.@refill
|
|
@c !!! With the standalone Info system you may go to specific nodes
|
|
@c directly..
|
|
|
|
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 @kbd{g* @key{RET}}. (@inforef{Expert, Advanced Info commands,
|
|
info}.)@refill
|
|
|
|
@c !!! dir file may be located in one of many places:
|
|
@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH
|
|
@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH
|
|
@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH
|
|
@c /usr/local/info
|
|
@c /usr/local/lib/info
|
|
The @file{dir} file in the @file{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.@refill
|
|
|
|
@node Printed Books, Formatting Commands, Info Files, Overview
|
|
@comment node-name, next, previous, up
|
|
@section Printed Books
|
|
@cindex Printed book and manual characteristics
|
|
@cindex Manual characteristics, printed
|
|
@cindex Book characteristics, printed
|
|
@cindex Texinfo printed book characteristics
|
|
@cindex Characteristics, printed books or manuals
|
|
|
|
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.@footnote{You can also use the
|
|
@code{texi2roff} program if you do not have @TeX{}; since Texinfo is
|
|
designed for use with @TeX{}, @code{texi2roff} is not described here.
|
|
@code{texi2roff} is part of the standard GNU distribution.}@refill
|
|
|
|
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.@refill
|
|
|
|
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.@refill
|
|
|
|
@TeX{} is a general purpose typesetting program. Texinfo provides a
|
|
file called @file{texinfo.tex} that contains information (definitions or
|
|
@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
|
|
(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
|
|
to @TeX{} commands, which @TeX{} can then process to create the typeset
|
|
document.) @file{texinfo.tex} contains the specifications for printing
|
|
a document.@refill
|
|
|
|
Most often, documents are printed on 8.5 inch by 11 inch
|
|
pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you
|
|
can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
|
|
235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper
|
|
(@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}.
|
|
Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill
|
|
|
|
By changing the parameters in @file{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.@refill
|
|
|
|
@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.
|
|
(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
|
|
about @TeX{}.)@refill
|
|
|
|
@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.@refill
|
|
|
|
@xref{Obtaining TeX, , How to Obtain @TeX{}}.
|
|
|
|
|
|
@node Formatting Commands, Conventions, Printed Books, Overview
|
|
@comment node-name, next, previous, up
|
|
@section @@-commands
|
|
@cindex @@-commands
|
|
@cindex Formatting commands
|
|
|
|
In a Texinfo file, the commands that tell @TeX{} how to typeset the
|
|
printed manual and tell @code{makeinfo} and
|
|
@code{texinfo-format-buffer} how to create an Info file are preceded
|
|
by @samp{@@}; they are called @dfn{@@-commands}. For example,
|
|
@code{@@node} is the command to indicate a node and @code{@@chapter}
|
|
is the command to indicate the start of a chapter.@refill
|
|
|
|
@quotation
|
|
@strong{Please note:} All the @@-commands, with the exception of the
|
|
@code{@@TeX@{@}} command, must be written entirely in lower
|
|
case.@refill
|
|
@end quotation
|
|
|
|
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.@refill
|
|
|
|
Depending on what they do or what arguments@footnote{The word
|
|
@dfn{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 @cite{Oxford
|
|
English Dictionary}, the word derives from the Latin for @dfn{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.} they take, you need to write @@-commands on lines of
|
|
their own or as part of sentences:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Write a command such as @code{@@noindent} at the beginning of a line as
|
|
the only text on the line. (@code{@@noindent} prevents the beginning of
|
|
the next line from being indented as the beginning of a
|
|
paragraph.)@refill
|
|
|
|
@item
|
|
Write a command such as @code{@@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. (@code{@@chapter} creates chapter titles.)@refill
|
|
|
|
@item
|
|
Write a command such as @code{@@dots@{@}} wherever you wish but usually
|
|
within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
|
|
|
|
@item
|
|
Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
|
|
wish (but usually within a sentence) with its argument,
|
|
@var{sample-code} in this example, between the braces. (@code{@@code}
|
|
marks text as being code.)@refill
|
|
|
|
@item
|
|
Write a command such as @code{@@example} at the beginning of a line of
|
|
its own; write the body-text on following lines; and write the matching
|
|
@code{@@end} command, @code{@@end example} in this case, at the
|
|
beginning of a line of its own after the body-text. (@code{@@example}
|
|
@dots{} @code{@@end example} indents and typesets body-text as an
|
|
example.)@refill
|
|
@end itemize
|
|
|
|
@noindent
|
|
@cindex Braces, when to use
|
|
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 @code{@@:}, are exceptions to the rule;
|
|
they do not need braces.@refill
|
|
|
|
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 @ref{Command Syntax, , @@-Command Syntax}.)@refill
|
|
|
|
@node Conventions, Comments, Formatting Commands, Overview
|
|
@comment node-name, next, previous, up
|
|
@section General Syntactic Conventions
|
|
@cindex General syntactic conventions
|
|
@cindex Syntactic conventions
|
|
@cindex Conventions, syntactic
|
|
|
|
All @sc{ascii} printing characters except @samp{@@}, @samp{@{} and
|
|
@samp{@}} can appear in a Texinfo file and stand for themselves.
|
|
@samp{@@} is the escape character which introduces commands.
|
|
@samp{@{} and @samp{@}} should be used only to surround arguments to
|
|
certain commands. To put one of these special characters into the
|
|
document, put an @samp{@@} character in front of it, like this:
|
|
@samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
|
|
|
|
@ifinfo
|
|
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 @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
|
|
@end ifinfo
|
|
@iftex
|
|
It is customary in @TeX{} to use doubled single-quote characters to
|
|
begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This
|
|
convention should be followed in Texinfo files. @TeX{} converts
|
|
doubled single-quote characters to left- and right-hand doubled
|
|
quotation marks, ``like this'', and Info converts doubled single-quote
|
|
characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and
|
|
@w{@tt{ '' }} to @w{@tt{ " }}.@refill
|
|
@end iftex
|
|
|
|
Use three hyphens in a row, @samp{---}, 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.@refill
|
|
|
|
To prevent a paragraph from being indented in the printed manual, put
|
|
the command @code{@@noindent} on a line by itself before the
|
|
paragraph.@refill
|
|
|
|
If you mark off a region of the Texinfo file with the @code{@@iftex}
|
|
and @w{@code{@@end iftex}} commands, that region will appear only in
|
|
the printed copy; in that region, you can use certain commands
|
|
borrowed from Plain@TeX{} that you cannot use in Info. Likewise, if
|
|
you mark off a region with the @code{@@ifinfo} and @code{@@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{}.
|
|
(@xref{Conditionals}.)
|
|
|
|
@cindex Tabs; don't use!
|
|
@quotation
|
|
@strong{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.@refill
|
|
|
|
@noindent
|
|
To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
|
|
spaces when you press the @key{TAB} key.@refill
|
|
|
|
@noindent
|
|
Also, you can run @code{untabify} in Emacs to convert tabs in a region
|
|
to multiple spaces.@refill
|
|
@end quotation
|
|
|
|
@node Comments, Minimum, Conventions, Overview
|
|
@comment node-name, next, previous, up
|
|
@section 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
|
|
@code{@@comment} command (which may be abbreviated to @code{@@c}).
|
|
Such comments are for the person who reads the Texinfo file. All the
|
|
text on a line that follows either @code{@@comment} or @code{@@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 @code{@@comment} or
|
|
@code{@@c} in the middle of a line, and only the text that follows after
|
|
the @code{@@comment} or @code{@@c} command does not appear; but some
|
|
commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
|
|
whole line. You cannot use @code{@@comment} or @code{@@c} in a line
|
|
beginning with such a command.)@refill
|
|
@cindex Comments
|
|
@findex comment
|
|
@findex c @r{(comment)}
|
|
|
|
You can write long stretches of text that will not appear in either
|
|
the Info file or the printed manual by using the @code{@@ignore} and
|
|
@code{@@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 @code{@@ignore} and @code{@@end ignore} for writing
|
|
comments. Often, @code{@@ignore} and @code{@@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.@refill
|
|
@cindex Ignored text
|
|
@cindex Unprocessed text
|
|
@findex ignore
|
|
@c !!! Perhaps include this comment about ignore and ifset:
|
|
@ignore
|
|
Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
|
|
@code{@@ifclear} conditions is ignored in the sense that it will not
|
|
contribute to the formatted output. However, TeX and makeinfo must
|
|
still parse the ignored text, in order to understand when to
|
|
@emph{stop} ignoring text from the source file; that means that you
|
|
will still get error messages if you have invalid Texinfo markup
|
|
within ignored text.
|
|
@end ignore
|
|
|
|
@node Minimum, Six Parts, Comments, Overview
|
|
@comment node-name, next, previous, up
|
|
@section What a Texinfo File Must Have
|
|
@cindex Minimal Texinfo file (requirements)
|
|
@cindex Must have in Texinfo file
|
|
@cindex Required in Texinfo file
|
|
@cindex Texinfo file minimum
|
|
|
|
By convention, the names of Texinfo files end with one of the
|
|
extensions @file{.texinfo}, @file{.texi}, or @file{.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.@refill
|
|
|
|
In order to be made into a printed manual and an Info file, a
|
|
Texinfo file @strong{must} begin with lines like this:@refill
|
|
|
|
@example
|
|
@group
|
|
\input texinfo
|
|
@@setfilename @var{info-file-name}
|
|
@@settitle @var{name-of-manual}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
The contents of the file follow this beginning, and then you @strong{must} end
|
|
a Texinfo file with a line like this:@refill
|
|
|
|
@example
|
|
@@bye
|
|
@end example
|
|
|
|
@findex input @r{(@TeX{} command)}
|
|
@noindent
|
|
The @samp{\input texinfo} line tells @TeX{} to use the
|
|
@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
|
|
@@-commands into @TeX{} typesetting commands. (Note the use of the
|
|
backslash, @samp{\}; this is correct for @TeX{}.) The
|
|
@samp{@@setfilename} line provides a name for the Info file and the
|
|
@samp{@@settitle} line specifies a title for the page headers (or
|
|
footers) of the printed manual.@refill
|
|
|
|
The @code{@@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.@refill
|
|
|
|
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:@refill
|
|
|
|
@example
|
|
@group
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@@c %**start of header
|
|
@@setfilename @var{info-file-name}
|
|
@@settitle @var{name-of-manual}
|
|
@@c %**end of header
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
|
|
Texinfo mode when you edit the file.
|
|
|
|
The @code{@@c} lines which surround the @samp{@@setfilename} and
|
|
@samp{@@settitle} lines are optional, but you need them in order to
|
|
run @TeX{} or Info on just part of the file. (@xref{Start of Header},
|
|
for more information.)@refill
|
|
|
|
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.@refill
|
|
|
|
@node Six Parts, Short Sample, Minimum, Overview
|
|
@comment node-name, next, previous, up
|
|
@section Six Parts of a Texinfo File
|
|
|
|
Generally, a Texinfo file contains more than the minimal
|
|
beginning and end---it usually contains six parts:@refill
|
|
|
|
@table @r
|
|
@item 1. Header
|
|
The @dfn{Header} names the file, tells @TeX{} which definitions' file to
|
|
use, and performs other ``housekeeping'' tasks.@refill
|
|
|
|
@item 2. Summary Description and Copyright
|
|
The @dfn{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 @code{@@ifinfo} and
|
|
@code{@@end ifinfo} commands so that the formatters place it only in the Info
|
|
file.@refill
|
|
|
|
@item 3. Title and Copyright
|
|
The @dfn{Title and Copyright} segment contains the title and copyright pages
|
|
and copying permissions for the printed manual. The segment must be
|
|
enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
|
|
The title and copyright page appear only in the printed @w{manual}.@refill
|
|
|
|
@item 4. `Top' Node and Master Menu
|
|
The @dfn{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.@refill
|
|
|
|
@item 5. Body
|
|
The @dfn{Body} of the document may be structured like a traditional book or
|
|
encyclopedia or it may be free form.@refill
|
|
|
|
@item 6. End
|
|
The @dfn{End} contains commands for printing indices and generating
|
|
the table of contents, and the @code{@@bye} command on a line of its
|
|
own.@refill
|
|
@end table
|
|
|
|
@node Short Sample, Acknowledgements, Six Parts, Overview
|
|
@comment node-name, next, previous, up
|
|
@section A Short Sample Texinfo File
|
|
@cindex Sample Texinfo file
|
|
|
|
Here is a complete but very short Texinfo file, in 6 parts. The first
|
|
three parts of the file, from @samp{\input texinfo} through to
|
|
@samp{@@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. (@xref{Beginning a
|
|
File}.)@refill
|
|
|
|
@noindent
|
|
In the following, the sample text is @emph{indented}; comments on it are
|
|
not. The complete file, without any comments, is shown in
|
|
@ref{Sample Texinfo File}.
|
|
|
|
@subheading Part 1: Header
|
|
|
|
@noindent
|
|
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.
|
|
|
|
@example
|
|
@group
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@@c %**start of header
|
|
@@setfilename sample.info
|
|
@@settitle Sample Document
|
|
@@c %**end of header
|
|
|
|
@@setchapternewpage odd
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Part 2: Summary Description and Copyright
|
|
|
|
@noindent
|
|
The summary description and copyright segment does not@*
|
|
appear in the printed document.
|
|
|
|
@example
|
|
@group
|
|
@@ifinfo
|
|
This is a short example of a complete Texinfo file.
|
|
|
|
Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
|
|
@@end ifinfo
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Part 3: Titlepage and Copyright
|
|
|
|
@noindent
|
|
The titlepage segment does not appear in the Info file.
|
|
|
|
@example
|
|
@group
|
|
@@titlepage
|
|
@@sp 10
|
|
@@comment The title is printed in a large font.
|
|
@@center @@titlefont@{Sample Title@}
|
|
@end group
|
|
|
|
@group
|
|
@@c The following two commands start the copyright page.
|
|
@@page
|
|
@@vskip 0pt plus 1filll
|
|
Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
|
|
@@end titlepage
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Part 4: `Top' Node and Master Menu
|
|
|
|
@noindent
|
|
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.
|
|
|
|
@example
|
|
@group
|
|
@@node Top, First Chapter, (dir), (dir)
|
|
@@comment node-name, next, previous, up
|
|
@end group
|
|
@end example
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
* First Chapter:: The first chapter is the
|
|
only chapter in this sample.
|
|
* Concept Index:: This index has two entries.
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Part 5: The Body of the Document
|
|
|
|
@noindent
|
|
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.@refill
|
|
|
|
@example
|
|
@group
|
|
@@node First Chapter, Concept Index, Top, Top
|
|
@@comment node-name, next, previous, up
|
|
@@chapter First Chapter
|
|
@@cindex Sample index entry
|
|
@end group
|
|
|
|
@group
|
|
This is the contents of the first chapter.
|
|
@@cindex Another sample index entry
|
|
@end group
|
|
|
|
@group
|
|
Here is a numbered list.
|
|
|
|
@@enumerate
|
|
@@item
|
|
This is the first item.
|
|
|
|
@@item
|
|
This is the second item.
|
|
@@end enumerate
|
|
@end group
|
|
|
|
@group
|
|
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.
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Part 6: The End of the Document
|
|
|
|
@noindent
|
|
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 @code{@@bye} command that marks the end of
|
|
the document.@refill
|
|
|
|
@example
|
|
@group
|
|
@@node Concept Index, , First Chapter, Top
|
|
@@comment node-name, next, previous, up
|
|
@@unnumbered Concept Index
|
|
@end group
|
|
|
|
@group
|
|
@@printindex cp
|
|
|
|
@@contents
|
|
@@bye
|
|
@end group
|
|
@end example
|
|
|
|
@subheading The Results
|
|
|
|
Here is what the contents of the first chapter of the sample look like:
|
|
|
|
@sp 1
|
|
@need 700
|
|
@quotation
|
|
This is the contents of the first chapter.
|
|
|
|
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.
|
|
@end quotation
|
|
|
|
@node Acknowledgements, , Short Sample, Overview
|
|
@comment node-name, next, previous, up
|
|
@section Acknowledgements
|
|
|
|
Richard M.@: Stallman wrote Edition 1.0 of this manual.
|
|
@w{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
|
|
@w{Francois Pinard} and @w{David D.@: Zuhn}, who tirelessly recorded
|
|
and reported mistakes and obscurities; our special thanks go to
|
|
@w{Melissa Weisshaus} for her frequent and often tedious reviews of
|
|
nearly similar editions. Our mistakes are our own.
|
|
|
|
@c ignore until mailing lists set up
|
|
@ignore
|
|
Please send suggestions and corrections to:
|
|
|
|
@example
|
|
@group
|
|
@r{Internet address:}
|
|
bug-gnu-texinfo@@prep.ai.mit.edu
|
|
|
|
@r{UUCP path:}
|
|
mit-eddie!prep.ai.mit.edu!bug-gnu-texinfo
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
Please include the manual's edition number in your messages.
|
|
@end ignore
|
|
|
|
@node Texinfo Mode, Beginning a File, Overview, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Using Texinfo Mode
|
|
@cindex Texinfo mode
|
|
@cindex Mode, using Texinfo
|
|
@cindex GNU Emacs
|
|
@cindex Emacs
|
|
|
|
You may edit a Texinfo file with any text editor you choose. A Texinfo
|
|
file is no different from any other @sc{ascii} file. However, GNU Emacs
|
|
comes with a special mode, called Texinfo
|
|
mode, that provides Emacs commands and tools to help ease your work.@refill
|
|
|
|
This chapter describes features of GNU Emacs' Texinfo mode but not any
|
|
features of the Texinfo formatting language. If you are reading this
|
|
manual straight through from the beginning, you may want to skim through
|
|
this chapter briefly and come back to it after reading succeeding
|
|
chapters which describe the Texinfo formatting language in
|
|
detail.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Texinfo Mode Overview, Emacs Editing, , Texinfo Mode
|
|
@ifinfo
|
|
@heading Texinfo Mode Overview
|
|
@end ifinfo
|
|
|
|
Texinfo mode provides special features for working with Texinfo
|
|
files:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Insert frequently used @@commands. @refill
|
|
|
|
@item
|
|
Automatically create @code{@@node} lines.
|
|
|
|
@item
|
|
Show the structure of a Texinfo source file.@refill
|
|
|
|
@item
|
|
Automatically create or update the `Next',@*
|
|
`Previous', and `Up' pointers of a node.
|
|
|
|
@item
|
|
Automatically create or update menus.@refill
|
|
|
|
@item
|
|
Automatically create a master menu.@refill
|
|
|
|
@item
|
|
Format a part or all of a file for Info.@refill
|
|
|
|
@item
|
|
Typeset and print part or all of a file.@refill
|
|
@end itemize
|
|
|
|
Perhaps the two most helpful features are those for inserting frequently
|
|
used @@-commands and for creating node pointers and menus.@refill
|
|
|
|
@node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
|
|
@section The Usual GNU Emacs Editing Commands
|
|
|
|
In most cases, the usual Text mode commands work the same in Texinfo
|
|
mode as they do in Text mode. Texinfo mode adds new editing commands
|
|
and tools to GNU Emacs' general purpose editing features. The major
|
|
difference concerns filling. In Texinfo mode, the paragraph
|
|
separation variable and syntax table are redefined so that Texinfo
|
|
commands that should be on lines of their own are not inadvertently
|
|
included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
|
|
command will refill a paragraph but not mix an indexing command on a
|
|
line adjacent to it into the paragraph.@refill
|
|
|
|
In addition, Texinfo mode sets the @code{page-delimiter} variable to
|
|
the value of @code{texinfo-chapter-level-regexp}; by default, this is
|
|
a regular expression matching the commands for chapters and their
|
|
equivalents, such as appendices. With this value for the page
|
|
delimiter, you can jump from chapter title to chapter title with the
|
|
@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
|
|
(@code{backward-page}) commands and narrow to a chapter with the
|
|
@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
|
|
The GNU Emacs Manual}, for details about the page commands.)@refill
|
|
|
|
You may name a Texinfo file however you wish, but the convention is to
|
|
end a Texinfo file name with one of the three extensions
|
|
@file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is
|
|
preferred, since it is explicit, but a shorter extension may be
|
|
necessary for operating systems that limit the length of file names.
|
|
GNU Emacs automatically enters Texinfo mode when you visit a file with
|
|
a @file{.texinfo} or @file{.texi}
|
|
extension. Also, Emacs switches to Texinfo mode
|
|
when you visit a
|
|
file that has @samp{-*-texinfo-*-} in its first line. If ever you are
|
|
in another mode and wish to switch to Texinfo mode, type @code{M-x
|
|
texinfo-mode}.@refill
|
|
|
|
Like all other Emacs features, you can customize or enhance Texinfo
|
|
mode as you wish. In particular, the keybindings are very easy to
|
|
change. The keybindings described here are the default or standard
|
|
ones.@refill
|
|
|
|
@node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
|
|
@comment node-name, next, previous, up
|
|
@section Inserting Frequently Used Commands
|
|
@cindex Inserting frequently used commands
|
|
@cindex Frequently used commands, inserting
|
|
@cindex Commands, inserting them
|
|
|
|
Texinfo mode provides commands to insert various frequently used
|
|
@@-commands into the buffer. You can use these commands to save
|
|
keystrokes.@refill
|
|
|
|
The insert commands are invoked by typing @kbd{C-c} twice and then the
|
|
first letter of the @@-command:@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-c c
|
|
@itemx M-x texinfo-insert-@@code
|
|
@findex texinfo-insert-@@code
|
|
Insert @code{@@code@{@}} and put the
|
|
cursor between the braces.@refill
|
|
|
|
@item C-c C-c d
|
|
@itemx M-x texinfo-insert-@@dfn
|
|
@findex texinfo-insert-@@dfn
|
|
Insert @code{@@dfn@{@}} and put the
|
|
cursor between the braces.@refill
|
|
|
|
@item C-c C-c e
|
|
@itemx M-x texinfo-insert-@@end
|
|
@findex texinfo-insert-@@end
|
|
Insert @code{@@end} and attempt to insert the correct following word,
|
|
such as @samp{example} or @samp{table}. (This command does not handle
|
|
nested lists correctly, but inserts the word appropriate to the
|
|
immediately preceding list.)@refill
|
|
|
|
@item C-c C-c i
|
|
@itemx M-x texinfo-insert-@@item
|
|
@findex texinfo-insert-@@item
|
|
Insert @code{@@item} and put the
|
|
cursor at the beginning of the next line.@refill
|
|
|
|
@item C-c C-c k
|
|
@itemx M-x texinfo-insert-@@kbd
|
|
@findex texinfo-insert-@@kbd
|
|
Insert @code{@@kbd@{@}} and put the
|
|
cursor between the braces.@refill
|
|
|
|
@item C-c C-c n
|
|
@itemx M-x texinfo-insert-@@node
|
|
@findex texinfo-insert-@@node
|
|
Insert @code{@@node} and a comment line
|
|
listing the sequence for the `Next',
|
|
`Previous', and `Up' nodes.
|
|
Leave point after the @code{@@node}.@refill
|
|
|
|
@item C-c C-c o
|
|
@itemx M-x texinfo-insert-@@noindent
|
|
@findex texinfo-insert-@@noindent
|
|
Insert @code{@@noindent} and put the
|
|
cursor at the beginning of the next line.@refill
|
|
|
|
@item C-c C-c s
|
|
@itemx M-x texinfo-insert-@@samp
|
|
@findex texinfo-insert-@@samp
|
|
Insert @code{@@samp@{@}} and put the
|
|
cursor between the braces.@refill
|
|
|
|
@item C-c C-c t
|
|
@itemx M-x texinfo-insert-@@table
|
|
@findex texinfo-insert-@@table
|
|
Insert @code{@@table} followed by a @key{SPC}
|
|
and leave the cursor after the @key{SPC}.@refill
|
|
|
|
@item C-c C-c v
|
|
@itemx M-x texinfo-insert-@@var
|
|
@findex texinfo-insert-@@var
|
|
Insert @code{@@var@{@}} and put the
|
|
cursor between the braces.@refill
|
|
|
|
@item C-c C-c x
|
|
@itemx M-x texinfo-insert-@@example
|
|
@findex texinfo-insert-@@example
|
|
Insert @code{@@example} and put the
|
|
cursor at the beginning of the next line.@refill
|
|
|
|
@c M-@{ was the binding for texinfo-insert-braces;
|
|
@c in Emacs 19, backward-paragraph will take this binding.
|
|
@item C-c C-c @{
|
|
@itemx M-x texinfo-insert-braces
|
|
@findex texinfo-insert-braces
|
|
Insert @code{@{@}} and put the cursor between the braces.@refill
|
|
|
|
@item C-c C-c @}
|
|
@itemx C-c C-c ]
|
|
@itemx M-x up-list
|
|
@findex up-list
|
|
Move from between a pair of braces forward past the closing brace.
|
|
Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
|
|
is, however, more mnemonic; hence the two keybindings. (Also, you can
|
|
move out from between braces by typing @kbd{C-f}.)@refill
|
|
@end table
|
|
|
|
To put a command such as @w{@code{@@code@{@dots{}@}}} around an
|
|
@emph{existing} word, position the cursor in front of the word and type
|
|
@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
|
|
The value of the prefix argument tells Emacs how many words following
|
|
point to include between braces---1 for one word, 2 for two words, and
|
|
so on. Use a negative argument to enclose the previous word or words.
|
|
If you do not specify a prefix argument, Emacs inserts the @@-command
|
|
string and positions the cursor between the braces. This feature works
|
|
only for those @@-commands that operate on a word or words within one
|
|
line, such as @code{@@kbd} and @code{@@var}.@refill
|
|
|
|
This set of insert commands was created after analyzing the frequency
|
|
with which different @@-commands are used in the @cite{GNU Emacs
|
|
Manual} and the @cite{GDB Manual}. If you wish to add your own insert
|
|
commands, you can bind a keyboard macro to a key, use abbreviations,
|
|
or extend the code in @file{texinfo.el}.@refill
|
|
|
|
@findex texinfo-start-menu-description
|
|
@cindex Menu description, start
|
|
@cindex Description for menu, start
|
|
@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
|
|
command that works differently from the other insert commands. It
|
|
inserts a node's section or chapter title in the space for the
|
|
description in a menu entry line. (A menu entry has three parts, the
|
|
entry name, the node name, and the description. Only the node name is
|
|
required, but a description helps explain what the node is about.
|
|
@xref{Menu Parts, , The Parts of a Menu}.)@refill
|
|
|
|
To use @code{texinfo-start-menu-description}, position point in a menu
|
|
entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
|
|
the title that goes with the node name, and inserts the title as a
|
|
description; it positions point at beginning of the inserted text so you
|
|
can edit it. The function does not insert the title if the menu entry
|
|
line already contains a description.@refill
|
|
|
|
This command is only an aid to writing descriptions; it does not do the
|
|
whole job. You must edit the inserted text since a title tends to use
|
|
the same words as a node name but a useful description uses different
|
|
words.@refill
|
|
|
|
@node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
|
|
@comment node-name, next, previous, up
|
|
@section Showing the Section Structure of a File
|
|
@cindex Showing the section structure of a file
|
|
@cindex Section structure of a file, showing it
|
|
@cindex Structure of a file, showing it
|
|
@cindex Outline of file structure, showing it
|
|
@cindex Contents-like outline of file structure
|
|
@cindex File section structure, showing it
|
|
@cindex Texinfo file section structure, showing it
|
|
|
|
You can show the section structure of a Texinfo file by using the
|
|
@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
|
|
shows the section structure of a Texinfo file by listing the lines
|
|
that begin with the @@-commands for @code{@@chapter},
|
|
@code{@@section}, and the like. It constructs what amounts
|
|
to a table of contents. These lines are displayed in another buffer
|
|
called the @samp{*Occur*} buffer. In that buffer, you can position
|
|
the cursor over one of the lines and use the @kbd{C-c C-c} command
|
|
(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
|
|
in the Texinfo file.@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-s
|
|
@itemx M-x texinfo-show-structure
|
|
@findex texinfo-show-structure
|
|
Show the @code{@@chapter}, @code{@@section}, and such lines of a
|
|
Texinfo file.@refill
|
|
|
|
@item C-c C-c
|
|
@itemx M-x occur-mode-goto-occurrence
|
|
@findex occur-mode-goto-occurrence
|
|
Go to the line in the Texinfo file corresponding to the line under the
|
|
cursor in the @file{*Occur*} buffer.@refill
|
|
@end table
|
|
|
|
If you call @code{texinfo-show-structure} with a prefix argument by
|
|
typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
|
|
@@-commands for @code{@@chapter}, @code{@@section}, and the like,
|
|
but also the @code{@@node} lines. (This is how the
|
|
@code{texinfo-show-structure} command worked without an argument in
|
|
the first version of Texinfo. It was changed because @code{@@node}
|
|
lines clutter up the @samp{*Occur*} buffer and are usually not
|
|
needed.) You can use @code{texinfo-show-structure} with a prefix
|
|
argument to check whether the `Next', `Previous', and `Up' pointers of
|
|
an @code{@@node} line are correct.@refill
|
|
|
|
Often, when you are working on a manual, you will be interested only
|
|
in the structure of the current chapter. In this case, you can mark
|
|
off the region of the buffer that you are interested in with the
|
|
@kbd{C-x n} (@code{narrow-to-region}) command and
|
|
@code{texinfo-show-structure} will work on only that region. To see
|
|
the whole buffer again, use @w{@kbd{C-x w}} (@code{widen}).
|
|
(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
|
|
information about the narrowing commands.)@refill
|
|
|
|
@vindex page-delimiter
|
|
@cindex Page delimiter in Texinfo mode
|
|
In addition to providing the @code{texinfo-show-structure} command,
|
|
Texinfo mode sets the value of the page delimiter variable to match
|
|
the chapter-level @@-commands. This enables you to use the @kbd{C-x
|
|
]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
|
|
commands to move forward and backward by chapter, and to use the
|
|
@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
|
|
@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
|
|
about the page commands.@refill
|
|
|
|
@node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
|
|
@comment node-name, next, previous, up
|
|
@section Updating Nodes and Menus
|
|
@cindex Updating nodes and menus
|
|
@cindex Create nodes, menus automatically
|
|
@cindex Insert nodes, menus automatically
|
|
@cindex Automatically insert nodes, menus
|
|
|
|
Texinfo mode provides commands for automatically creating or updating
|
|
menus and node pointers. The commands are called ``update'' commands
|
|
because their most frequent use is for updating a Texinfo file after
|
|
you have worked on it; but you can use them to insert the `Next',
|
|
`Previous', and `Up' pointers into an @code{@@node} line that has none and to
|
|
create menus in a file that has none.@refill
|
|
|
|
If you do not use the updating commands, you need to write menus and
|
|
node pointers by hand, which is a tedious task.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Updating Commands, Updating Requirements, , Updating Nodes and Menus
|
|
@ifinfo
|
|
@subheading The Updating Commands
|
|
@end ifinfo
|
|
|
|
You can use the updating commands@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
to insert or update the `Next', `Previous', and `Up' pointers of a
|
|
node,@refill
|
|
|
|
@item
|
|
to insert or update the menu for a section, and@refill
|
|
|
|
@item
|
|
to create a master menu for a Texinfo source file.@refill
|
|
@end itemize
|
|
|
|
You can also use the commands to update all the nodes and menus in a
|
|
region or in a whole Texinfo file.@refill
|
|
|
|
The updating commands work only with conventional Texinfo files, which
|
|
are structured hierarchically like books. In such files, a structuring
|
|
command line must follow closely after each @code{@@node} line, except
|
|
for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
|
|
a line beginning with @code{@@chapter}, @code{@@section}, or other
|
|
similar command.)
|
|
|
|
You can write the structuring command line on the line that follows
|
|
immediately after an @code{@@node} line or else on the line that
|
|
follows after a single @code{@@comment} line or a single
|
|
@code{@@ifinfo} line. You cannot interpose more than one line between
|
|
the @code{@@node} line and the structuring command line; and you may
|
|
interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
|
|
|
|
Commands which work on a whole buffer require that the `Top' node be
|
|
followed by a node with an @code{@@chapter} or equivalent-level command.
|
|
Note that the menu updating commands will not create a main or master
|
|
menu for a Texinfo file that has only @code{@@chapter}-level nodes! The
|
|
menu updating commands only create menus @emph{within} nodes for lower level
|
|
nodes. To create a menu of chapters, you must provide a `Top'
|
|
node.@refill
|
|
|
|
The menu updating commands remove menu entries that refer to other Info
|
|
files since they do not refer to nodes within the current buffer. This
|
|
is a deficiency. Rather than use menu entries, you can use cross
|
|
references to refer to other Info files. None of the updating commands
|
|
affect cross references.@refill
|
|
|
|
Texinfo mode has five updating commands that are used most often: two
|
|
are for updating the node pointers or menu of a single node (or a
|
|
region); two are for updating every node pointer and menu in a file;
|
|
and one, the @code{texinfo-master-menu} command, is for creating a
|
|
master menu for a complete file, and optionally, for updating every
|
|
node and menu in the whole Texinfo file.@refill
|
|
|
|
The @code{texinfo-master-menu} command is the primary command:@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-u m
|
|
@itemx M-x texinfo-master-menu
|
|
@findex texinfo-master-menu
|
|
Create or update a master menu that includes all the other menus
|
|
(incorporating the descriptions from pre-existing menus, if
|
|
any).@refill
|
|
|
|
With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
|
|
update all the nodes and all the regular menus in the buffer before
|
|
constructing the master menu. (@xref{The Top Node, , The Top Node and
|
|
Master Menu}, for more about a master menu.)@refill
|
|
|
|
For @code{texinfo-master-menu} to work, the Texinfo file must have a
|
|
`Top' node and at least one subsequent node.@refill
|
|
|
|
After extensively editing a Texinfo file, you can type the following:
|
|
|
|
@example
|
|
C-u M-x texinfo-master-menu
|
|
@exdent or
|
|
C-u C-c C-u m
|
|
@end example
|
|
|
|
@noindent
|
|
This updates all the nodes and menus completely and all at once.@refill
|
|
@end table
|
|
|
|
The other major updating commands do smaller jobs and are designed for
|
|
the person who updates nodes and menus as he or she writes a Texinfo
|
|
file.@refill
|
|
|
|
@need 1000
|
|
The commands are:@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-u C-n
|
|
@itemx M-x texinfo-update-node
|
|
@findex texinfo-update-node
|
|
Insert the `Next', `Previous', and `Up' pointers for the node that point is
|
|
within (i.e., for the @code{@@node} line preceding point). If the
|
|
@code{@@node} line has pre-existing `Next', `Previous', or `Up'
|
|
pointers in it, the old pointers are removed and new ones inserted.
|
|
With an argument (prefix argument, @kbd{C-u}, if interactive), this command
|
|
updates all @code{@@node} lines in the region (which is the text
|
|
between point and mark).@refill
|
|
|
|
@item C-c C-u C-m
|
|
@itemx M-x texinfo-make-menu
|
|
@findex texinfo-make-menu
|
|
Create or update the menu in the node that point is within.
|
|
With an argument (@kbd{C-u} as prefix argument, if
|
|
interactive), the command makes or updates menus for the
|
|
nodes which are either within or a part of the
|
|
region.@refill
|
|
|
|
Whenever @code{texinfo-make-menu} updates an existing menu, the
|
|
descriptions from that menu are incorporated into the new menu. This
|
|
is done by copying descriptions from the existing menu to the entries
|
|
in the new menu that have the same node names. If the node names are
|
|
different, the descriptions are not copied to the new menu.@refill
|
|
|
|
@item C-c C-u C-e
|
|
@itemx M-x texinfo-every-node-update
|
|
@findex texinfo-every-node-update
|
|
Insert or update the `Next', `Previous', and `Up' pointers for every
|
|
node in the buffer.@refill
|
|
|
|
@item C-c C-u C-a
|
|
@itemx M-x texinfo-all-menus-update
|
|
@findex texinfo-all-menus-update
|
|
Create or update all the menus in the buffer. With an argument
|
|
(@kbd{C-u} as prefix argument, if interactive), first insert
|
|
or update all the node
|
|
pointers before working on the menus.@refill
|
|
|
|
If a master menu exists, the @code{texinfo-all-menus-update} command
|
|
updates it; but the command does not create a new master menu if none
|
|
already exists. (Use the @code{texinfo-master-menu} command for
|
|
that.)@refill
|
|
|
|
When working on a document that does not merit a master menu, you can
|
|
type the following:
|
|
|
|
@example
|
|
C-u C-c C-u C-a
|
|
@exdent or
|
|
C-u M-x texinfo-all-menus-update
|
|
@end example
|
|
|
|
@noindent
|
|
This updates all the nodes and menus.@refill
|
|
@end table
|
|
|
|
The @code{texinfo-column-for-description} variable specifies the
|
|
column to which menu descriptions are indented. By default, the value
|
|
is 32 although it is often useful to reduce it to as low as 24. You
|
|
can set the variable with the @kbd{M-x edit-options} command
|
|
(@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
|
|
Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
|
|
, Examining and Setting Variables, emacs, The GNU Emacs
|
|
Manual}).@refill
|
|
|
|
Also, the @code{texinfo-indent-menu-description} command may be used to
|
|
indent existing menu descriptions to a specified column. Finally, if
|
|
you wish, you can use the @code{texinfo-insert-node-lines} command to
|
|
insert missing @code{@@node} lines into a file. (@xref{Other Updating
|
|
Commands}, for more information.)@refill
|
|
|
|
@node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
|
|
@comment node-name, next, previous, up
|
|
@subsection Updating Requirements
|
|
@cindex Updating requirements
|
|
@cindex Requirements for updating commands
|
|
|
|
To use the updating commands, you must organize the Texinfo file
|
|
hierarchically with chapters, sections, subsections, and the like.
|
|
When you construct the hierarchy of the manual, do not `jump down'
|
|
more than one level at a time: you can follow the `Top' node with a
|
|
chapter, but not with a section; you can follow a chapter with a
|
|
section, but not with a subsection. However, you may `jump up' any
|
|
number of levels at one time---for example, from a subsection to a
|
|
chapter.@refill
|
|
|
|
Each @code{@@node} line, with the exception of the line for the `Top'
|
|
node, must be followed by a line with a structuring command such as
|
|
@code{@@chapter}, @code{@@section}, or
|
|
@code{@@unnumberedsubsec}.@refill
|
|
|
|
Each @code{@@node} line/structuring-command line combination
|
|
must look either like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@node Comments, Minimum, Conventions, Overview
|
|
@@comment node-name, next, previous, up
|
|
@@section Comments
|
|
@end group
|
|
@end example
|
|
|
|
or like this (without the @code{@@comment} line):
|
|
|
|
@example
|
|
@group
|
|
@@node Comments, Minimum, Conventions, Overview
|
|
@@section Comments
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
In this example, `Comments' is the name of both the node and the
|
|
section. The next node is called `Minimum' and the previous node is
|
|
called `Conventions'. The `Comments' section is within the `Overview'
|
|
node, which is specified by the `Up' pointer. (Instead of an
|
|
@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill
|
|
|
|
If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
|
|
and be the first node in the file.@refill
|
|
|
|
The menu updating commands create a menu of sections within a chapter,
|
|
a menu of subsections within a section, and so on. This means that
|
|
you must have a `Top' node if you want a menu of chapters.@refill
|
|
|
|
Incidentally, the @code{makeinfo} command will create an Info file for
|
|
a hierarchically organized Texinfo file that lacks `Next', `Previous'
|
|
and `Up' pointers. Thus, if you can be sure that your Texinfo file
|
|
will be formatted with @code{makeinfo}, you have no need for the
|
|
`update node' commands. (@xref{Create an Info File, , Creating an
|
|
Info File}, for more information about @code{makeinfo}.) However,
|
|
both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands
|
|
require that you insert menus in the file.@refill
|
|
|
|
@node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
|
|
@comment node-name, next, previous, up
|
|
@subsection Other Updating Commands
|
|
|
|
In addition to the five major updating commands, Texinfo mode
|
|
possesses several less frequently used updating commands:@refill
|
|
|
|
@table @kbd
|
|
@item M-x texinfo-insert-node-lines
|
|
@findex texinfo-insert-node-lines
|
|
Insert @code{@@node} lines before the @code{@@chapter},
|
|
@code{@@section}, and other sectioning commands wherever they are
|
|
missing throughout a region in a Texinfo file.@refill
|
|
|
|
With an argument (@kbd{C-u} as prefix argument, if interactive), the
|
|
@code{texinfo-insert-node-lines} command not only inserts
|
|
@code{@@node} lines but also inserts the chapter or section titles as
|
|
the names of the corresponding nodes. In addition, it inserts the
|
|
titles as node names in pre-existing @code{@@node} lines that lack
|
|
names. Since node names should be more concise than section or
|
|
chapter titles, you must manually edit node names so inserted.@refill
|
|
|
|
For example, the following marks a whole buffer as a region and inserts
|
|
@code{@@node} lines and titles throughout:@refill
|
|
|
|
@example
|
|
C-x h C-u M-x texinfo-insert-node-lines
|
|
@end example
|
|
|
|
(Note that this command inserts titles as node names in @code{@@node}
|
|
lines; the @code{texinfo-start-menu-description} command
|
|
(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles
|
|
as descriptions in menu entries, a different action. However, in both
|
|
cases, you need to edit the inserted text.)@refill
|
|
|
|
@item M-x texinfo-multiple-files-update
|
|
@findex texinfo-multiple-files-update @r{(in brief)}
|
|
Update nodes and menus in a document built from several separate files.
|
|
With @kbd{C-u} as a prefix argument, create and insert a master menu in
|
|
the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
|
|
update all the menus and all the `Next', `Previous', and `Up' pointers
|
|
of all the included files before creating and inserting a master menu in
|
|
the outer file. The @code{texinfo-multiple-files-update} command is
|
|
described in the appendix on @code{@@include} files.
|
|
@ifinfo
|
|
@xref{texinfo-multiple-files-update}.@refill
|
|
@end ifinfo
|
|
@iftex
|
|
@xref{texinfo-multiple-files-update, ,
|
|
@code{texinfo-multiple-files-update}}.@refill
|
|
@end iftex
|
|
|
|
@item M-x texinfo-indent-menu-description
|
|
@findex texinfo-indent-menu-description
|
|
Indent every description in the menu following point to the specified
|
|
column. You can use this command to give yourself more space for
|
|
descriptions. With an argument (@kbd{C-u} as prefix argument, if
|
|
interactive), the @code{texinfo-indent-menu-description} command indents
|
|
every description in every menu in the region. However, this command
|
|
does not indent the second and subsequent lines of a multi-line
|
|
description.@refill
|
|
|
|
@item M-x texinfo-sequential-node-update
|
|
@findex texinfo-sequential-node-update
|
|
Insert the names of the nodes immediately following and preceding the
|
|
current node as the `Next' or `Previous' pointers regardless of those
|
|
nodes' hierarchical level. This means that the `Next' node of a
|
|
subsection may well be the next chapter. Sequentially ordered nodes are
|
|
useful for novels and other documents that you read through
|
|
sequentially. (However, in Info, the @code{g* @key{RET}} command lets
|
|
you look through the file sequentially, so sequentially ordered nodes
|
|
are not strictly necessary.) With an argument (prefix argument, if
|
|
interactive), the @code{texinfo-sequential-node-update} command
|
|
sequentially updates all the nodes in the region.@refill
|
|
@end table
|
|
|
|
@node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
|
|
@comment node-name, next, previous, up
|
|
@section Formatting for Info
|
|
@cindex Formatting for Info
|
|
@cindex Running an Info formatter
|
|
@cindex Info formatting
|
|
|
|
Texinfo mode provides several commands for formatting part or all of a
|
|
Texinfo file for Info. Often, when you are writing a document, you
|
|
want to format only part of a file---that is, a region.@refill
|
|
|
|
You can use either the @code{texinfo-format-region} or the
|
|
@code{makeinfo-region} command to format a region:@refill
|
|
|
|
@table @kbd
|
|
@findex texinfo-format-region
|
|
@item C-c C-e C-r
|
|
@itemx M-x texinfo-format-region
|
|
@itemx C-c C-m C-r
|
|
@itemx M-x makeinfo-region
|
|
Format the current region for Info.@refill
|
|
@end table
|
|
|
|
You can use either the @code{texinfo-format-buffer} or the
|
|
@code{makeinfo-buffer} command to format a whole buffer:@refill
|
|
|
|
@table @kbd
|
|
@findex texinfo-format-buffer
|
|
@item C-c C-e C-b
|
|
@itemx M-x texinfo-format-buffer
|
|
@itemx C-c C-m C-b
|
|
@itemx M-x makeinfo-buffer
|
|
Format the current buffer for Info.@refill
|
|
@end table
|
|
|
|
@need 1000
|
|
For example, after writing a Texinfo file, you can type the following:
|
|
|
|
@example
|
|
C-u C-c C-u m
|
|
@exdent or
|
|
C-u M-x texinfo-master-menu
|
|
@end example
|
|
|
|
@noindent
|
|
This updates all the nodes and menus. Then type the following to create
|
|
an Info file:
|
|
|
|
@example
|
|
C-c C-m C-b
|
|
@exdent or
|
|
M-x makeinfo-buffer
|
|
@end example
|
|
|
|
For the Info formatting commands to work, the file @emph{must} include
|
|
a line that has @code{@@setfilename} in its header.@refill
|
|
|
|
Not all systems support the @code{makeinfo}-based formatting commands.@refill
|
|
|
|
@xref{Create an Info File}, for details about Info formatting.@refill
|
|
|
|
@node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
|
|
@comment node-name, next, previous, up
|
|
@section Formatting and Printing
|
|
@cindex Formatting for printing
|
|
@cindex Printing a region or buffer
|
|
@cindex Region formatting and printing
|
|
@cindex Buffer formatting and printing
|
|
@cindex Part of file formatting and printing
|
|
|
|
Typesetting and printing a Texinfo file is a multi-step process in which
|
|
you first create a file for printing (called a @sc{dvi} file), and then
|
|
print the file. Optionally, you may also create indices. To do this,
|
|
you must run the @code{texindex} command after first running the
|
|
@code{tex} typesetting command; and then you must run the @code{tex}
|
|
command again. @refill
|
|
|
|
Often, when you are writing a document, you want to typeset and print
|
|
only part of a file to see what it will look like. You can use the
|
|
@code{texinfo-tex-region} and related commands for this purpose. Use
|
|
the @code{texinfo-tex-buffer} command to format all of a
|
|
buffer.@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-t C-r
|
|
@itemx M-x texinfo-tex-region
|
|
@findex texinfo-tex-region
|
|
Run @TeX{} on the region.@refill
|
|
|
|
@item C-c C-t C-b
|
|
@itemx M-x texinfo-tex-buffer
|
|
@findex texinfo-tex-buffer
|
|
Run @TeX{} on the buffer.@refill
|
|
|
|
@item C-c C-t C-i
|
|
@itemx M-x texinfo-texindex
|
|
Run @code{texindex} to sort the indices of a Texinfo file formatted with
|
|
@code{texinfo-tex-region} or @code{texinfo-tex-buffer}. You must run
|
|
the @code{tex} command a second time after sorting the raw index
|
|
files.@refill
|
|
|
|
@item C-c C-t C-p
|
|
@itemx M-x texinfo-tex-print
|
|
@findex texinfo-tex-print
|
|
Print the file (or the part of the file) previously formatted with
|
|
@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
|
|
@end table
|
|
|
|
For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
|
|
file @emph{must} start with a @samp{\input texinfo} line and must
|
|
include an @code{@@settitle} line. The file must end with @code{@@bye}
|
|
on a line by itself. (When you use @code{texinfo-tex-region}, you must
|
|
surround the @code{@@settitle} line with start-of-header and
|
|
end-of-header lines.)@refill
|
|
|
|
@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related
|
|
commands, such as @code{tex-show-print-queue}.@refill
|
|
|
|
@node Texinfo Mode Summary, , Printing, Texinfo Mode
|
|
@comment node-name, next, previous, up
|
|
@section Texinfo Mode Summary
|
|
|
|
In Texinfo mode, each set of commands has default keybindings that
|
|
begin with the same keys. All the commands that are custom-created
|
|
for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
|
|
mnemonic.@refill
|
|
|
|
@subheading Insert Commands
|
|
|
|
The insert commands are invoked by typing @kbd{C-c} twice and then the
|
|
first letter of the @@-command to be inserted. (It might make more
|
|
sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
|
|
@kbd{C-c C-c} is quick to type.)@refill
|
|
|
|
@example
|
|
C-c C-c c @r{Insert} @samp{@@code}.
|
|
C-c C-c d @r{Insert} @samp{@@dfn}.
|
|
C-c C-c e @r{Insert} @samp{@@end}.
|
|
C-c C-c i @r{Insert} @samp{@@item}.
|
|
C-c C-c n @r{Insert} @samp{@@node}.
|
|
C-c C-c s @r{Insert} @samp{@@samp}.
|
|
C-c C-c v @r{Insert} @samp{@@var}.
|
|
C-c C-c @{ @r{Insert braces.}
|
|
C-c C-c ]
|
|
C-c C-c @} @r{Move out of enclosing braces.}
|
|
|
|
@group
|
|
C-c C-c C-d @r{Insert a node's section title}
|
|
@r{in the space for the description}
|
|
@r{in a menu entry line.}
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Show Structure
|
|
|
|
The @code{texinfo-show-structure} command is often used within a
|
|
narrowed region.@refill
|
|
|
|
@example
|
|
C-c C-s @r{List all the headings.}
|
|
@end example
|
|
|
|
@subheading The Master Update Command
|
|
|
|
The @code{texinfo-master-menu} command creates a master menu; and can
|
|
be used to update every node and menu in a file as well.@refill
|
|
|
|
@example
|
|
@group
|
|
C-c C-u m
|
|
M-x texinfo-master-menu
|
|
@r{Create or update a master menu.}
|
|
@end group
|
|
|
|
@group
|
|
C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
|
|
@r{create or update all nodes and regular}
|
|
@r{menus, and then create a master menu.}
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Update Pointers
|
|
|
|
@c !!! added verbiage to prevent overfull hbox --bob 26 Mar 93
|
|
The update pointer commands are invoked by typing @kbd{C-c C-u} and
|
|
then either typing @kbd{C-n} for @code{texinfo-update-node} or typing
|
|
@kbd{C-e} for @code{texinfo-every-node-update}.@refill
|
|
|
|
@example
|
|
C-c C-u C-n @r{Update a node.}
|
|
C-c C-u C-e @r{Update every node in the buffer.}
|
|
@end example
|
|
|
|
@subheading Update Menus
|
|
|
|
Invoke the update menu commands by typing @kbd{C-c C-u}
|
|
and then either @kbd{C-m} for @code{texinfo-make-menu} or
|
|
@kbd{C-a} for @code{texinfo-all-menus-update}. To update
|
|
both nodes and menus at the same time, precede @kbd{C-c C-u
|
|
C-a} with @kbd{C-u}.@refill
|
|
|
|
@example
|
|
C-c C-u C-m @r{Make or update a menu.}
|
|
|
|
@group
|
|
C-c C-u C-a @r{Make or update all}
|
|
@r{menus in a buffer.}
|
|
@end group
|
|
|
|
@group
|
|
C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
|
|
@r{first create or update all nodes and}
|
|
@r{then create or update all menus.}
|
|
@end group
|
|
@end example
|
|
|
|
@subheading Format for Info
|
|
|
|
The Info formatting commands that are written in Emacs Lisp are
|
|
invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
|
|
or @kbd{C-b} for the whole buffer.@refill
|
|
|
|
The Info formatting commands that are written in C and based on the
|
|
@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
|
|
either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
Use the @code{texinfo-format@dots{}} commands:
|
|
|
|
@example
|
|
@group
|
|
C-c C-e C-r @r{Format the region.}
|
|
C-c C-e C-b @r{Format the buffer.}
|
|
@end group
|
|
@end example
|
|
|
|
@need 750
|
|
@noindent
|
|
Use @code{makeinfo}:
|
|
|
|
@example
|
|
C-c C-m C-r @r{Format the region.}
|
|
C-c C-m C-b @r{Format the buffer.}
|
|
C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
|
|
C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
|
|
@end example
|
|
|
|
@subheading Typeset and Print
|
|
|
|
The @TeX{} typesetting and printing commands are invoked by typing
|
|
@kbd{C-c C-t} and then another control command: @kbd{C-r} for
|
|
@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
|
|
and so on.@refill
|
|
|
|
@example
|
|
C-c C-t C-r @r{Run @TeX{} on the region.}
|
|
C-c C-t C-b @r{Run @TeX{} on the buffer.}
|
|
C-c C-t C-i @r{Run} @code{texindex}.
|
|
C-c C-t C-p @r{Print the @sc{dvi} file.}
|
|
C-c C-t C-q @r{Show the print queue.}
|
|
C-c C-t C-d @r{Delete a job from the print queue.}
|
|
C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
|
|
C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
|
|
C-c C-t C-l @r{Recenter the output buffer.}
|
|
@end example
|
|
|
|
@subheading Other Updating Commands
|
|
|
|
The `other updating commands' do not have standard keybindings because
|
|
they are rarely used.
|
|
|
|
@example
|
|
@group
|
|
M-x texinfo-insert-node-lines
|
|
@r{Insert missing @code{@@node} lines in region.}
|
|
@r{With @kbd{C-u} as a prefix argument,}
|
|
@r{use section titles as node names.}
|
|
@end group
|
|
|
|
@group
|
|
M-x texinfo-multiple-files-update
|
|
@r{Update a multi-file document.}
|
|
@r{With @kbd{C-u 2} as a prefix argument,}
|
|
@r{create or update all nodes and menus}
|
|
@r{in all included files first.}
|
|
@end group
|
|
|
|
@group
|
|
M-x texinfo-indent-menu-description
|
|
@r{Indent descriptions.}
|
|
@end group
|
|
|
|
@group
|
|
M-x texinfo-sequential-node-update
|
|
@r{Insert node pointers in strict sequence.}
|
|
@end group
|
|
@end example
|
|
|
|
@node Beginning a File, Ending a File, Texinfo Mode, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Beginning a Texinfo File
|
|
@cindex Beginning a Texinfo file
|
|
@cindex Texinfo file beginning
|
|
@cindex File beginning
|
|
|
|
Certain pieces of information must be provided at the beginning of a
|
|
Texinfo file, such as the name of the file and the title of the
|
|
document.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Four Parts, Sample Beginning, , Beginning a File
|
|
@ifinfo
|
|
@heading Four Parts Begin a File
|
|
@end ifinfo
|
|
|
|
Generally, the beginning of a Texinfo file has four parts:@refill
|
|
|
|
@enumerate
|
|
@item
|
|
The header, delimited by special comment lines, that includes the
|
|
commands for naming the Texinfo file and telling @TeX{} what
|
|
definitions' file to use when processing the Texinfo file.@refill
|
|
|
|
@item
|
|
A short statement of what the file is about, with a copyright notice
|
|
and copying permissions. This is enclosed in @code{@@ifinfo} and
|
|
@code{@@end ifinfo} commands so that the formatters place it only
|
|
in the Info file.@refill
|
|
|
|
@item
|
|
A title page and copyright page, with a copyright notice and copying
|
|
permissions. This is enclosed between @code{@@titlepage} and
|
|
@code{@@end titlepage} commands. The title and copyright page appear
|
|
only in the printed @w{manual}.@refill
|
|
|
|
@item
|
|
The `Top' node that contains a menu for the whole Info file. The
|
|
contents of this node appear only in the Info file.@refill
|
|
@end enumerate
|
|
|
|
Also, optionally, you may include the copying conditions for a program
|
|
and a warranty disclaimer. The copying section will be followed by an
|
|
introduction or else by the first chapter of the manual.@refill
|
|
|
|
Since the copyright notice and copying permissions for the Texinfo
|
|
document (in contrast to the copying permissions for a program) are in
|
|
parts that appear only in the Info file or only in the printed manual,
|
|
this information must be given twice.@refill
|
|
|
|
@node Sample Beginning, Header, Four Parts, Beginning a File
|
|
@comment node-name, next, previous, up
|
|
@section Sample Texinfo File Beginning
|
|
|
|
The following sample shows what is needed.@refill
|
|
|
|
@example
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@@c %**start of header
|
|
@@setfilename @var{name-of-info-file}
|
|
@@settitle @var{name-of-manual}
|
|
@@setchapternewpage odd
|
|
@@c %**end of header
|
|
|
|
@@ifinfo
|
|
This file documents @dots{}
|
|
|
|
Copyright @var{year} @var{copyright-owner}
|
|
|
|
@group
|
|
Permission is granted to @dots{}
|
|
@@end ifinfo
|
|
@end group
|
|
|
|
@group
|
|
@@c This title page illustrates only one of the
|
|
@@c two methods of forming a title page.
|
|
@end group
|
|
|
|
@group
|
|
@@titlepage
|
|
@@title @var{name-of-manual-when-printed}
|
|
@@subtitle @var{subtitle-if-any}
|
|
@@subtitle @var{second-subtitle}
|
|
@@author @var{author}
|
|
@end group
|
|
|
|
@group
|
|
@@c The following two commands
|
|
@@c start the copyright page.
|
|
@@page
|
|
@@vskip 0pt plus 1filll
|
|
Copyright @@copyright@{@} @var{year} @var{copyright-owner}
|
|
@end group
|
|
|
|
Published by @dots{}
|
|
|
|
Permission is granted to @dots{}
|
|
@@end titlepage
|
|
|
|
@@node Top, Overview, (dir), (dir)
|
|
|
|
@@ifinfo
|
|
This document describes @dots{}
|
|
|
|
This document applies to version @dots{}
|
|
of the program named @dots{}
|
|
@@end ifinfo
|
|
|
|
@group
|
|
@@menu
|
|
* Copying:: Your rights and freedoms.
|
|
* First Chapter:: Getting started @dots{}
|
|
* Second Chapter:: @dots{}
|
|
@dots{}
|
|
@dots{}
|
|
@@end menu
|
|
@end group
|
|
|
|
@group
|
|
@@node First Chapter, Second Chapter, top, top
|
|
@@comment node-name, next, previous, up
|
|
@@chapter First Chapter
|
|
@@cindex Index entry for First Chapter
|
|
@end group
|
|
@end example
|
|
|
|
@node Header, Info Summary and Permissions, Sample Beginning, Beginning a File
|
|
@comment node-name, next, previous, up
|
|
@section The Texinfo File Header
|
|
@cindex Header for Texinfo files
|
|
@cindex Texinfo file header
|
|
|
|
Texinfo files start with at least three lines that provide Info and
|
|
@TeX{} with necessary information. These are the @code{\input
|
|
texinfo} line, the @code{@@settitle} line, and the
|
|
@code{@@setfilename} line. If you want to run @TeX{} on just a part
|
|
of the Texinfo File, you must write the @code{@@settitle}
|
|
and @code{@@setfilename} lines between start-of-header and end-of-header
|
|
lines.@refill
|
|
|
|
Thus, the beginning of a Texinfo file looks like this:
|
|
|
|
@example
|
|
@group
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@@setfilename sample.info
|
|
@@settitle Sample Document
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
or else like this:
|
|
|
|
@example
|
|
@group
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@@c %**start of header
|
|
@@setfilename sample.info
|
|
@@settitle Sample Document
|
|
@@c %**end of header
|
|
@end group
|
|
@end example
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node First Line, Start of Header, , Header
|
|
@comment node-name, next, previous, up
|
|
@subsection The First Line of a Texinfo File
|
|
@cindex First line of a Texinfo file
|
|
@cindex Beginning line of a Texinfo file
|
|
@cindex Header of a Texinfo file
|
|
|
|
Every Texinfo file that is to be the top-level input to @TeX{} must begin
|
|
with a line that looks like this:@refill
|
|
|
|
@example
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@end example
|
|
|
|
@noindent
|
|
This line serves two functions:
|
|
|
|
@enumerate
|
|
@item
|
|
When the file is processed by @TeX{}, the @code{\input texinfo} command
|
|
tells @TeX{} to load the macros needed for processing a Texinfo file.
|
|
These are in a file called @file{texinfo.tex}, which is usually located
|
|
in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash,
|
|
@samp{\}, to mark the beginning of a command, just as Texinfo uses
|
|
@code{@@}. The @file{texinfo.tex} file causes the switch from @samp{\}
|
|
to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
|
|
is why it appears at the beginning of the file.@refill
|
|
|
|
@item
|
|
When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
|
|
specification tells Emacs to use Texinfo mode.@refill
|
|
@end enumerate
|
|
|
|
@node Start of Header, setfilename, First Line, Header
|
|
@comment node-name, next, previous, up
|
|
@subsection Start of Header
|
|
@cindex Start of header line
|
|
|
|
Write a start-of-header line on the second line of a Texinfo file.
|
|
Follow the start-of-header line with @code{@@setfilename} and
|
|
@code{@@settitle} lines and, optionally, with other command lines, such
|
|
as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
|
|
end-of-header line (@pxref{End of Header}).@refill
|
|
|
|
With these lines, you can format part of a Texinfo file for Info or
|
|
typeset part for printing.@refill
|
|
|
|
A start-of-header line looks like this:@refill
|
|
|
|
@example
|
|
@@c %**start of header
|
|
@end example
|
|
|
|
The odd string of characters, @samp{%**}, is to ensure that no other
|
|
comment is accidentally taken for a start-of-header line.@refill
|
|
|
|
@node setfilename, settitle, Start of Header, Header
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@setfilename}
|
|
@cindex Info file requires @code{@@setfilename}
|
|
@findex setfilename
|
|
|
|
In order to be made into an Info file, a Texinfo file must contain a line
|
|
that looks like this:@refill
|
|
|
|
@example
|
|
@@setfilename @var{info-file-name}
|
|
@end example
|
|
|
|
Write the @code{@@setfilename} command at the beginning of a line and
|
|
follow it on the same line by the Info file name. Do not write
|
|
anything else on the line; anything on the line after the command is
|
|
considered part of the file name, including a comment.@refill
|
|
|
|
The @code{@@setfilename} line specifies the name of the Info file to be
|
|
generated. This name should be different from the name of the Texinfo
|
|
file. The convention is to write a name with a @samp{.info} extension,
|
|
to produce an Info file name such as @file{texinfo.info}.@refill
|
|
|
|
Some operating systems cannot handle long file names. You can run into
|
|
a problem even when the file name you specify is itself short enough.
|
|
This occurs because the Info formatters split a long Info file into
|
|
short indirect subfiles, and name them by appending `-1', `-2', @dots{},
|
|
`-10', `-11', and so on, to the original file name. (@xref{Tag and
|
|
Split Files, , Tag Files and Split Files}.) The subfile name
|
|
@file{texinfo.info-10}, for example, is too long for some systems; so
|
|
the Info file name for this document is actually @file{texinfo} rather than
|
|
@file{texinfo.info}.@refill
|
|
|
|
The Info formatting commands ignore everything written before the
|
|
@code{@@setfilename} line, which is why the very first line of
|
|
the file (the @code{\input} line) does not need to be commented out.
|
|
The @code{@@setfilename} line is ignored when you typeset a printed
|
|
manual.@refill
|
|
|
|
@node settitle, setchapternewpage, setfilename, Header
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@settitle}
|
|
@findex settitle
|
|
|
|
In order to be made into a printed manual, a Texinfo file must contain
|
|
a line that looks like this:@refill
|
|
|
|
@example
|
|
@@settitle @var{title}
|
|
@end example
|
|
|
|
Write the @code{@@settitle} command at the beginning of a line and
|
|
follow it on the same line by the title. This tells @TeX{} the title
|
|
to use in a header or footer. Do not write anything else on the line;
|
|
anything on the line after the command is considered part of the
|
|
title, including a comment.@refill
|
|
|
|
Conventionally, @TeX{} formats a Texinfo file for double-sided output
|
|
so as to print the title in the left-hand (even-numbered) page
|
|
headings and the current chapter titles in the right-hand
|
|
(odd-numbered) page headings. (@TeX{} learns the title of each
|
|
chapter from each @code{@@chapter} command.) Page footers are not
|
|
printed.@refill
|
|
|
|
Even if you are printing in a single-sided style, @TeX{} looks for an
|
|
@code{@@settitle} command line, in case you include the manual title
|
|
in the heading. @refill
|
|
|
|
The @code{@@settitle} command should precede everything that generates
|
|
actual output in @TeX{}.@refill
|
|
|
|
Although the title in the @code{@@settitle} command is usually the
|
|
same as the title on the title page, it does not affect the title as
|
|
it appears on the title page. Thus, the two do not need not match
|
|
exactly; and the title in the @code{@@settitle} command can be a
|
|
shortened or expanded version of the title as it appears on the title
|
|
page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
|
|
|
|
@TeX{} prints page headings only for that text that comes after the
|
|
@code{@@end titlepage} command in the Texinfo file, or that comes
|
|
after an @code{@@headings} command that turns on headings.
|
|
(@xref{headings on off, , The @code{@@headings} Command}, for more
|
|
information.)@refill
|
|
|
|
You may, if you wish, create your own, customized headings and
|
|
footings. @xref{Headings, , Page Headings}, for a detailed discussion
|
|
of this process.@refill
|
|
|
|
@node setchapternewpage, paragraphindent, settitle, Header
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@setchapternewpage}
|
|
@cindex Starting chapters
|
|
@cindex Pages, starting odd
|
|
@findex setchapternewpage
|
|
|
|
In a book or a manual, text is usually printed on both sides of the
|
|
paper, chapters start on right-hand pages, and right-hand pages have
|
|
odd numbers. But in short reports, text often is printed only on one
|
|
side of the paper. Also in short reports, chapters sometimes do not
|
|
start on new pages, but are printed on the same page as the end of the
|
|
preceding chapter, after a small amount of vertical whitespace.@refill
|
|
|
|
You can use the @code{@@setchapternewpage} command with various
|
|
arguments to specify how @TeX{} should start chapters and whether it
|
|
should typeset pages for printing on one or both sides of the paper
|
|
(single-sided or double-sided printing).@refill
|
|
|
|
Write the @code{@@setchapternewpage} command at the beginning of a
|
|
line followed by its argument.@refill
|
|
|
|
For example, you would write the following to cause each chapter to
|
|
start on a fresh odd-numbered page:@refill
|
|
|
|
@example
|
|
@@setchapternewpage odd
|
|
@end example
|
|
|
|
You can specify one of three alternatives with the
|
|
@code{@@setchapternewpage} command:@refill
|
|
|
|
@table @asis
|
|
@ignore
|
|
@item No @code{@@setchapternewpage} command
|
|
If the Texinfo file does not contain an @code{@@setchapternewpage}
|
|
command before the @code{@@titlepage} command, @TeX{} automatically
|
|
begins chapters on new pages and prints headings in the standard
|
|
format for single-sided printing. This is the conventional format for
|
|
single-sided printing.@refill
|
|
|
|
The result is exactly the same as when you write
|
|
@code{@@setchapternewpage on}.@refill
|
|
@end ignore
|
|
@item @code{@@setchapternewpage off}
|
|
Cause @TeX{} to typeset a new chapter on the same page as the last
|
|
chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
|
|
format page headers for single-sided printing. (You can override the
|
|
headers format with the @code{@@headings double} command; see
|
|
@ref{headings on off, , The @code{@@headings} Command}.)@refill
|
|
|
|
@item @code{@@setchapternewpage on}
|
|
Cause @TeX{} to start new chapters on new pages and to typeset page
|
|
headers for single-sided printing. This is the form most often
|
|
used for short reports.@refill
|
|
|
|
This alternative is the default.@refill
|
|
|
|
@item @code{@@setchapternewpage odd}
|
|
Cause @TeX{} to start new chapters on new, odd-numbered pages
|
|
(right-handed pages) and to typeset for double-sided printing. This is
|
|
the form most often used for books and manuals.@refill
|
|
@end table
|
|
|
|
@noindent
|
|
Texinfo does not have an @code{@@setchapternewpage even} command.@refill
|
|
|
|
@noindent
|
|
(You can countermand or modify an @code{@@setchapternewpage} command
|
|
with an @code{@@headings} command. @xref{headings on off, , The
|
|
@code{@@headings} Command}.)@refill
|
|
|
|
At the beginning of a manual or book, pages are not numbered---for
|
|
example, the title and copyright pages of a book are not numbered.
|
|
By convention, table of contents pages are numbered with roman
|
|
numerals and not in sequence with the rest of the document.@refill
|
|
|
|
Since an Info file does not have pages, the @code{@@setchapternewpage}
|
|
command has no effect on it.@refill
|
|
|
|
Usually, you do not write an @code{@@setchapternewpage} command for
|
|
single-sided printing, but accept the default which is to typeset for
|
|
single-sided printing and to start new chapters on new pages. Usually,
|
|
you write an @code{@@setchapternewpage odd} command for double-sided
|
|
printing.@refill
|
|
|
|
@node paragraphindent, End of Header, setchapternewpage, Header
|
|
@comment node-name, next, previous, up
|
|
@subsection Paragraph Indenting
|
|
@cindex Indenting paragraphs
|
|
@cindex Paragraph indentation
|
|
@findex paragraphindent
|
|
|
|
The Info formatting commands may insert spaces at the beginning of the
|
|
first line of each paragraph, thereby indenting that paragraph. You
|
|
can use the @code{@@paragraphindent} command to specify the
|
|
indentation. Write an @code{@@paragraphindent} command at the
|
|
beginning of a line followed by either @samp{asis} or a number. The
|
|
template is:@refill
|
|
|
|
@example
|
|
@@paragraphindent @var{indent}
|
|
@end example
|
|
|
|
The Info formatting commands indent according to the value of
|
|
@var{indent}:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If the value of @var{indent} is @samp{asis}, the Info formatting
|
|
commands do not change the existing indentation.@refill
|
|
|
|
@item
|
|
If the value of @var{indent} is 0, the Info formatting commands delete
|
|
existing indentation.@refill
|
|
|
|
@item
|
|
If the value of @var{indent} is greater than 0, the Info formatting
|
|
commands indent the paragraph by that number of spaces.@refill
|
|
@end itemize
|
|
|
|
The default value of @var{indent} is @samp{asis}.@refill
|
|
|
|
Write the @code{@@paragraphindent} command before or shortly after the
|
|
end-of-header line at the beginning of a Texinfo file. (If you write
|
|
the command between the start-of-header and end-of-header lines, the
|
|
region formatting commands indent paragraphs as specified.)@refill
|
|
|
|
@c !!! added verbiage to prevent overfull hbox --bob 26 Mar 93
|
|
A peculiarity of @code{texinfo-format-buffer} and
|
|
@code{texinfo-format-region} is that they do not indent (nor
|
|
fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
|
|
@xref{Refilling Paragraphs}, for a detailed description of what goes
|
|
on.@refill
|
|
|
|
@node End of Header, , paragraphindent, Header
|
|
@comment node-name, next, previous, up
|
|
@subsection End of Header
|
|
@cindex End of header line
|
|
|
|
Follow the header lines with an @w{end-of-header} line.
|
|
An end-of-header line looks like this:@refill
|
|
|
|
@example
|
|
@@c %**end of header
|
|
@end example
|
|
|
|
If you include the @code{@@setchapternewpage} command between the
|
|
start-of-header and end-of-header lines, @TeX{} will typeset a region as
|
|
that command specifies. Similarly, if you include an @code{@@smallbook}
|
|
command between the start-of-header and end-of-header lines, @TeX{} will
|
|
typeset a region in the ``small'' book format.@refill
|
|
|
|
@ifinfo
|
|
The reason for the odd string of characters (@samp{%**}) is so that the
|
|
@code{texinfo-tex-region} command does not accidentally find
|
|
something that it should not when it is looking for the header.@refill
|
|
|
|
The start-of-header line and the end-of-header line are Texinfo mode
|
|
variables that you can change.@refill
|
|
@end ifinfo
|
|
|
|
@iftex
|
|
@xref{Start of Header}.
|
|
@end iftex
|
|
|
|
@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File
|
|
@comment node-name, next, previous, up
|
|
@section Summary and Copying Permissions for Info
|
|
|
|
The title page and the copyright page appear only in the printed copy of
|
|
the manual; therefore, the same information must be inserted in a
|
|
section that appears only in the Info file. This section usually
|
|
contains a brief description of the contents of the Info file, a
|
|
copyright notice, and copying permissions.@refill
|
|
|
|
The copyright notice should read:@refill
|
|
|
|
@example
|
|
Copyright @var{year} @var{copyright-owner}
|
|
@end example
|
|
|
|
@noindent
|
|
and be put on a line by itself.@refill
|
|
|
|
Standard text for the copyright permissions is contained in an appendix
|
|
to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying
|
|
Permissions}, for the complete text.@refill
|
|
|
|
The permissions text appears in an Info file @emph{before} the first
|
|
node. This mean that a reader does @emph{not} see this text when
|
|
reading the file using Info, except when using the advanced Info command
|
|
@kbd{g *}.
|
|
|
|
@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File
|
|
@comment node-name, next, previous, up
|
|
@section The Title and Copyright Pages
|
|
|
|
A manual's name and author are usually printed on a title page.
|
|
Sometimes copyright information is printed on the title page as well;
|
|
more often, copyright information is printed on the back of the title
|
|
page.
|
|
|
|
The title and copyright pages appear in the printed manual, but not in the
|
|
Info file. Because of this, it is possible to use several slightly
|
|
obscure @TeX{} typesetting commands that cannot be used in an Info file.
|
|
In addition, this part of the beginning of a Texinfo file contains the text
|
|
of the copying permissions that will appear in the printed manual.@refill
|
|
|
|
@xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the
|
|
standard text for the copyright permissions.@refill
|
|
|
|
@menu
|
|
* titlepage:: Create a title for the printed document.
|
|
* titlefont center sp:: The @code{@@titlefont}, @code{@@center},
|
|
and @code{@@sp} commands.
|
|
* title subtitle author:: The @code{@@title}, @code{@@subtitle},
|
|
and @code{@@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.
|
|
@end menu
|
|
|
|
@node titlepage, titlefont center sp, , Titlepage & Copyright Page
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@titlepage}
|
|
@cindex Title page
|
|
@findex titlepage
|
|
|
|
Start the material for the title page and following copyright page
|
|
with @code{@@titlepage} on a line by itself and end it with
|
|
@code{@@end titlepage} on a line by itself.@refill
|
|
|
|
The @code{@@end titlepage} command starts a new page and turns on page
|
|
numbering. (@xref{Headings, , Page Headings}, for details about how to
|
|
generate of page headings.) All the material that you want to
|
|
appear on unnumbered pages should be put between the
|
|
@code{@@titlepage} and @code{@@end titlepage} commands. By using the
|
|
@code{@@page} command you can force a page break within the region
|
|
delineated by the @code{@@titlepage} and @code{@@end titlepage}
|
|
commands and thereby create more than one unnumbered page. This is
|
|
how the copyright page is produced. (The @code{@@titlepage} command
|
|
might perhaps have been better named the
|
|
@code{@@titleandadditionalpages} command, but that would have been
|
|
rather long!)@refill
|
|
|
|
@c !!! append refill to footnote when makeinfo can handle it.
|
|
When you write a manual about a computer program, you should write the
|
|
version of the program to which the manual applies on the title
|
|
page. If the manual changes more frequently than the program or is
|
|
independent of it, you should also include an edition
|
|
number@footnote{We have found that it is helpful to refer to versions
|
|
of manuals as `editions' and versions of programs as `versions';
|
|
otherwise, we find we are liable to confuse each other in conversation
|
|
by referring to both the documentation and the software with the same
|
|
words.} for the manual. This helps readers keep track of which manual
|
|
is for which version of the program. (The `Top' node
|
|
should also contain this information; see @ref{makeinfo top, ,
|
|
@code{@@top}}.)@refill
|
|
|
|
Texinfo provides two methods for creating a title page. One method
|
|
uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
|
|
to generate a title page in which the words on the page are
|
|
centered.@refill
|
|
|
|
The second method uses the @code{@@title}, @code{@@subtitle}, and
|
|
@code{@@author} commands to create a title page with black rules under
|
|
the title and author lines and the subtitle text set flush to the
|
|
right hand side of the page. With this method, you do not specify any
|
|
of the actual formatting of the title page. You specify the text
|
|
you want, and Texinfo does the formatting. You may use either
|
|
method.@refill
|
|
|
|
@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
|
|
@findex titlefont
|
|
@findex center
|
|
@findex sp @r{(titlepage line spacing)}
|
|
|
|
You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
|
|
commands to create a title page for a printed document. (This is the
|
|
first of the two methods for creating a title page in Texinfo.)@refill
|
|
|
|
Use the @code{@@titlefont} command to select a large font suitable for
|
|
the title itself.@refill
|
|
|
|
@need 700
|
|
For example:
|
|
|
|
@example
|
|
@@titlefont@{Texinfo@}
|
|
@end example
|
|
|
|
Use the @code{@@center} command at the beginning of a line to center
|
|
the remaining text on that line. Thus,@refill
|
|
|
|
@example
|
|
@@center @@titlefont@{Texinfo@}
|
|
@end example
|
|
|
|
@noindent
|
|
centers the title, which in this example is ``Texinfo'' printed
|
|
in the title font.@refill
|
|
|
|
Use the @code{@@sp} command to insert vertical space. For example:@refill
|
|
|
|
@example
|
|
@@sp 2
|
|
@end example
|
|
|
|
@noindent
|
|
This inserts two blank lines on the printed page. (@xref{sp, ,
|
|
@code{@@sp}}, for more information about the @code{@@sp}
|
|
command.)@refill
|
|
|
|
A template for this method looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@titlepage
|
|
@@sp 10
|
|
@@center @@titlefont@{@var{name-of-manual-when-printed}@}
|
|
@@sp 2
|
|
@@center @var{subtitle-if-any}
|
|
@@sp 2
|
|
@@center @var{author}
|
|
@dots{}
|
|
@@end titlepage
|
|
@end group
|
|
@end example
|
|
|
|
The spacing of the example fits an 8 1/2 by 11 inch manual.@refill
|
|
|
|
@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
|
|
@findex title
|
|
@findex subtitle
|
|
@findex author
|
|
|
|
You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
|
|
commands to create a title page in which the vertical and horizontal
|
|
spacing is done for you automatically. This contrasts with the method
|
|
described in
|
|
the previous section, in which the @code{@@sp} command is needed to
|
|
adjust vertical spacing.@refill
|
|
|
|
Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
|
|
commands at the beginning of a line followed by the title, subtitle,
|
|
or author.@refill
|
|
|
|
The @code{@@title} command produces a line in which the title is set
|
|
flush to the left-hand side of the page in a larger than normal font.
|
|
The title is underlined with a black rule.@refill
|
|
|
|
The @code{@@subtitle} command sets subtitles in a normal-sized font
|
|
flush to the right-hand side of the page.@refill
|
|
|
|
The @code{@@author} command sets the names of the author or authors in
|
|
a middle-sized font flush to the left-hand side of the page on a line
|
|
near the bottom of the title page. The names are underlined with a
|
|
black rule that is thinner than the rule that underlines the title.
|
|
(The black rule only occurs if the @code{@@author} command line is
|
|
followed by an @code{@@page} command line.)@refill
|
|
|
|
There are two ways to use the @code{@@author} command: you can write
|
|
the name or names on the remaining part of the line that starts with
|
|
an @code{@@author} command:@refill
|
|
|
|
@example
|
|
@@author by Jane Smith and John Doe
|
|
@end example
|
|
|
|
@noindent
|
|
or you can write the names one above each other by using two (or more)
|
|
@code{@@author} commands:@refill
|
|
|
|
@example
|
|
@group
|
|
@@author Jane Smith
|
|
@@author John Doe
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(Only the bottom name is underlined with a black rule.)@refill
|
|
|
|
@need 950
|
|
A template for this method looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@titlepage
|
|
@@title @var{name-of-manual-when-printed}
|
|
@@subtitle @var{subtitle-if-any}
|
|
@@subtitle @var{second-subtitle}
|
|
@@author @var{author}
|
|
@@page
|
|
@dots{}
|
|
@@end titlepage
|
|
@end group
|
|
@end example
|
|
|
|
@ifinfo
|
|
@noindent
|
|
Contrast this form with the form of a title page written using the
|
|
@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill
|
|
|
|
@example
|
|
@@titlepage
|
|
@@sp 10
|
|
@@center @@titlefont@{Name of Manual When Printed@}
|
|
@@sp 2
|
|
@@center Subtitle, If Any
|
|
@@sp 1
|
|
@@center Second subtitle
|
|
@@sp 2
|
|
@@center Author
|
|
@@page
|
|
@dots{}
|
|
@@end titlepage
|
|
@end example
|
|
@end ifinfo
|
|
|
|
@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page
|
|
@comment node-name, next, previous, up
|
|
@subsection Copyright Page and Permissions
|
|
@cindex Copyright page
|
|
@cindex Printed permissions
|
|
@cindex Permissions, printed
|
|
|
|
By international treaty, the copyright notice for a book should be
|
|
either on the title page or on the back of the title page. The
|
|
copyright notice should include the year followed by the name of the
|
|
organization or person who owns the copyright.@refill
|
|
|
|
When the copyright notice is on the back of the title page, that page
|
|
is customarily not numbered. Therefore, in Texinfo, the information
|
|
on the copyright page should be within @code{@@titlepage} and
|
|
@code{@@end titlepage} commands.@refill
|
|
|
|
@findex vskip
|
|
@findex filll
|
|
@cindex Vertical whitespace (@samp{vskip})
|
|
Use the @code{@@page} command to cause a page break. To push the
|
|
copyright notice and the other text on the copyright page towards the
|
|
bottom of the page, you can write a somewhat mysterious line after the
|
|
@code{@@page} command that reads like this:@refill
|
|
|
|
@example
|
|
@@vskip 0pt plus 1filll
|
|
@end example
|
|
|
|
@noindent
|
|
This is a @TeX{} command that is not supported by the Info formatting
|
|
commands. The @code{@@vskip} command inserts whitespace. The
|
|
@samp{0pt plus 1filll} means to put in zero points of mandatory whitespace,
|
|
and as much optional whitespace as needed to push the
|
|
following text to the bottom of the page. Note the use of three
|
|
@samp{l}s in the word @samp{filll}; this is the correct usage in
|
|
@TeX{}.@refill
|
|
|
|
@findex copyright
|
|
In a printed manual, the @code{@@copyright@{@}} command generates a
|
|
@samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The
|
|
copyright notice itself has the following legally defined sequence:@refill
|
|
|
|
@example
|
|
Copyright @copyright{} @var{year} @var{copyright-owner}
|
|
@end example
|
|
|
|
It is customary to put information on how to get a manual after the
|
|
copyright notice, followed by the copying permissions for the
|
|
manual.@refill
|
|
|
|
Note that permissions must be given here as well as in the summary
|
|
segment within @code{@@ifinfo} and @code{@@end ifinfo} that
|
|
immediately follows the header since this text appears only in the
|
|
printed manual and the @samp{ifinfo} text appears only in the Info
|
|
file.@refill
|
|
|
|
@xref{Sample Permissions}, for the standard text.@refill
|
|
|
|
@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page
|
|
@comment node-name, next, previous, up
|
|
@subsection Heading Generation
|
|
@findex end titlepage
|
|
@cindex Headings, page, begin to appear
|
|
@cindex Titlepage end starts headings
|
|
@cindex End titlepage starts headings
|
|
|
|
An @code{@@end titlepage} command on a line by itself not only marks
|
|
the end of the title and copyright pages, but also causes @TeX{} to start
|
|
generating page headings and page numbers.
|
|
|
|
To repeat what is said elsewhere, Texinfo has two standard page heading
|
|
formats, one for documents which are printed on one side of each sheet of paper
|
|
(single-sided printing), and the other for documents which are printed on both
|
|
sides of each sheet (double-sided printing).
|
|
(@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
|
|
You can specify these formats in different ways:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The conventional way is to write an @code{@@setchapternewpage} command
|
|
before the title page commands, and then have the @code{@@end
|
|
titlepage} command start generating page headings in the manner desired.
|
|
(@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
|
|
|
|
@item
|
|
Alternatively, you can use the @code{@@headings} command to prevent page
|
|
headings from being generated or to start them for either single or
|
|
double-sided printing. (Write an @code{@@headings} command immediately
|
|
after the @code{@@end titlepage} command. @xref{headings on off, , The
|
|
@code{@@headings} Command}, for more information.)@refill
|
|
|
|
@item
|
|
Or, you may specify your own page heading and footing format.
|
|
@xref{Headings, , Page Headings}, for detailed
|
|
information about page headings and footings.@refill
|
|
@end itemize
|
|
|
|
Most documents are formatted with the standard single-sided or
|
|
double-sided format, using @code{@@setchapternewpage odd} for
|
|
double-sided printing and no @code{@@setchapternewpage} command for
|
|
single-sided printing.@refill
|
|
|
|
@node headings on off, , end titlepage, Titlepage & Copyright Page
|
|
@comment node-name, next, previous, up
|
|
@subsection The @code{@@headings} Command
|
|
@findex headings
|
|
|
|
The @code{@@headings} command is rarely used. It specifies what kind of
|
|
page headings and footings to print on each page. Usually, this is
|
|
controlled by the @code{@@setchapternewpage} command. You need the
|
|
@code{@@headings} command only if the @code{@@setchapternewpage} command
|
|
does not do what you want, or if you want to turn off pre-defined page
|
|
headings prior to defining your own. Write an @code{@@headings} command
|
|
immediately after the @code{@@end titlepage} command.@refill
|
|
|
|
There are four ways to use the @code{@@headings} command:@refill
|
|
|
|
@table @code
|
|
@item @@headings off
|
|
Turn off printing of page headings.@refill
|
|
|
|
@item @@headings single
|
|
Turn on page headings appropriate for single-sided printing.
|
|
@refill
|
|
|
|
@item @@headings double
|
|
@itemx @@headings on
|
|
Turn on page headings appropriate for double-sided printing. The two
|
|
commands, @code{@@headings on} and @code{@@headings double}, are
|
|
synonymous.@refill
|
|
@end table
|
|
|
|
For example, suppose you write @code{@@setchapternewpage off} before the
|
|
@code{@@titlepage} command to tell @TeX{} to start a new chapter on the
|
|
same page as the end of the last chapter. This command also causes
|
|
@TeX{} to typeset page headers for single-sided printing. To cause
|
|
@TeX{} to typeset for double sided printing, write @code{@@headings
|
|
double} after the @code{@@end titlepage} command.
|
|
|
|
You can stop @TeX{} from generating any page headings at all by
|
|
writing @code{@@headings off} on a line of its own immediately after the
|
|
line containing the @code{@@end titlepage} command, like this:@refill
|
|
|
|
@example
|
|
@@end titlepage
|
|
@@headings off
|
|
@end example
|
|
|
|
@noindent
|
|
The @code{@@headings off} command overrides the @code{@@end titlepage}
|
|
command, which would otherwise cause @TeX{} to print page
|
|
headings.@refill
|
|
|
|
You can also specify your own style of page heading and footing.
|
|
@xref{Headings, , Page Headings}, for more information.@refill
|
|
|
|
@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File
|
|
@comment node-name, next, previous, up
|
|
@section The `Top' Node and Master Menu
|
|
@cindex @samp{@r{Top}} node
|
|
@cindex Master menu
|
|
@cindex Node, `Top'
|
|
|
|
The `Top' node is the node from which you enter an Info file.@refill
|
|
|
|
A `Top' node should contain a brief description of the Info file and an
|
|
extensive, master menu for the whole Info file.
|
|
This helps the reader understand what the Info file is
|
|
about. Also, you should write the version number of the program to
|
|
which the Info file applies; or, at least, the edition number.@refill
|
|
|
|
The contents of the `Top' node should appear only in the Info file; none
|
|
of it should appear in printed output, so enclose it between
|
|
@code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not
|
|
print either an @code{@@node} line or a menu; they appear only in Info;
|
|
strictly speaking, you are not required to enclose these parts between
|
|
@code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
|
|
@xref{Conditionals, , Conditionally Visible Text}.)@refill
|
|
|
|
@menu
|
|
* Title of Top Node:: Sketch what the file is about.
|
|
* Master Menu Parts:: A master menu has three or more parts.
|
|
@end menu
|
|
|
|
@node Title of Top Node, Master Menu Parts, , The Top Node
|
|
@ifinfo
|
|
@subheading `Top' Node Title
|
|
@end ifinfo
|
|
|
|
Sometimes, you will want to place an @code{@@top} sectioning command
|
|
line containing the title of the document immediately after the
|
|
@code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
|
|
Sectioning Command}, for more information).@refill
|
|
|
|
For example, the beginning of the Top node of this manual contains an
|
|
@code{@@top} sectioning command, a short description, and edition and
|
|
version information. It looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@dots{}
|
|
@@end titlepage
|
|
|
|
@@ifinfo
|
|
@@node Top, Copying, (dir), (dir)
|
|
@@top Texinfo
|
|
|
|
Texinfo is a documentation system@dots{}
|
|
@end group
|
|
|
|
@group
|
|
This is edition@dots{}
|
|
@dots{}
|
|
@@end ifinfo
|
|
@end group
|
|
|
|
@group
|
|
@@menu
|
|
* Copying:: Texinfo is freely
|
|
redistributable.
|
|
* Overview:: What is Texinfo?
|
|
@dots{}
|
|
@end group
|
|
@@end menu
|
|
@end example
|
|
|
|
In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
|
|
level directory of the whole Info system, which is called @samp{(dir)}.
|
|
The `Next' node refers to the first node that follows the main or master
|
|
menu, which is usually the copying permissions, introduction, or first
|
|
chapter.@refill
|
|
|
|
@node Master Menu Parts, , Title of Top Node, The Top Node
|
|
@subsection Parts of a Master Menu
|
|
@cindex Master menu parts
|
|
@cindex Parts of a master menu
|
|
|
|
A @dfn{master menu} is a detailed main menu listing all the nodes in a
|
|
file.
|
|
|
|
A master menu is enclosed in @code{@@menu} and @code{@@end menu}
|
|
commands and does not appear in the printed document.@refill
|
|
|
|
Generally, a master menu is divided into parts.@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The first part contains the major nodes in the Texinfo file: the nodes
|
|
for the chapters, chapter-like sections, and the appendices.@refill
|
|
|
|
@item
|
|
The second part contains nodes for the indices.@refill
|
|
|
|
@item
|
|
The third and subsequent parts contain a listing of the other, lower
|
|
level nodes, often ordered by chapter. This way, rather than go
|
|
through an intermediary menu, an inquirer can go directly to a
|
|
particular node when searching for specific information. These menu
|
|
items are not required; add them if you think they are a
|
|
convenience.@refill
|
|
@end itemize
|
|
|
|
Each section in the menu can be introduced by a descriptive line. So
|
|
long as the line does not begin with an asterisk, it will not be
|
|
treated as a menu entry. (@xref{Writing a Menu}, for more
|
|
information.)@refill
|
|
|
|
For example, the master menu for this manual looks like the following
|
|
(but has many more entries):@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
* Copying:: Texinfo is freely
|
|
redistributable.
|
|
* Overview:: What is Texinfo?
|
|
* Texinfo Mode:: Special features in GNU Emacs.
|
|
@dots{}
|
|
@dots{}
|
|
@end group
|
|
@group
|
|
* Command and Variable Index::
|
|
An entry for each @@-command.
|
|
* Concept Index:: An entry for each concept.
|
|
@end group
|
|
|
|
@group
|
|
--- The Detailed Node Listing ---
|
|
|
|
Overview of Texinfo
|
|
|
|
* Info Files:: What is an Info file?
|
|
* Printed Manuals:: Characteristics of
|
|
a printed manual.
|
|
@dots{}
|
|
@dots{}
|
|
@end group
|
|
|
|
@group
|
|
Using Texinfo Mode
|
|
|
|
* Info on a Region:: Formatting part of a file
|
|
for Info.
|
|
@dots{}
|
|
@dots{}
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
@node Software Copying Permissions, , The Top Node, Beginning a File
|
|
@comment node-name, next, previous, up
|
|
@section Software Copying Permissions
|
|
@cindex Software copying permissions
|
|
@cindex Copying software
|
|
@cindex Distribution
|
|
@cindex License agreement
|
|
|
|
If the Texinfo file has a section containing the ``General Public
|
|
License'' and the distribution information and a warranty disclaimer
|
|
for the software that is documented, this section usually follows the
|
|
`Top' node. The General Public License is very important to Project
|
|
GNU software. It ensures that you and others will continue to have a
|
|
right to use and share the software.@refill
|
|
|
|
The copying and distribution information and the disclaimer are
|
|
followed by an introduction or else by the first chapter of the
|
|
manual.@refill
|
|
|
|
@cindex Introduction, as part of file
|
|
Although an introduction is not a required part of a Texinfo file, it
|
|
is very helpful. Ideally, it should state clearly and concisely what
|
|
the file is about and who would be interested in reading it. In
|
|
general, an introduction would follow the licensing and distribution
|
|
information, although sometimes people put it earlier in the document.
|
|
Usually, an introduction is put in an @code{@@unnumbered} section.
|
|
(@xref{unnumbered & appendix, , The @code{@@unnumbered} and
|
|
@code{@@appendix} Commands}.)@refill
|
|
|
|
@node Ending a File, Structuring, Beginning a File, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Ending a Texinfo File
|
|
@cindex Ending a Texinfo file
|
|
@cindex Texinfo file ending
|
|
@cindex File ending
|
|
@findex bye
|
|
|
|
The end of a Texinfo file should include the commands that create
|
|
indices and generate detailed and summary tables of contents.
|
|
And it must include the @code{@@bye} command that marks the last line
|
|
processed by @TeX{}.@refill
|
|
|
|
@need 700
|
|
For example:
|
|
|
|
@example
|
|
@@node Concept Index, , Variables Index, Top
|
|
@@c node-name, next, previous, up
|
|
@@unnumbered Concept Index
|
|
|
|
@@printindex cp
|
|
|
|
@@contents
|
|
@@bye
|
|
@end example
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Printing Indices & Menus, Contents, , Ending a File
|
|
@comment node-name, next, previous, up
|
|
@section Index Menus and Printing an Index
|
|
@findex printindex
|
|
@cindex Printing an index
|
|
@cindex Indices, printing and menus
|
|
@cindex Generating menus with indices
|
|
@cindex Menus generated with indices
|
|
|
|
To print an index means to include it as part of a manual or Info
|
|
file. This does not happen automatically just because you use
|
|
@code{@@cindex} or other index-entry generating commands in the
|
|
Texinfo file; those just cause the raw data for the index to be
|
|
accumulated. To generate an index, you must include the
|
|
@code{@@printindex} command at the place in the document where you
|
|
want the index to appear. Also, as part of the process of creating a
|
|
printed manual, you must run a program called @code{texindex}
|
|
(@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted
|
|
index file. The sorted index file is what is actually used to
|
|
print the index.@refill
|
|
|
|
Texinfo offers six different types of predefined index: the concept
|
|
index, the function index, the variables index, the keystroke index, the
|
|
program index, and the data type index (@pxref{Predefined Indices}). Each
|
|
index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
|
|
@samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them
|
|
into separate sections (@pxref{Combining Indices}); or you may define
|
|
your own indices (@pxref{New Indices, , Defining New Indices}).@refill
|
|
|
|
The @code{@@printindex} command takes a two-letter index name, reads
|
|
the corresponding sorted index file and formats it appropriately into
|
|
an index.@refill
|
|
|
|
@ignore
|
|
The two-letter index names are:
|
|
|
|
@table @samp
|
|
@item cp
|
|
concept index
|
|
@item fn
|
|
function index
|
|
@item vr
|
|
variable index
|
|
@item ky
|
|
key index
|
|
@item pg
|
|
program index
|
|
@item tp
|
|
data type index
|
|
@end table
|
|
@end ignore
|
|
The @code{@@printindex} command does not generate a chapter heading
|
|
for the index. Consequently, you should precede the
|
|
@code{@@printindex} command with a suitable section or chapter command
|
|
(usually @code{@@unnumbered}) to supply the chapter heading and put
|
|
the index into the table of contents. Precede the @code{@@unnumbered}
|
|
command with an @code{@@node} line.@refill
|
|
|
|
@need 1200
|
|
For example:
|
|
|
|
@smallexample
|
|
@group
|
|
@@node Variable Index, Concept Index, Function Index, Top
|
|
@@comment node-name, next, previous, up
|
|
@@unnumbered Variable Index
|
|
|
|
@@printindex vr
|
|
@end group
|
|
|
|
@group
|
|
@@node Concept Index, , Variable Index, Top
|
|
@@comment node-name, next, previous, up
|
|
@@unnumbered Concept Index
|
|
|
|
@@printindex cp
|
|
@end group
|
|
|
|
@group
|
|
@@summarycontents
|
|
@@contents
|
|
@@bye
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
(Readers often prefer that the concept index come last in a book,
|
|
since that makes it easiest to find.)@refill
|
|
|
|
@ignore
|
|
In @TeX{}, the @code{@@printindex} command needs a sorted index file
|
|
to work from. @TeX{} does not know how to do sorting; this is a
|
|
deficiency. @TeX{} writes output files of raw index data; use the
|
|
@code{texindex} program to convert these files to sorted index files.
|
|
(@xref{Format/Print Hardcopy}, for more information.)@refill
|
|
@end ignore
|
|
@node Contents, File End, Printing Indices & Menus, Ending a File
|
|
@comment node-name, next, previous, up
|
|
@section Generating a Table of Contents
|
|
@cindex Table of contents
|
|
@cindex Contents, Table of
|
|
@findex contents
|
|
@findex summarycontents
|
|
@findex shortcontents
|
|
|
|
The @code{@@chapter}, @code{@@section}, and other structuring commands
|
|
supply the information to make up a table of contents, but they do not
|
|
cause an actual table to appear in the manual. To do this, you must
|
|
use the @code{@@contents} and @code{@@summarycontents}
|
|
commands:@refill
|
|
|
|
@table @code
|
|
@item @@contents
|
|
Generate a table of contents in a printed manual, including all
|
|
chapters, sections, subsections, etc., as well as appendices and
|
|
unnumbered chapters. (Headings generated by the @code{@@heading}
|
|
series of commands do not appear in the table of contents.) The
|
|
@code{@@contents} command should be written on a line by
|
|
itself.@refill
|
|
|
|
@item @@shortcontents
|
|
@itemx @@summarycontents
|
|
(@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
|
|
two commands are exactly the same.)@refill
|
|
|
|
Generate a short or summary table of contents that lists only the
|
|
chapters (and appendices and unnumbered chapters). Omit sections, subsections
|
|
and subsubsections. Only a long manual needs a short table
|
|
of contents in addition to the full table of contents.@refill
|
|
|
|
Write the @code{@@shortcontents} command on a line by itself right
|
|
@emph{before} the @code{@@contents} command.@refill
|
|
@end table
|
|
|
|
The table of contents commands automatically generate a chapter-like
|
|
heading at the top of the first table of contents page. Write the table
|
|
of contents commands at the very end of a Texinfo file, just before the
|
|
@code{@@bye} command, following any index sections---anything in the
|
|
Texinfo file after the table of contents commands will be omitted from
|
|
the table of contents.@refill
|
|
|
|
When you print a manual with a table of contents, the table of
|
|
contents are printed last and numbered with roman numerals. You need
|
|
to place those pages in their proper place, after the title page,
|
|
yourself. (This is the only collating you need to do for a printed
|
|
manual. The table of contents is printed last because it is generated
|
|
after the rest of the manual is typeset.)@refill
|
|
|
|
@need 700
|
|
Here is an example of where to write table of contents commands:@refill
|
|
|
|
@example
|
|
@group
|
|
@var{indices}@dots{}
|
|
@@shortcontents
|
|
@@contents
|
|
@@bye
|
|
@end group
|
|
@end example
|
|
|
|
Since an Info file uses menus instead of tables of contents, the Info
|
|
formatting commands ignore the @code{@@contents} and
|
|
@code{@@shortcontents} commands.@refill
|
|
|
|
@node File End, , Contents, Ending a File
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@bye} File Ending
|
|
@findex bye
|
|
|
|
An @code{@@bye} command terminates @TeX{} or Info formatting. None of
|
|
the formatting commands see any of the file following @code{@@bye}.
|
|
The @code{@@bye} command should be on a line by itself.@refill
|
|
|
|
If you wish, you may follow the @code{@@bye} line with notes. These notes
|
|
will not be formatted and will not appear in either Info or a printed
|
|
manual; it is as if text after @code{@@bye} were within @code{@@ignore}
|
|
@dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line
|
|
with a local variables list. @xref{Compile-Command, , Using Local
|
|
Variables and the Compile Command}, for more information.@refill
|
|
|
|
@node Structuring, Nodes, Ending a File, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Chapter Structuring
|
|
@cindex Chapter structuring
|
|
@cindex Structuring of chapters
|
|
|
|
The @dfn{chapter structuring} commands divide a document into a hierarchy of
|
|
chapters, sections, subsections, and subsubsections. These commands
|
|
generate large headings; they also provide information for the table
|
|
of contents of a printed manual (@pxref{Contents, , Generating a Table
|
|
of Contents}).@refill
|
|
|
|
The chapter structuring commands do not create an Info node structure,
|
|
so normally you should put an @code{@@node} command immediately before
|
|
each chapter structuring command (@pxref{Nodes}). The only time you
|
|
are likely to use the chapter structuring commands without using the
|
|
node structuring commands is if you are writing a document that
|
|
contains no cross references and will never be transformed into Info
|
|
format.@refill
|
|
|
|
It is unlikely that you will ever write a Texinfo file that is
|
|
intended only as an Info file and not as a printable document. If you
|
|
do, you might still use chapter structuring commands to create a
|
|
heading at the top of each node---but you don't need to.@refill
|
|
|
|
@menu
|
|
* Tree Structuring:: A manual is like an upside down tree @dots{}
|
|
* Structuring Command Types:: How to divide a manual into parts.
|
|
* makeinfo top:: The @code{@@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.
|
|
@end menu
|
|
|
|
@node Tree Structuring, Structuring Command Types, , Structuring
|
|
@comment node-name, next, previous, up
|
|
@section Tree Structure of Sections
|
|
@cindex Tree structuring
|
|
|
|
A Texinfo file is usually structured like a book with chapters,
|
|
sections, subsections, and the like. This structure can be visualized
|
|
as a tree (or rather as an upside-down tree) with the root at the top
|
|
and the levels corresponding to chapters, sections, subsection, and
|
|
subsubsections.@refill
|
|
|
|
Here is a diagram that shows a Texinfo file with three chapters,
|
|
each of which has two sections.@refill
|
|
|
|
@example
|
|
@group
|
|
Top
|
|
|
|
|
-------------------------------------
|
|
| | |
|
|
Chapter 1 Chapter 2 Chapter 3
|
|
| | |
|
|
-------- -------- --------
|
|
| | | | | |
|
|
Section Section Section Section Section Section
|
|
1.1 1.2 2.1 2.2 3.1 3.2
|
|
|
|
@end group
|
|
@end example
|
|
|
|
In a Texinfo file that has this structure, the beginning of Chapter 2
|
|
looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@node Chapter 2, Chapter 3, Chapter 1, top
|
|
@@chapter Chapter 2
|
|
@end group
|
|
@end example
|
|
|
|
The chapter structuring commands are described in the sections that
|
|
follow; the @code{@@node} and @code{@@menu} commands are described in
|
|
following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
|
|
|
|
@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section Types of Structuring Command
|
|
|
|
The chapter structuring commands fall into four groups or series, each
|
|
of which contains structuring commands corresponding to the
|
|
hierarchical levels of chapters, sections, subsections, and
|
|
subsubsections.@refill
|
|
|
|
The four groups are the @code{@@chapter} series, the
|
|
@code{@@unnumbered} series, the @code{@@appendix} series, and the
|
|
@code{@@heading} series.@refill
|
|
|
|
Each command produces titles that have a different appearance on the
|
|
printed page or Info file; only some of the commands produce
|
|
titles that are listed in the table of contents of a printed book or
|
|
manual.@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The @code{@@chapter} and @code{@@appendix} series of commands produce
|
|
numbered or lettered entries both in the body of a printed work and in
|
|
its table of contents.@refill
|
|
|
|
@item
|
|
The @code{@@unnumbered} series of commands produce unnumbered entries
|
|
both in the body of a printed work and in its table of contents. The
|
|
@code{@@top} command, which has a special use, is a member of this
|
|
series (@pxref{makeinfo top, , @code{@@top}}).@refill
|
|
|
|
@item
|
|
The @code{@@heading} series of commands produce unnumbered headings
|
|
that do not appear in a table of contents. The heading commands never
|
|
start a new page.@refill
|
|
|
|
@item
|
|
The @code{@@majorheading} command produces results similar to using
|
|
the @code{@@chapheading} command but generates a larger vertical
|
|
whitespace before the heading.@refill
|
|
|
|
@item
|
|
When an @code{@@setchapternewpage} command says to do so, the
|
|
@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
|
|
start new pages in the printed manual; the @code{@@heading} commands
|
|
do not.@refill
|
|
@end itemize
|
|
|
|
@need 1000
|
|
Here are the four groups of chapter structuring commands:@refill
|
|
|
|
@c Slightly different formatting for regular sized books and smallbooks.
|
|
@ifset smallbook
|
|
@sp 1
|
|
@tex
|
|
{\let\rm=\indrm \let\tt=\indtt
|
|
\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil&
|
|
\hskip.5em#\hfil\cr
|
|
|
|
& & & \rm No new pages\cr
|
|
\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr
|
|
\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr
|
|
|
|
& & & \cr
|
|
& \tt @@top& & \tt @@majorheading\cr
|
|
\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr
|
|
\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr
|
|
\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
|
|
\tt @@subheading\cr
|
|
\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
|
|
\tt @@subsubheading\cr}}
|
|
@end tex
|
|
@end ifset
|
|
@ifclear smallbook
|
|
@sp 1
|
|
@tex
|
|
\vbox{
|
|
\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil&
|
|
\hskip.5em#\hfil& \hskip.5em #\hfil\cr
|
|
|
|
& & & \cr
|
|
& & & \rm No new pages\cr
|
|
\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr
|
|
\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr
|
|
|
|
& & & \cr
|
|
& \tt @@top& & \tt @@majorheading\cr
|
|
\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr
|
|
\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr
|
|
\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
|
|
\tt @@subheading\cr
|
|
\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
|
|
\tt @@subsubheading\cr}}
|
|
@end tex
|
|
@end ifclear
|
|
@ifinfo
|
|
@example
|
|
@group
|
|
@r{No new pages}
|
|
@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
|
|
@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
|
|
|
|
@@top @@majorheading
|
|
@@chapter @@unnumbered @@appendix @@chapheading
|
|
@@section @@unnumberedsec @@appendixsec @@heading
|
|
@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
|
|
@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
|
|
@end group
|
|
@end example
|
|
@end ifinfo
|
|
|
|
@c Cannot line up columns properly inside of an example because of roman
|
|
@c proportional fonts.
|
|
@ignore
|
|
@ifset smallbook
|
|
@iftex
|
|
@smallexample
|
|
@group
|
|
@r{No new pages}
|
|
@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
|
|
@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
|
|
|
|
@@top @@majorheading
|
|
@@chapter @@unnumbered @@appendix @@chapheading
|
|
@@section @@unnumberedsec @@appendixsec @@heading
|
|
@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
|
|
@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
|
|
@end group
|
|
@end smallexample
|
|
@end iftex
|
|
@end ifset
|
|
@ifclear smallbook
|
|
@iftex
|
|
@smallexample
|
|
@group
|
|
@r{No new pages}
|
|
@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered}
|
|
@r{In contents} @r{In contents} @r{In contents} @r{Not in contents}
|
|
|
|
@@top @@majorheading
|
|
@@chapter @@unnumbered @@appendix @@chapheading
|
|
@@section @@unnumberedsec @@appendixsec @@heading
|
|
@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
|
|
@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
|
|
@end group
|
|
@end smallexample
|
|
@end iftex
|
|
@end ignore
|
|
|
|
@node makeinfo top, chapter, Structuring Command Types, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@top}
|
|
|
|
The @code{@@top} command is a special sectioning command that you use
|
|
only after an @code{@@node Top} line at the beginning of a Texinfo file.
|
|
The @code{@@top} command tells the @code{makeinfo} formatter
|
|
which node is the `Top'
|
|
node. It has the same typesetting effect as @code{@@unnumbered}
|
|
(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}).
|
|
For detailed information, see
|
|
@ref{makeinfo top command, , The @code{@@top} Command}.@refill
|
|
|
|
@node chapter, unnumbered & appendix, makeinfo top, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@chapter}
|
|
@findex chapter
|
|
|
|
@code{@@chapter} identifies a chapter in the document. Write the
|
|
command at the beginning of a line and follow it on the same line by
|
|
the title of the chapter.@refill
|
|
|
|
For example, this chapter in this manual is entitled ``Chapter
|
|
Structuring''; the @code{@@chapter} line looks like this:@refill
|
|
|
|
@example
|
|
@@chapter Chapter Structuring
|
|
@end example
|
|
|
|
In @TeX{}, the @code{@@chapter} command creates a chapter in the
|
|
document, specifying the chapter title. The chapter is numbered
|
|
automatically.@refill
|
|
|
|
In Info, the @code{@@chapter} command causes the title to appear on a
|
|
line by itself, with a line of asterisks inserted underneath. Thus,
|
|
in Info, the above example produces the following output:@refill
|
|
|
|
@example
|
|
Chapter Structuring
|
|
*******************
|
|
@end example
|
|
|
|
@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@unnumbered}, @code{@@appendix}
|
|
@findex unnumbered
|
|
@findex appendix
|
|
|
|
Use the @code{@@unnumbered} command to create a chapter that appears
|
|
in a printed manual without chapter numbers of any kind. Use the
|
|
@code{@@appendix} command to create an appendix in a printed manual
|
|
that is labelled by letter instead of by number.@refill
|
|
|
|
For Info file output, the @code{@@unnumbered} and @code{@@appendix}
|
|
commands are equivalent to @code{@@chapter}: the title is printed on a
|
|
line by itself with a line of asterisks underneath. (@xref{chapter, ,
|
|
@code{@@chapter}}.)@refill
|
|
|
|
To create an appendix or an unnumbered chapter, write an
|
|
@code{@@appendix} or @code{@@unnumbered} command at the beginning of a
|
|
line and follow it on the same line by the title, as you would if you
|
|
were creating a chapter.@refill
|
|
|
|
@node majorheading & chapheading, section, unnumbered & appendix, Structuring
|
|
@section @code{@@majorheading}, @code{@@chapheading}
|
|
@findex majorheading
|
|
@findex chapheading
|
|
|
|
The @code{@@majorheading} and @code{@@chapheading} commands put
|
|
chapter-like headings in the body of a document.@refill
|
|
|
|
However, neither command causes @TeX{} to produce a numbered heading
|
|
or an entry in the table of contents; and neither command causes
|
|
@TeX{} to start a new page in a printed manual.@refill
|
|
|
|
In @TeX{}, an @code{@@majorheading} command generates a larger vertical
|
|
whitespace before the heading than an @code{@@chapheading} command but
|
|
is otherwise the same.@refill
|
|
|
|
In Info,
|
|
the @code{@@majorheading} and
|
|
@code{@@chapheading} commands are equivalent to
|
|
@code{@@chapter}: the title is printed on a line by itself with a line
|
|
of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
|
|
|
|
@node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@section}
|
|
@findex section
|
|
|
|
In a printed manual, an @code{@@section} command identifies a
|
|
numbered section within a chapter. The section title appears in the
|
|
table of contents. In Info, an @code{@@section} command provides a
|
|
title for a segment of text, underlined with @samp{=}.@refill
|
|
|
|
This section is headed with an @code{@@section} command and looks like
|
|
this in the Texinfo file:@refill
|
|
|
|
@example
|
|
@@section @@code@{@@@@section@}
|
|
@end example
|
|
|
|
To create a section, write the @code{@@section} command at the
|
|
beginning of a line and follow it on the same line by the section
|
|
title.@refill
|
|
|
|
Thus,
|
|
|
|
@example
|
|
@@section This is a section
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
This is a section
|
|
=================
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
in Info.
|
|
|
|
@node unnumberedsec appendixsec heading, subsection, section, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
|
|
@findex unnumberedsec
|
|
@findex appendixsec
|
|
@findex heading
|
|
|
|
The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
|
|
commands are, respectively, the unnumbered, appendix-like, and
|
|
heading-like equivalents of the @code{@@section} command.
|
|
(@xref{section, , @code{@@section}}.)@refill
|
|
|
|
@table @code
|
|
@item @@unnumberedsec
|
|
The @code{@@unnumberedsec} command may be used within an
|
|
unnumbered chapter or within a regular chapter or appendix to
|
|
provide an unnumbered section.@refill
|
|
|
|
@item @@appendixsec
|
|
@itemx @@appendixsection
|
|
@code{@@appendixsection} is a longer spelling of the
|
|
@code{@@appendixsec} command; the two are synonymous.@refill
|
|
@findex appendixsection
|
|
|
|
Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
|
|
command is used only within appendices.@refill
|
|
|
|
@item @@heading
|
|
You may use the @code{@@heading} command anywhere you wish for a
|
|
section-style heading that will not appear in the table of contents.@refill
|
|
@end table
|
|
|
|
@node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section The @code{@@subsection} Command
|
|
@findex subsection
|
|
|
|
Subsections are to sections as sections are to chapters.
|
|
(@xref{section, , @code{@@section}}.) In Info, subsection titles are
|
|
underlined with @samp{-}. For example,@refill
|
|
|
|
@example
|
|
@@subsection This is a subsection
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
This is a subsection
|
|
--------------------
|
|
@end group
|
|
@end example
|
|
|
|
In a printed manual, subsections are listed in the table of contents
|
|
and are numbered three levels deep.@refill
|
|
|
|
@node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section The @code{@@subsection}-like Commands
|
|
@cindex Subsection-like commands
|
|
@findex unnumberedsubsec
|
|
@findex appendixsubsec
|
|
@findex subheading
|
|
|
|
The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
|
|
@code{@@subheading} commands are, respectively, the unnumbered,
|
|
appendix-like, and heading-like equivalents of the @code{@@subsection}
|
|
command. (@xref{subsection, , @code{@@subsection}}.)@refill
|
|
|
|
In Info, the @code{@@subsection}-like commands generate a title
|
|
underlined with hyphens. In a printed manual, an @code{@@subheading}
|
|
command produces a heading like that of a subsection except that it is
|
|
not numbered and does not appear in the table of contents. Similarly,
|
|
an @code{@@unnumberedsubsec} command produces an unnumbered heading like
|
|
that of a subsection and an @code{@@appendixsubsec} command produces a
|
|
subsection-like heading labelled with a letter and numbers; both of
|
|
these commands produce headings that appear in the table of
|
|
contents.@refill
|
|
|
|
@node subsubsection, , unnumberedsubsec appendixsubsec subheading, Structuring
|
|
@comment node-name, next, previous, up
|
|
@section The `subsub' Commands
|
|
@cindex Subsub commands
|
|
@findex subsubsection
|
|
@findex unnumberedsubsubsec
|
|
@findex appendixsubsubsec
|
|
@findex subsubheading
|
|
|
|
The fourth and lowest level sectioning commands in Texinfo are the
|
|
`subsub' commands. They are:@refill
|
|
|
|
@table @code
|
|
@item @@subsubsection
|
|
Subsubsections are to subsections as subsections are to sections.
|
|
(@xref{subsection, , @code{@@subsection}}.) In a printed manual,
|
|
subsubsection titles appear in the table of contents and are numbered
|
|
four levels deep.@refill
|
|
|
|
@item @@unnumberedsubsubsec
|
|
Unnumbered subsubsection titles appear in the table of contents of a
|
|
printed manual, but lack numbers. Otherwise, unnumbered
|
|
subsubsections are the same as subsubsections. In Info, unnumbered
|
|
subsubsections look exactly like ordinary subsubsections.@refill
|
|
|
|
@item @@appendixsubsubsec
|
|
Conventionally, appendix commands are used only for appendices and are
|
|
lettered and numbered appropriately in a printed manual. They also
|
|
appear in the table of contents. In Info, appendix subsubsections look
|
|
exactly like ordinary subsubsections.@refill
|
|
|
|
@item @@subsubheading
|
|
The @code{@@subsubheading} command may be used anywhere that you need
|
|
a small heading that will not appear in the table of contents. In
|
|
Info, subsubheadings look exactly like ordinary subsubsection
|
|
headings.@refill
|
|
@end table
|
|
|
|
In Info, `subsub' titles are underlined with periods.
|
|
For example,@refill
|
|
|
|
@example
|
|
@@subsubsection This is a subsubsection
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
This is a subsubsection
|
|
.......................
|
|
@end group
|
|
@end example
|
|
|
|
@node Nodes, Menus, Structuring, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Nodes
|
|
|
|
@dfn{Nodes} are the primary segments of a Texinfo file. They do not
|
|
themselves impose a hierarchic or any other kind of structure on a file.
|
|
Nodes contain @dfn{node pointers} that name other nodes, and can contain
|
|
@dfn{menus} which are lists of nodes. In Info, the movement commands
|
|
can carry you to a pointed-to node or to a node listed in a menu. Node
|
|
pointers and menus provide structure for Info files just as chapters,
|
|
sections, subsections, and the like, provide structure for printed
|
|
books.@refill
|
|
|
|
@menu
|
|
* 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 @code{makeinfo}.
|
|
@end menu
|
|
|
|
@node Two Paths, Node Menu Illustration, , Nodes
|
|
@ifinfo
|
|
@heading Two Paths
|
|
@end ifinfo
|
|
|
|
The node and menu commands and the chapter structuring commands are
|
|
independent of each other:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
In Info, node and menu commands provide structure. The chapter
|
|
structuring commands generate headings with different kinds of
|
|
underlining---asterisks for chapters, hyphens for sections, and so on;
|
|
they do nothing else.@refill
|
|
|
|
@item
|
|
In @TeX{}, the chapter structuring commands generate chapter and section
|
|
numbers and tables of contents. The node and menu commands provide
|
|
information for cross references; they do nothing else.@refill
|
|
@end itemize
|
|
|
|
You can use node pointers and menus to structure an Info file any way
|
|
you want; and you can write a Texinfo file so that its Info output has a
|
|
different structure than its printed output. However, most Texinfo
|
|
files are written such that the structure for the Info output
|
|
corresponds to the structure for the printed output. It is not
|
|
convenient to do otherwise.@refill
|
|
|
|
Generally, printed output is structured in a tree-like hierarchy in
|
|
which the chapters are the major limbs from which the sections branch
|
|
out. Similarly, node pointers and menus are organized to create a
|
|
matching structure in the Info output.@refill
|
|
|
|
@node Node Menu Illustration, node, Two Paths, Nodes
|
|
@comment node-name, next, previous, up
|
|
@section Node and Menu Illustration
|
|
|
|
Here is a copy of the diagram shown earlier that illustrates a Texinfo
|
|
file with three chapters, each of which contains two sections.@refill
|
|
|
|
Note that the ``root'' is at the top of the diagram and the ``leaves''
|
|
are at the bottom. This is how such a diagram is drawn conventionally;
|
|
it illustrates an upside-down tree. For this reason, the root node is
|
|
called the `Top' node, and `Up' node pointers carry you closer to the
|
|
root.@refill
|
|
|
|
@example
|
|
@group
|
|
Top
|
|
|
|
|
-------------------------------------
|
|
| | |
|
|
Chapter 1 Chapter 2 Chapter 3
|
|
| | |
|
|
-------- -------- --------
|
|
| | | | | |
|
|
Section Section Section Section Section Section
|
|
1.1 1.2 2.1 2.2 3.1 3.2
|
|
|
|
@end group
|
|
@end example
|
|
|
|
Write the beginning of the node for Chapter 2 like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@node Chapter 2, Chapter 3, Chapter 1, top
|
|
@@comment node-name, next, previous, up
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This @code{@@node} line says that the name of this node is ``Chapter 2'', the
|
|
name of the `Next' node is ``Chapter 3'', the name of the `Previous'
|
|
node is ``Chapter 1'', and the name of the `Up' node is ``Top''.
|
|
|
|
@quotation
|
|
@strong{Please Note:} `Next' refers to the next node at the same
|
|
hierarchical level in the manual, not necessarily to the next node
|
|
within the Texinfo file. In the Texinfo file, the subsequent node may
|
|
be at a lower level---a section-level node may follow a chapter-level
|
|
node, and a subsection-level node may follow a section-level node.
|
|
`Next' and `Previous' refer to nodes at the @emph{same} hierarchical
|
|
level. (The `Top' node contains the exception to this rule. Since the
|
|
`Top' node is the only node at that level, `Next' refers to the first
|
|
following node, which is almost always a chapter or chapter-level
|
|
node.)@refill
|
|
@end quotation
|
|
|
|
To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
|
|
2. (@xref{Menus}.) You would write the menu just
|
|
before the beginning of Section 2.1, like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
* Sect. 2.1:: Description of this section.
|
|
* Sect. 2.2::
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
Write the node for Sect. 2.1 like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
|
|
@@comment node-name, next, previous, up
|
|
@end group
|
|
@end example
|
|
|
|
In Info format, the `Next' and `Previous' pointers of a node usually
|
|
lead to other nodes at the same level---from chapter to chapter or from
|
|
section to section (sometimes, as shown, the `Previous' pointer points
|
|
up); an `Up' pointer usually leads to a node at the level above (closer
|
|
to the `Top' node); and a `Menu' leads to nodes at a level below (closer
|
|
to `leaves'). (A cross reference can point to a node at any level;
|
|
see @ref{Cross References}.)@refill
|
|
|
|
Usually, an @code{@@node} command and a chapter structuring command are
|
|
used in sequence, along with indexing commands. (You may follow the
|
|
@code{@@node} line with a comment line that reminds you which pointer is
|
|
which.)@refill
|
|
|
|
Here is the beginning of the chapter in this manual called ``Ending a
|
|
Texinfo File''. This shows an @code{@@node} line followed by a comment
|
|
line, an @code{@@chapter} line, and then by indexing lines.@refill
|
|
|
|
@example
|
|
@group
|
|
@@node Ending a File, Structuring, Beginning a File, Top
|
|
@@comment node-name, next, previous, up
|
|
@@chapter Ending a Texinfo File
|
|
@@cindex Ending a Texinfo file
|
|
@@cindex Texinfo file ending
|
|
@@cindex File ending
|
|
@end group
|
|
@end example
|
|
|
|
@node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes
|
|
@comment node-name, next, previous, up
|
|
@section The @code{@@node} Command
|
|
|
|
@cindex Node, defined
|
|
A @dfn{node} is a segment of text that begins at an @code{@@node}
|
|
command and continues until the next @code{@@node} command. The
|
|
definition of node is different from that for chapter or section. A
|
|
chapter may contain sections and a section may contain subsections;
|
|
but a node cannot contain subnodes; the text of a node continues only
|
|
until the next @code{@@node} command in the file. A node usually
|
|
contains only one chapter structuring command, the one that follows
|
|
the @code{@@node} line. On the other hand, in printed output nodes
|
|
are used only for cross references, so a chapter or section may
|
|
contain any number of nodes. Indeed, a chapter usually contains
|
|
several nodes, one for each section, subsection, and
|
|
subsubsection.@refill
|
|
|
|
To create a node, write an @code{@@node} command at the beginning of a
|
|
line, and follow it with four arguments, separated by commas, on the
|
|
rest of the same line. These arguments are the name of the node, and
|
|
the names of the `Next', `Previous', and `Up' pointers, in that order.
|
|
You may insert spaces before each pointer if you wish; the spaces are
|
|
ignored. You must write the name of the node, and the names of the
|
|
`Next', `Previous', and `Up' pointers, all on the same line. Otherwise,
|
|
the formatters fail. (@inforef{Top, info, info}, for more information
|
|
about nodes in Info.)@refill
|
|
|
|
Usually, you write one of the chapter-structuring command lines
|
|
immediately after an @code{@@node} line---for example, an
|
|
@code{@@section} or @code{@@subsection} line. (@xref{Structuring
|
|
Command Types, , Types of Structuring Command}.)@refill
|
|
|
|
@quotation
|
|
@strong{Please note:} The GNU Emacs Texinfo mode updating commands work
|
|
only with Texinfo files in which @code{@@node} lines are followed by chapter
|
|
structuring lines. @xref{Updating Requirements}.@refill
|
|
@end quotation
|
|
|
|
@TeX{} uses @code{@@node} lines to identify the names to use for cross
|
|
references. For this reason, you must write @code{@@node} lines in a
|
|
Texinfo file that you intend to format for printing, even if you do not
|
|
intend to format it for Info. (Cross references, such as the one at the
|
|
end of this sentence, are made with @code{@@xref} and its related
|
|
commands; see @ref{Cross References}.)@refill
|
|
|
|
@menu
|
|
* Node Names:: How to choose node and pointer names.
|
|
* Writing a Node:: How to write an @code{@@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 @code{@@top} command.
|
|
* Top Node Summary:: Write a brief description for readers.
|
|
@end menu
|
|
|
|
@node Node Names, Writing a Node, , node
|
|
@ifinfo
|
|
@subheading Choosing Node and Pointer Names
|
|
@end ifinfo
|
|
|
|
The name of a node identifies the node. The pointers enable
|
|
you to reach other nodes and consist of the names of those nodes.@refill
|
|
|
|
Normally, a node's `Up' pointer contains the name of the node whose menu
|
|
mentions that node. The node's `Next' pointer contains the name of the
|
|
node that follows that node in that menu and its `Previous' pointer
|
|
contains the name of the node that precedes it in that menu. When a
|
|
node's `Previous' node is the same as its `Up' node, both node pointers
|
|
name the same node.@refill
|
|
|
|
Usually, the first node of a Texinfo file is the `Top' node, and its
|
|
`Up' and `Previous' pointers point to the @file{dir} file, which
|
|
contains the main menu for all of Info.@refill
|
|
|
|
The `Top' node itself contains the main or master menu for the manual.
|
|
Also, it is helpful to include a brief description of the manual in the
|
|
`Top' node. @xref{First Node}, for information on how to write the
|
|
first node of a Texinfo file.@refill
|
|
|
|
@node Writing a Node, Node Line Tips, Node Names, node
|
|
@comment node-name, next, previous, up
|
|
@subsection How to Write an @code{@@node} Line
|
|
@cindex Writing an @code{@@node} line
|
|
@cindex @code{@@node} line writing
|
|
@cindex Node line writing
|
|
|
|
The easiest way to write an @code{@@node} line is to write @code{@@node}
|
|
at the beginning of a line and then the name of the node, like
|
|
this:@refill
|
|
|
|
@example
|
|
@@node @var{node-name}
|
|
@end example
|
|
|
|
If you are using GNU Emacs, you can use the update node commands
|
|
provided by Texinfo mode to insert the names of the pointers; or you
|
|
can leave the pointers out of the Texinfo file and let @code{makeinfo}
|
|
insert node pointers into the Info file it creates. (@xref{Texinfo
|
|
Mode}, and @ref{makeinfo Pointer Creation}.)@refill
|
|
|
|
Alternatively, you can insert the `Next', `Previous', and `Up'
|
|
pointers yourself. If you do this, you may find it helpful to use the
|
|
Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
|
|
@samp{@@node} and a comment line listing the names of the pointers in
|
|
their proper order. The comment line helps you keep track of which
|
|
arguments are for which pointers. This comment line is especially useful
|
|
if you are not familiar with Texinfo.@refill
|
|
|
|
The template for a node line with `Next', `Previous', and `Up' pointers
|
|
looks like this:@refill
|
|
|
|
@example
|
|
@@node @var{node-name}, @var{next}, @var{previous}, @var{up}
|
|
@end example
|
|
|
|
If you wish, you can ignore @code{@@node} lines altogether in your first
|
|
draft and then use the @code{texinfo-insert-node-lines} command to
|
|
create @code{@@node} lines for you. However, we do not
|
|
recommend this practice. It is better to name the node itself
|
|
at the same time that you
|
|
write a segment so you can easily make cross references. A large number
|
|
of cross references are an especially important feature of a good Info
|
|
file.@refill
|
|
|
|
After you have inserted an @code{@@node} line, you should immediately
|
|
write an @@-command for the chapter or section and insert its name.
|
|
Next (and this is important!), put in several index entries. Usually,
|
|
you will find at least two and often as many as four or five ways of
|
|
referring to the node in the index. Use them all. This will make it
|
|
much easier for people to find the node.@refill
|
|
|
|
@node Node Line Tips, Node Line Requirements, Writing a Node, node
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@node} Line Tips
|
|
|
|
Here are three suggestions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Try to pick node names that are informative but short.@refill
|
|
|
|
In the Info file, the file name, node name, and pointer names are all
|
|
inserted on one line, which may run into the right edge of the window.
|
|
(This does not cause a problem with Info, but is ugly.)@refill
|
|
|
|
@item
|
|
Try to pick node names that differ from each other near the beginnings
|
|
of their names. This way, it is easy to use automatic name completion in
|
|
Info.@refill
|
|
|
|
@item
|
|
By convention, node names are capitalized just as they would be for
|
|
section or chapter titles---initial and significant words are
|
|
capitalized; others are not.@refill
|
|
@end itemize
|
|
|
|
@node Node Line Requirements, First Node, Node Line Tips, node
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@node} Line Requirements
|
|
|
|
@cindex Node line requirements
|
|
Here are several requirements for @code{@@node} lines:
|
|
|
|
@itemize @bullet
|
|
@cindex Unique nodename requirement
|
|
@cindex Nodename must be unique
|
|
@item
|
|
All the node names for a single Info file must be unique.@refill
|
|
|
|
Duplicates confuse the Info movement commands. This means, for
|
|
example, that if you end every chapter with a summary, you must name
|
|
each summary node differently. You cannot just call each one
|
|
``Summary''. You may, however, duplicate the titles of chapters, sections,
|
|
and the like. Thus you can end each chapter in a book with a section
|
|
called ``Summary'', so long as the node names for those sections are all
|
|
different.@refill
|
|
|
|
@item
|
|
A pointer name must be the name of a node.@refill
|
|
|
|
The node to which a pointer points may come before or after the
|
|
node containing the pointer.@refill
|
|
|
|
@cindex @@-command in nodename
|
|
@cindex Nodename, cannot contain
|
|
@item
|
|
You cannot use any of the Texinfo @@-commands in a node name;
|
|
@w{@@-commands} confuse Info.@refill
|
|
|
|
@need 750
|
|
Thus, the beginning of the section called @code{@@chapter} looks like
|
|
this:@refill
|
|
|
|
@smallexample
|
|
@group
|
|
@@node chapter, unnumbered & appendix, makeinfo top, Structuring
|
|
@@comment node-name, next, previous, up
|
|
@@section @@code@{@@@@chapter@}
|
|
@@findex chapter
|
|
@end group
|
|
@end smallexample
|
|
|
|
@cindex Comma in nodename
|
|
@cindex Colon in nodename
|
|
@cindex Apostrophe in nodename
|
|
@item
|
|
You cannot use commas, colons, or apostrophes within a node name; these
|
|
confuse @TeX{} or the Info formatters.@refill
|
|
|
|
@need 700
|
|
For example, the following is a section title:
|
|
|
|
@smallexample
|
|
@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The corresponding node name is:
|
|
|
|
@smallexample
|
|
unnumberedsec appendixsec heading
|
|
@end smallexample
|
|
|
|
@cindex Case in nodename
|
|
@item
|
|
Case is significant.
|
|
@end itemize
|
|
|
|
@node First Node, makeinfo top command, Node Line Requirements, node
|
|
@comment node-name, next, previous, up
|
|
@subsection The First Node
|
|
@cindex @samp{@r{Top}} node is first
|
|
@cindex First node
|
|
|
|
The first node of a Texinfo file is the `Top' node, except in an
|
|
included file (@pxref{Include Files}).
|
|
|
|
The `Top' node (which must be named @samp{top} or @samp{Top}) should
|
|
have as its `Up' and `Previous' nodes the name of a node in another
|
|
file, where there is a menu that leads to this file. Specify the file
|
|
name in parentheses. If the file is to be installed directly in the
|
|
Info directory file, use @samp{(dir)} as the parent of the `Top' node;
|
|
this is short for @samp{(dir)top}, and specifies the `Top' node in the
|
|
@file{dir} file, which contains the main menu for Info. For example,
|
|
the @code{@@node Top} line of this manual looks like this:@refill
|
|
|
|
@example
|
|
@@node Top, Overview, (dir), (dir)
|
|
@end example
|
|
|
|
@noindent
|
|
(You may use the Texinfo updating commands or the @code{makeinfo}
|
|
utility to insert these `Next' and @samp{(dir)} pointers
|
|
automatically.)@refill
|
|
|
|
@xref{Install an Info File}, for more information about installing
|
|
an Info file in the @file{info} directory.@refill
|
|
|
|
The `Top' node contains the main or master menu for the document.
|
|
|
|
@node makeinfo top command, Top Node Summary, First Node, node
|
|
@comment node-name, next, previous, up
|
|
@subsection The @code{@@top} Sectioning Command
|
|
@findex top @r{(@@-command)}
|
|
|
|
A special sectioning command, @code{@@top}, has been created for use
|
|
with the @code{@@node Top} line. The @code{@@top} sectioning command tells
|
|
@code{makeinfo} that it marks the `Top' node in the file. It provides
|
|
the information that @code{makeinfo} needs to insert node
|
|
pointers automatically. Write the @code{@@top} command at the
|
|
beginning of the line immediately following the @code{@@node Top}
|
|
line. Write the title on the remaining part of the same line as the
|
|
@code{@@top} command.@refill
|
|
|
|
In Info, the @code{@@top} sectioning command causes the title to appear on a
|
|
line by itself, with a line of asterisks inserted underneath.@refill
|
|
|
|
In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
|
|
sectioning command is merely a synonym for @code{@@unnumbered}.
|
|
Neither of these formatters require an @code{@@top} command, and do
|
|
nothing special with it. You can use @code{@@chapter} or
|
|
@code{@@unnumbered} after the @code{@@node Top} line when you use
|
|
these formatters. Also, you can use @code{@@chapter} or
|
|
@code{@@unnumbered} when you use the Texinfo updating commands to
|
|
create or update pointers and menus.@refill
|
|
|
|
Whatever sectioning command follows an @code{@@node Top} line, whether
|
|
it be @code{@@top} or @code{@@chapter}, the @code{@@node Top} line and
|
|
the immediately following line and any additional text must be
|
|
enclosed between @code{@@ifinfo} and @code{@@end ifinfo} commands.
|
|
(@xref{Conditionals}.) This prevents the title and the accompanying
|
|
text from appearing in printed output. Write the @code{@@ifinfo}
|
|
command before the @code{@@node} line and write the @code{@@end ifinfo} command
|
|
after the @code{@@top} or other sectioning command and after any
|
|
additional text. (You can write the @code{@@end ifinfo} command after
|
|
the @code{@@end menu} command if you like.)@refill
|
|
|
|
@node Top Node Summary, , makeinfo top command, node
|
|
@subsection The `Top' Node Summary
|
|
@cindex @samp{@r{Top}} node summary
|
|
|
|
You can help readers by writing a summary in the `Top' node, after the
|
|
@code{@@top} line, before the main or master menu. The summary should
|
|
briefly describe the Info file. You should also write the version
|
|
number of the program to which the manual applies in this section. This
|
|
helps the reader keep track of which manual is for which version of the
|
|
program. If the manual changes more frequently than the program or is
|
|
independent of it, you should also include an edition number for the
|
|
manual. (The title page should also contain this information:
|
|
see @ref{titlepage, , @code{@@titlepage}}.)@refill
|
|
|
|
Put the whole of the `Top' node, including the @code{@@top} sectioning
|
|
command line if you
|
|
have one, between @code{@@ifinfo} and @code{@@end
|
|
ifinfo} so none of the text appears in the printed output
|
|
(@pxref{Conditionals, , Conditionally Visible Text}). (You may want to
|
|
repeat the brief description from the `Top' node within @code{@@iftex}
|
|
@dots{} @code{@@end iftex} at the beginning of the first chapter, for
|
|
those who read the printed manual.)
|
|
|
|
@node makeinfo Pointer Creation, , node, Nodes
|
|
@section Creating Pointers with @code{makeinfo}
|
|
@cindex Creating pointers with @code{makeinfo}
|
|
@cindex Pointer creation with @code{makeinfo}
|
|
@cindex Automatic pointer creation with @code{makeinfo}
|
|
|
|
The @code{makeinfo} program has a feature for automatically creating
|
|
node pointers for a hierarchically organized file that lacks
|
|
them.@refill
|
|
|
|
When you take advantage of this feature, you do not need to write the
|
|
`Next', `Previous', and `Up' pointers after the name of a node.
|
|
However, you must write a sectioning command, such as @code{@@chapter}
|
|
or @code{@@section}, on the line immediately following each truncated
|
|
@code{@@node} line. You cannot write a comment line after a node
|
|
line; the section line must follow it immediately.@refill
|
|
|
|
In addition, you must follow the `Top' @code{@@node} line with a line beginning
|
|
with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo
|
|
top, , @code{@@top}}.
|
|
|
|
Finally, you must write the name of each node (except for the `Top'
|
|
node) in a menu that is one or more hierarchical levels above the
|
|
node's hierarchical level.@refill
|
|
|
|
This node pointer insertion feature in @code{makeinfo} is an
|
|
alternative to the menu and pointer creation and update commands in
|
|
Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially
|
|
helpful to people who do not use GNU Emacs for writing Texinfo
|
|
documents.@refill
|
|
|
|
@node Menus, Cross References, Nodes, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Menus
|
|
@cindex Menus
|
|
@findex menu
|
|
|
|
@dfn{Menus} contain pointers to subordinate
|
|
nodes.@footnote{Menus can carry you to any node, regardless
|
|
of the hierarchical structure; even to nodes in a different
|
|
Info file. However, the GNU Emacs Texinfo mode updating
|
|
commands work only to create menus of subordinate nodes.
|
|
Conventionally, cross references are used to refer to other
|
|
nodes.} In Info, you use menus to go to such nodes. Menus
|
|
have no effect in printed manuals and do not appear in
|
|
them.@refill
|
|
|
|
By convention, a menu is put at the end of a node since a reader who
|
|
uses the menu may not see text that follows it.@refill
|
|
|
|
@ifinfo
|
|
A node that has a menu should @emph{not} contain much text. If you
|
|
have a lot of text and a menu, move most of the text into a new
|
|
subnode---all but a few lines.@refill
|
|
@end ifinfo
|
|
@iftex
|
|
@emph{A node that has a menu should not contain much text.} If you
|
|
have a lot of text and a menu, move most of the text into a new
|
|
subnode---all but a few lines. Otherwise, a reader with a terminal
|
|
that displays only a few lines may miss the menu and its associated
|
|
text. As a practical matter, you should locate a menu within 20 lines
|
|
of the beginning of the node.@refill
|
|
@end iftex
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Menu Location, Writing a Menu, , Menus
|
|
@ifinfo
|
|
@heading Menus Need Short Nodes
|
|
@end ifinfo
|
|
@cindex Menu location
|
|
@cindex Location of menus
|
|
@cindex Nodes for menus are short
|
|
@cindex Short nodes for menus
|
|
|
|
@ifinfo
|
|
A reader can easily see a menu that is close to the beginning of the
|
|
node. The node should be short. As a practical matter, you should
|
|
locate a menu within 20 lines of the beginning of the node.
|
|
Otherwise, a reader with a terminal that displays only a few lines may
|
|
miss the menu and its associated text.@refill
|
|
@end ifinfo
|
|
|
|
The short text before a menu may look awkward in a printed manual. To
|
|
avoid this, you can write a menu near the beginning of its node and
|
|
follow the menu by an @code{@@node} line, and then an @code{@@heading}
|
|
line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
|
|
the menu, @code{@@node} line, and title appear only in the Info file,
|
|
not the printed document.@refill
|
|
|
|
For example, the preceding two paragraphs follow an Info-only menu,
|
|
@code{@@node} line, and heading, and look like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
* 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 entries.
|
|
* Other Info Files:: How to refer to a different
|
|
Info file.
|
|
@@end menu
|
|
|
|
@@node Menu Location, Writing a Menu, , Menus
|
|
@@ifinfo
|
|
@@heading Menus Need Short Nodes
|
|
@@end ifinfo
|
|
@end group
|
|
@end example
|
|
|
|
The Texinfo file for this document contains more than a dozen
|
|
examples of this procedure. One is at the beginning of this chapter;
|
|
another is at the beginning of the ``Cross References'' chapter.@refill
|
|
|
|
@node Writing a Menu, Menu Parts, Menu Location, Menus
|
|
@section Writing a Menu
|
|
@cindex Writing a menu
|
|
@cindex Menu writing
|
|
|
|
A menu consists of an @code{@@menu} command on a line by
|
|
itself followed by menu entry lines or menu comment lines
|
|
and then by an @code{@@end menu} command on a line by
|
|
itself.@refill
|
|
|
|
A menu looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
Larger Units of Text
|
|
|
|
* Files:: All about handling files.
|
|
* Multiples: Buffers. Multiple buffers; editing
|
|
several files at once.
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
In a menu, every line that begins with an @w{@samp{* }} is a
|
|
@dfn{menu entry}. (Note the space after the asterisk.) A
|
|
line that does not start with an @w{@samp{* }} may also
|
|
appear in a menu. Such a line is not a menu entry but is a
|
|
menu comment line that appears in the Info file. In
|
|
the example above, the line @samp{Larger Units of Text} is a
|
|
menu comment line; the two lines starting with @w{@samp{* }}
|
|
are menu entries.
|
|
|
|
@node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
|
|
@section The Parts of a Menu
|
|
@cindex Parts of a menu
|
|
@cindex Menu parts
|
|
@cindex @code{@@menu} parts
|
|
|
|
A menu entry has three parts, only the second of which is
|
|
required:@refill
|
|
|
|
@enumerate
|
|
@item
|
|
The menu entry name.
|
|
|
|
@item
|
|
The name of the node (required).
|
|
|
|
@item
|
|
A description of the item.
|
|
@end enumerate
|
|
|
|
The template for a menu entry looks like this:@refill
|
|
|
|
@example
|
|
* @var{menu-entry-name}: @var{node-name}. @var{description}
|
|
@end example
|
|
|
|
Follow the menu entry name with a single colon and follow the node name
|
|
with tab, comma, period, or newline.@refill
|
|
|
|
In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
|
|
command. The menu entry name is what the user types after the @kbd{m}
|
|
command.@refill
|
|
|
|
The third part of a menu entry is a descriptive phrase or
|
|
sentence. Menu entry names and node names are often short; the
|
|
description explains to the reader what the node is about. The
|
|
description, which is optional, can spread over two or more lines. A
|
|
useful description complements the node name rather than repeats
|
|
it.@refill
|
|
|
|
@node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
|
|
@comment node-name, next, previous, up
|
|
@section Less Cluttered Menu Entry
|
|
@cindex Two part menu entry
|
|
@cindex Double-colon menu entries
|
|
@cindex Menu entries with two colons
|
|
@cindex Less cluttered menu entry
|
|
@cindex Uncluttered menu entry
|
|
|
|
When the menu entry name and node name are the same, you can write
|
|
the name immediately after the asterisk and space at the beginning of
|
|
the line and follow the name with two colons.@refill
|
|
|
|
@need 800
|
|
For example, write
|
|
|
|
@example
|
|
* Name:: @var{description}
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
instead of
|
|
|
|
@example
|
|
* Name: Name. @var{description}
|
|
@end example
|
|
|
|
You should use the node name for the menu entry name whenever possible,
|
|
since it reduces visual clutter in the menu.@refill
|
|
|
|
@node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
|
|
@comment node-name, next, previous, up
|
|
@section A Menu Example
|
|
@cindex Menu example
|
|
@cindex Example menu
|
|
|
|
A menu looks like this in Texinfo:@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
* menu entry name: Node name. A short description.
|
|
* Node name:: This form is preferred.
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
This produces:
|
|
|
|
@example
|
|
@group
|
|
* menu:
|
|
|
|
* menu entry name: Node name. A short description.
|
|
* Node name:: This form is preferred.
|
|
@end group
|
|
@end example
|
|
|
|
@need 700
|
|
Here is an example as you might see it in a Texinfo file:@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
Larger Units of Text
|
|
|
|
* Files:: All about handling files.
|
|
* Multiples: Buffers. Multiple buffers; editing
|
|
several files at once.
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
This produces:
|
|
|
|
@example
|
|
@group
|
|
* menu:
|
|
Larger Units of Text
|
|
|
|
* Files:: All about handling files.
|
|
* Multiples: Buffers. Multiple buffers; editing
|
|
several files at once.
|
|
@end group
|
|
@end example
|
|
|
|
In this example, the menu has two entries. @samp{Files} is both a menu
|
|
entry name and the name of the node referred to by that name.
|
|
@samp{Multiples} is the menu entry name; it refers to the node named
|
|
@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
|
|
appears in the menu, but is not an entry.@refill
|
|
|
|
Since no file name is specified with either @samp{Files} or
|
|
@samp{Buffers}, they must be the names of nodes in the same Info file
|
|
(@pxref{Other Info Files, , Referring to Other Info Files}).@refill
|
|
|
|
@node Other Info Files, , Menu Example, Menus
|
|
@comment node-name, next, previous, up
|
|
@section Referring to Other Info Files
|
|
@cindex Referring to other Info files
|
|
@cindex Nodes in other Info files
|
|
@cindex Other Info files' nodes
|
|
@cindex Going to other Info files' nodes
|
|
@cindex Info; other files' nodes
|
|
|
|
You can create a menu entry that enables a reader in Info to go to a
|
|
node in another Info file by writing the file name in parentheses just
|
|
before the node name. In this case, you should use the three-part menu
|
|
entry format, which saves the reader from having to type the file
|
|
name.@refill
|
|
|
|
@need 800
|
|
The format looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
|
|
* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
For example, to refer directly to the @samp{Outlining} and
|
|
@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
|
|
menu like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@menu
|
|
* Outlining: (emacs)Outline Mode. The major mode for
|
|
editing outlines.
|
|
* Rebinding: (emacs)Rebinding. How to redefine the
|
|
meaning of a key.
|
|
@@end menu
|
|
@end group
|
|
@end example
|
|
|
|
If you do not list the node name, but only name the file, then Info
|
|
presumes that you are referring to the `Top' node.@refill
|
|
|
|
The @file{dir} file that contains the main menu for Info has menu
|
|
entries that list only file names. These take you directly to the `Top'
|
|
nodes of each Info document. (@xref{Install an Info File}.)@refill
|
|
|
|
@need 700
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
* Info: (info). Documentation browsing system.
|
|
* Emacs: (emacs). The extensible, self-documenting
|
|
text editor.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(The @file{dir} top level directory for the Info system is an Info file,
|
|
not a Texinfo file, but a menu entry looks the same in both types of
|
|
file.)@refill
|
|
|
|
Note that the GNU Emacs Texinfo mode menu updating commands only work
|
|
with nodes within the current buffer, so you cannot use them to create
|
|
menus that refer to other files. You must write such menus by hand.@refill
|
|
|
|
@node Cross References, Marking Text, Menus, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Cross References
|
|
@cindex Making cross references
|
|
@cindex Cross references
|
|
@cindex References
|
|
|
|
@dfn{Cross references} are used to refer the reader to other parts of the
|
|
same or different Texinfo files. In Texinfo, nodes are the
|
|
places to which cross references can refer.@refill
|
|
|
|
@menu
|
|
* 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' @dots{}
|
|
* 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.
|
|
@end menu
|
|
|
|
@node References, Cross Reference Commands, , Cross References
|
|
@ifinfo
|
|
@heading What References Are For
|
|
@end ifinfo
|
|
|
|
Often, but not always, a printed document should be designed so that
|
|
it can be read sequentially. People tire of flipping back and forth
|
|
to find information that should be presented to them as they need
|
|
it.@refill
|
|
|
|
However, in any document, some information will be too detailed for
|
|
the current context, or incidental to it; use cross references to
|
|
provide access to such information. Also, an on-line help system or a
|
|
reference manual is not like a novel; few read such documents in
|
|
sequence from beginning to end. Instead, people look up what they
|
|
need. For this reason, such creations should contain many cross
|
|
references to help readers find other information that they may not
|
|
have read.@refill
|
|
|
|
In a printed manual, a cross reference results in a page reference,
|
|
unless it is to another manual altogether, in which case the cross
|
|
reference names that manual.@refill
|
|
|
|
In Info, a cross reference results in an entry that you can follow using
|
|
the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
|
|
commands, info}.)@refill
|
|
|
|
The various cross reference commands use nodes to define cross
|
|
reference locations. This is evident in Info, in which a cross
|
|
reference takes you to the specified node. @TeX{} also uses nodes to
|
|
define cross reference locations, but the action is less obvious. When
|
|
@TeX{} generates a @sc{dvi} file, it records nodes' page numbers and
|
|
uses the page numbers in making references. Thus, if you are writing
|
|
a manual that will only be printed, and will not be used on-line, you
|
|
must nonetheless write @code{@@node} lines to name the places to which
|
|
you make cross references.@refill
|
|
|
|
@need 800
|
|
@node Cross Reference Commands, Cross Reference Parts, References, Cross References
|
|
@comment node-name, next, previous, up
|
|
@section Different Cross Reference Commands
|
|
@cindex Different cross reference commands
|
|
|
|
There are four different cross reference commands:@refill
|
|
|
|
@table @code
|
|
@item @@xref
|
|
Used to start a sentence in the printed manual saying
|
|
@w{`See @dots{}'} or an entry in the Info file saying
|
|
@samp{*Note @dots{}}.
|
|
|
|
@item @@ref
|
|
Used within or, more often, at the end of a sentence; same as
|
|
@code{@@xref} for Info; produces just the reference in the printed
|
|
manual without a preceding `See'.@refill
|
|
|
|
@item @@pxref
|
|
Used within parentheses to make a reference that suits both an Info
|
|
file and a printed book. Starts with a lower case `see' within the
|
|
printed manual. (@samp{p} is for `parenthesis'.)@refill
|
|
|
|
@item @@inforef
|
|
Used to make a reference to an Info file for which there is no printed
|
|
manual.@refill
|
|
@end table
|
|
|
|
@noindent
|
|
(The @code{@@cite} command is used to make references to books and
|
|
manuals for which there is no corresponding Info file and, therefore,
|
|
no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
|
|
|
|
@node Cross Reference Parts, xref, Cross Reference Commands, Cross References
|
|
@comment node-name, next, previous, up
|
|
@section Parts of a Cross Reference
|
|
@cindex Cross reference parts
|
|
@cindex Parts of a cross reference
|
|
|
|
A cross reference command requires only one argument, which is the
|
|
name of the node to which it refers. But a cross reference command
|
|
may contain up to four additional arguments. By using these
|
|
arguments, you can provide a cross reference name for Info, a topic
|
|
description or section title for the printed output, the name of a
|
|
different Info file, and the name of a different printed
|
|
manual.@refill
|
|
|
|
Here is a simple cross reference example:@refill
|
|
|
|
@example
|
|
@@xref@{Node name@}.
|
|
@end example
|
|
|
|
@noindent
|
|
which produces
|
|
|
|
@example
|
|
*Note Node name::.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Section @var{nnn} [Node name], page @var{ppp}.
|
|
@end quotation
|
|
|
|
@need 700
|
|
Here is an example of a full five-part cross reference:@refill
|
|
|
|
@example
|
|
@group
|
|
@@xref@{Node name, Cross Reference Name, Particular Topic,
|
|
info-file-name, A Printed Manual@}, for details.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
which produces
|
|
|
|
@example
|
|
*Note Cross Reference Name: (info-file-name)Node name,
|
|
for details.
|
|
@end example
|
|
|
|
@noindent
|
|
in Info and
|
|
|
|
@quotation
|
|
See section ``Particular Topic'' in @i{A Printed Manual}, for details.
|
|
@end quotation
|
|
|
|
@noindent
|
|
in a printed book.
|
|
|
|
The five possible arguments for a cross reference are:@refill
|
|
|
|
@enumerate
|
|
@item
|
|
The node name (required). This is the node to which the
|
|
cross reference takes you. In a printed document, the location of the
|
|
node provides the page reference only for references within the same
|
|
document.@refill
|
|
|
|
@item
|
|
The cross reference name for the Info reference, if it is to be different
|
|
from the node name. If you include this argument, it argument becomes
|
|
the first part of the cross reference. It is usually omitted.@refill
|
|
|
|
@item
|
|
A topic description or section name. Often, this is the title of the
|
|
section. This is used as the name of the reference in the printed
|
|
manual. If omitted, the node name is used.@refill
|
|
|
|
@item
|
|
The name of the Info file in which the reference is located, if it is
|
|
different from the current file.@refill
|
|
|
|
@item
|
|
The name of a printed manual from a different Texinfo file.@refill
|
|
@end enumerate
|
|
|
|
The template for a full five argument cross reference looks like
|
|
this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
|
|
@var{info-file-name}, @var{printed-manual-title}@}.
|
|
@end group
|
|
@end example
|
|
|
|
Cross references with one, two, three, four, and five arguments are
|
|
described separately following the description of @code{@@xref}.@refill
|
|
|
|
Write a node name in a cross reference in exactly the same way as in
|
|
the @code{@@node} line, including the same capitalization; otherwise, the
|
|
formatters may not find the reference.@refill
|
|
|
|
You can write cross reference commands within a paragraph, but note
|
|
how Info and @TeX{} format the output of each of the various commands:
|
|
write @code{@@xref} at the beginning of a sentence; write
|
|
@code{@@pxref} only within parentheses, and so on.@refill
|
|
|
|
@node xref, Top Node Naming, Cross Reference Parts, Cross References
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@xref}
|
|
@findex xref
|
|
@cindex Cross references using @code{@@xref}
|
|
@cindex References using @code{@@xref}
|
|
|
|
The @code{@@xref} command generates a cross reference for the
|
|
beginning of a sentence. The Info formatting commands convert it into
|
|
an Info cross reference, which the Info @samp{f} command can use to
|
|
bring you directly to another node. The @TeX{} typesetting commands
|
|
convert it into a page reference, or a reference to another book or
|
|
manual.@refill
|
|
|
|
@menu
|
|
* Reference Syntax:: What a reference looks like and requires.
|
|
* One Argument:: @code{@@xref} with one argument.
|
|
* Two Arguments:: @code{@@xref} with two arguments.
|
|
* Three Arguments:: @code{@@xref} with three arguments.
|
|
* Four and Five Arguments:: @code{@@xref} with four and five arguments.
|
|
@end menu
|
|
|
|
@node Reference Syntax, One Argument, , xref
|
|
@ifinfo
|
|
@subheading What a Reference Looks Like and Requires
|
|
@end ifinfo
|
|
|
|
Most often, an Info cross reference looks like this:@refill
|
|
|
|
@example
|
|
*Note @var{node-name}::.
|
|
@end example
|
|
|
|
@noindent
|
|
or like this
|
|
|
|
@example
|
|
*Note @var{cross-reference-name}: @var{node-name}.
|
|
@end example
|
|
|
|
@noindent
|
|
In @TeX{}, a cross reference looks like this:
|
|
|
|
@example
|
|
See Section @var{section-number} [@var{node-name}], page @var{page}.
|
|
@end example
|
|
|
|
@noindent
|
|
or like this
|
|
|
|
@example
|
|
See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
|
|
@end example
|
|
|
|
The @code{@@xref} command does not generate a period or comma to end
|
|
the cross reference in either the Info file or the printed output.
|
|
You must write that period or comma yourself; otherwise, Info will not
|
|
recognize the end of the reference. (The @code{@@pxref} command works
|
|
differently. @xref{pxref, , @code{@@pxref}}.)@refill
|
|
|
|
@quotation
|
|
@strong{Please note:} A period or comma @strong{must} follow the closing
|
|
brace of an @code{@@xref}. It is required to terminate the cross
|
|
reference. This period or comma will appear in the output, both in
|
|
the Info file and in the printed manual.@refill
|
|
@end quotation
|
|
|
|
@code{@@xref} must refer to an Info node by name. Use @code{@@node}
|
|
to define the node (@pxref{Writing a Node}).@refill
|
|
|
|
@code{@@xref} is followed by several arguments inside braces, separated by
|
|
commas. Whitespace before and after these commas is ignored.@refill
|
|
|
|
A cross reference requires only the name of a node; but it may contain
|
|
up to four additional arguments. Each of these variations produces a
|
|
cross reference that looks somewhat different.@refill
|
|
|
|
@quotation
|
|
@strong{Please note:} Commas separate arguments in a cross reference;
|
|
avoid including them in the title or other part lest the formatters
|
|
mistake them for separators.@refill
|
|
@end quotation
|
|
|
|
@node One Argument, Two Arguments, Reference Syntax, xref
|
|
@subsection @code{@@xref} with One Argument
|
|
|
|
The simplest form of @code{@@xref} takes one argument, the name of
|
|
another node in the same Info file. The Info formatters produce
|
|
output that the Info readers can use to jump to the reference; @TeX{}
|
|
produces output that specifies the page and section number for you.@refill
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@@xref@{Tropical Storms@}.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
*Note Tropical Storms::.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Section 3.1 [Tropical Storms], page 24.
|
|
@end quotation
|
|
|
|
@noindent
|
|
(Note that in the preceding example the closing brace is followed by a
|
|
period.)@refill
|
|
|
|
You can write a clause after the cross reference, like this:@refill
|
|
|
|
@example
|
|
@@xref@{Tropical Storms@}, for more info.
|
|
@end example
|
|
|
|
@noindent
|
|
which produces
|
|
|
|
@example
|
|
*Note Tropical Storms::, for more info.
|
|
@end example
|
|
|
|
@quotation
|
|
See Section 3.1 [Tropical Storms], page 24, for more info.
|
|
@end quotation
|
|
|
|
@noindent
|
|
(Note that in the preceding example the closing brace is followed by a
|
|
comma, and then by the clause, which is followed by a period.)@refill
|
|
|
|
@node Two Arguments, Three Arguments, One Argument, xref
|
|
@subsection @code{@@xref} with Two Arguments
|
|
|
|
With two arguments, the second is used as the name of the Info cross
|
|
reference, while the first is still the name of the node to which the
|
|
cross reference points.@refill
|
|
|
|
@need 750
|
|
@noindent
|
|
The template is like this:
|
|
|
|
@example
|
|
@@xref@{@var{node-name}, @var{cross-reference-name}@}.
|
|
@end example
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@@xref@{Electrical Effects, Lightning@}.
|
|
@end example
|
|
|
|
@noindent
|
|
produces:
|
|
|
|
@example
|
|
*Note Lightning: Electrical Effects.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Section 5.2 [Electrical Effects], page 57.
|
|
@end quotation
|
|
|
|
@noindent
|
|
(Note that in the preceding example the closing brace is followed by a
|
|
period; and that the node name is printed, not the cross reference name.)@refill
|
|
|
|
You can write a clause after the cross reference, like this:@refill
|
|
|
|
@example
|
|
@@xref@{Electrical Effects, Lightning@}, for more info.
|
|
@end example
|
|
|
|
@noindent
|
|
which produces
|
|
@example
|
|
*Note Lightning: Electrical Effects, for more info.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Section 5.2 [Electrical Effects], page 57, for more info.
|
|
@end quotation
|
|
|
|
@noindent
|
|
(Note that in the preceding example the closing brace is followed by a
|
|
comma, and then by the clause, which is followed by a period.)@refill
|
|
|
|
@node Three Arguments, Four and Five Arguments, Two Arguments, xref
|
|
@subsection @code{@@xref} with Three Arguments
|
|
|
|
A third argument replaces the node name in the @TeX{} output. The third
|
|
argument should be the name of the section in the printed output, or
|
|
else state the topic discussed by that section. Often, you will want to
|
|
use initial upper case letters so it will be easier to read when the
|
|
reference is printed. Use a third argument when the node name is
|
|
unsuitable because of syntax or meaning.@refill
|
|
|
|
Remember to avoid placing a comma within the title or topic section of
|
|
a cross reference, or within any other section. The formatters divide
|
|
cross references into arguments according to the commas; a comma
|
|
within a title or other section will divide it into two arguments. In
|
|
a reference, you need to write a title such as ``Clouds, Mist, and
|
|
Fog'' without the commas.@refill
|
|
|
|
Also, remember to write a comma or period after the closing brace of a
|
|
@code{@@xref} to terminate the cross reference. In the following
|
|
examples, a clause follows a terminating comma.@refill
|
|
|
|
|
|
@need 750
|
|
@noindent
|
|
The template is like this:
|
|
|
|
@example
|
|
@group
|
|
@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
|
|
@end group
|
|
@end example
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
|
|
for details.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
*Note Lightning: Electrical Effects, for details.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Section 5.2 [Thunder and Lightning], page 57, for details.
|
|
@end quotation
|
|
|
|
If a third argument is given and the second one is empty, then the
|
|
third argument serves both. (Note how two commas, side by side, mark
|
|
the empty second argument.)@refill
|
|
|
|
@example
|
|
@group
|
|
@@xref@{Electrical Effects, , Thunder and Lightning@},
|
|
for details.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
*Note Thunder and Lightning: Electrical Effects, for details.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Section 5.2 [Thunder and Lightning], page 57, for details.
|
|
@end quotation
|
|
|
|
As a practical matter, it is often best to write cross references with
|
|
just the first argument if the node name and the section title are the
|
|
same, and with the first and third arguments if the node name and title
|
|
are different.@refill
|
|
|
|
Here are several examples from @cite{The GAWK Manual}:@refill
|
|
|
|
@smallexample
|
|
@@xref@{Sample Program@}.
|
|
@@xref@{Glossary@}.
|
|
@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
|
|
@@xref@{Close Output, , Closing Output Files and Pipes@},
|
|
for more information.
|
|
@@xref@{Regexp, , Regular Expressions as Patterns@}.
|
|
@end smallexample
|
|
|
|
@node Four and Five Arguments, , Three Arguments, xref
|
|
@subsection @code{@@xref} with Four and Five Arguments
|
|
|
|
In a cross reference, a fourth argument specifies the name of another
|
|
Info file, different from the file in which the reference appears, and
|
|
a fifth argument specifies its title as a printed manual.@refill
|
|
|
|
Remember that a comma or period must follow the closing brace of an
|
|
@code{@@xref} command to terminate the cross reference. In the
|
|
following examples, a clause follows a terminating comma.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
|
|
@var{info-file-name}, @var{printed-manual-title}@}.
|
|
@end group
|
|
@end example
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@@xref@{Electrical Effects, Lightning, Thunder and Lightning,
|
|
weather, An Introduction to Meteorology@}, for details.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
*Note Lightning: (weather)Electrical Effects, for details.
|
|
@end example
|
|
|
|
@noindent
|
|
The name of the Info file is enclosed in parentheses and precedes
|
|
the name of the node.
|
|
|
|
@noindent
|
|
In a printed manual, the reference looks like this:@refill
|
|
|
|
@quotation
|
|
See section ``Thunder and Lightning'' in @i{An Introduction to
|
|
Meteorology}, for details.
|
|
@end quotation
|
|
|
|
@noindent
|
|
The title of the printed manual is typeset in italics; and the
|
|
reference lacks a page number since @TeX{} cannot know to which page a
|
|
reference refers when that reference is to another manual.@refill
|
|
|
|
Often, you will leave out the second argument when you use the long
|
|
version of @code{@@xref}. In this case, the third argument, the topic
|
|
description, will be used as the cross reference name in Info.@refill
|
|
|
|
@noindent
|
|
The template looks like this:
|
|
|
|
@example
|
|
@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
|
|
@var{printed-manual-title}@}, for details.
|
|
@end example
|
|
|
|
@noindent
|
|
which produces
|
|
|
|
@example
|
|
*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See section @var{title-or-topic} in @var{printed-manual-title}, for details.
|
|
@end quotation
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@@xref@{Electrical Effects, , Thunder and Lightning,
|
|
weather, An Introduction to Meteorology@}, for details.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
*Note Thunder and Lightning: (weather)Electrical Effects,
|
|
for details.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See section ``Thunder and Lightning'' in @i{An Introduction to
|
|
Meteorology}, for details.
|
|
@end quotation
|
|
|
|
On rare occasions, you may want to refer to another Info file that
|
|
is within a single printed manual---when multiple Texinfo files are
|
|
incorporated into the same @TeX{} run but make separate Info files.
|
|
In this case, you need to specify only the fourth argument, and not
|
|
the fifth.@refill
|
|
|
|
@node Top Node Naming, ref, xref, Cross References
|
|
@section Naming a `Top' Node
|
|
@cindex Naming a `Top' Node in references
|
|
@cindex @samp{@r{Top}} node naming for references
|
|
|
|
In a cross reference, you must always name a node. This means that in
|
|
order to refer to a whole manual, you must identify the `Top' node by
|
|
writing it as the first argument to the @code{@@xref} command. (This
|
|
is different from the way you write a menu entry; see @ref{Other Info
|
|
Files, , Referring to Other Info Files}.) At the same time, to
|
|
provide a meaningful section topic or title in the printed cross
|
|
reference (instead of the word `Top'), you must write an appropriate
|
|
entry for the third argument to the @code{@@xref} command.
|
|
@refill
|
|
|
|
@noindent
|
|
Thus, to make a cross reference to @cite{The GNU Make Manual},
|
|
write:@refill
|
|
|
|
@example
|
|
@@xref@{Top, , Overview, make, The GNU Make Manual@}.
|
|
@end example
|
|
|
|
@noindent
|
|
which produces
|
|
|
|
@example
|
|
*Note Overview: (make)Top.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See section ``Overview'' in @i{The GNU Make Manual}.
|
|
@end quotation
|
|
|
|
@noindent
|
|
In this example, @samp{Top} is the name of the first node, and
|
|
@samp{Overview} is the name of the first section of the manual.@refill
|
|
@node ref, pxref, Top Node Naming, Cross References
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@ref}
|
|
@cindex Cross references using @code{@@ref}
|
|
@cindex References using @code{@@ref}
|
|
@findex ref
|
|
|
|
@code{@@ref} is nearly the same as @code{@@xref} except that it does
|
|
not generate a `See' in the printed output, just the reference itself.
|
|
This makes it useful as the last part of a sentence.@refill
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
For more information, see @@ref@{Hurricanes@}.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
For more information, see *Note Hurricanes.
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
For more information, see Section 8.2 [Hurricanes], page 123.
|
|
@end quotation
|
|
|
|
The @code{@@ref} command sometimes leads writers to express themselves
|
|
in a manner that is suitable for a printed manual but looks awkward
|
|
in the Info format. Bear in mind that your audience will be using
|
|
both the printed and the Info format.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
Sea surges are described in @@ref@{Hurricanes@}.
|
|
@end group
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
Sea surges are described in Section 6.7 [Hurricanes], page 72.
|
|
@end quotation
|
|
|
|
@need 800
|
|
@noindent
|
|
in a printed document, and the following in Info:
|
|
|
|
@example
|
|
Sea surges are described in *Note Hurricanes::.
|
|
@end example
|
|
|
|
@quotation
|
|
@strong{Caution:} You @emph{must} write a period or comma immediately
|
|
after an @code{@@ref} command with two or more arguments. Otherwise,
|
|
Info will not find the end of the cross reference entry and its
|
|
attempt to follow the cross reference will fail. As a general rule,
|
|
you should write a period or comma after every @code{@@ref} command.
|
|
This looks best in both the printed and the Info output.@refill
|
|
@end quotation
|
|
|
|
@node pxref, inforef, ref, Cross References
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@pxref}
|
|
@cindex Cross references using @code{@@pxref}
|
|
@cindex References using @code{@@pxref}
|
|
@findex pxref
|
|
|
|
The parenthetical reference command, @code{@@pxref}, is nearly the
|
|
same as @code{@@xref}, but you use it @emph{only} inside parentheses
|
|
and you do @emph{not} type a comma or period after the command's
|
|
closing brace. The command differs from @code{@@xref} in two
|
|
ways:@refill
|
|
|
|
@enumerate
|
|
@item
|
|
@TeX{} typesets the reference for the printed manual with a lower case
|
|
`see' rather than an upper case `See'.@refill
|
|
|
|
@item
|
|
The Info formatting commands automatically end the reference with a
|
|
closing colon or period.@refill
|
|
@end enumerate
|
|
|
|
Because one type of formatting automatically inserts closing
|
|
punctuation and the other does not, you should use @code{@@pxref}
|
|
@emph{only} inside parentheses as part of another sentence. Also, you
|
|
yourself should not insert punctuation after the reference, as you do
|
|
with @code{@@xref}.@refill
|
|
|
|
@code{@@pxref} is designed so that the output looks right and works
|
|
right between parentheses both in printed output and in an Info file.
|
|
In a printed manual, a closing comma or period should not follow a
|
|
cross reference within parentheses; such punctuation is wrong. But in
|
|
an Info file, suitable closing punctuation must follow the cross
|
|
reference so Info can recognize its end. @code{@@pxref} spares you
|
|
the need to use complicated methods to put a terminator into one form
|
|
of the output and not the other.@refill
|
|
|
|
@noindent
|
|
With one argument, a parenthetical cross reference looks like
|
|
this:@refill
|
|
|
|
@example
|
|
@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
which produces
|
|
|
|
@example
|
|
@group
|
|
@dots{} storms cause flooding (*Note Hurricanes::) @dots{}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
|
|
@end quotation
|
|
|
|
With two arguments, a parenthetical cross reference has this
|
|
template:@refill
|
|
|
|
@example
|
|
@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
which produces
|
|
|
|
@example
|
|
@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
and
|
|
|
|
@need 1500
|
|
@quotation
|
|
@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
|
|
@end quotation
|
|
|
|
@code{@@pxref} can be used with up to five arguments just like
|
|
@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
|
|
|
|
@quotation
|
|
@strong{Please note:} Use @code{@@pxref} only as a parenthetical
|
|
reference. Do not try to use @code{@@pxref} as a clause in a sentence.
|
|
It will look bad in either the Info file, the printed output, or
|
|
both.@refill
|
|
|
|
Also, parenthetical cross references look best at the ends of sentences.
|
|
Although you may write them in the middle of a sentence, that location
|
|
breaks up the flow of text.@refill
|
|
@end quotation
|
|
|
|
@node inforef, , pxref, Cross References
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@inforef}
|
|
@cindex Cross references using @code{@@inforef}
|
|
@cindex References using @code{@@inforef}
|
|
@findex inforef
|
|
|
|
@code{@@inforef} is used for cross references to Info files for which
|
|
there are no printed manuals. Even in a printed manual,
|
|
@code{@@inforef} generates a reference directing the user to look in
|
|
an Info file.@refill
|
|
|
|
The command takes either two or three arguments, in the following
|
|
order:@refill
|
|
|
|
@enumerate
|
|
@item
|
|
The node name.
|
|
|
|
@item
|
|
The cross reference name (optional).
|
|
|
|
@item
|
|
The Info file name.
|
|
@end enumerate
|
|
|
|
@noindent
|
|
Separate the arguments with commas, as with @code{@@xref}. Also, you
|
|
must terminate the reference with a comma or period after the
|
|
@samp{@}}, as you do with @code{@@xref}.@refill
|
|
|
|
@noindent
|
|
The template is:
|
|
|
|
@example
|
|
@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
Thus,
|
|
|
|
@example
|
|
@group
|
|
@@inforef@{Expert, Advanced Info commands, info@},
|
|
for more information.
|
|
@end group
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
*Note Advanced Info commands: (info)Expert,
|
|
for more information.
|
|
@end group
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Info file @file{info}, node @samp{Expert}, for more information.
|
|
@end quotation
|
|
|
|
@need 800
|
|
@noindent
|
|
Similarly,
|
|
|
|
@example
|
|
@group
|
|
@@inforef@{Expert, , info@}, for more information.
|
|
@end group
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
*Note (info)Expert::, for more information.
|
|
@end example
|
|
|
|
@need 800
|
|
@noindent
|
|
and
|
|
|
|
@quotation
|
|
See Info file @file{info}, node @samp{Expert}, for more information.
|
|
@end quotation
|
|
|
|
The converse of @code{@@inforef} is @code{@@cite}, which is used to
|
|
refer to printed works for which no Info form exists. @xref{cite, ,
|
|
@code{@@cite}}.@refill
|
|
|
|
@node Marking Text, Quotations and Examples, Cross References, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Marking Words and Phrases
|
|
@cindex Paragraph, marking text within
|
|
@cindex Marking words and phrases
|
|
@cindex Words and phrases, marking them
|
|
@cindex Marking text within a paragraph
|
|
|
|
In Texinfo, you can mark words and phrases in a variety of ways.
|
|
The Texinfo formatters use this information to determine how to
|
|
highlight the text.
|
|
You can specify, for example, whether a word or phrase is a
|
|
defining occurrence, a metasyntactic variable, or a symbol used in a
|
|
program. Also, you can emphasize text.@refill
|
|
|
|
@menu
|
|
* Indicating:: How to indicate definitions, files, etc.
|
|
* Emphasis:: How to emphasize text.
|
|
@end menu
|
|
|
|
@node Indicating, Emphasis, , Marking Text
|
|
@comment node-name, next, previous, up
|
|
@section Indicating Definitions, Commands, etc.
|
|
@cindex Highlighting text
|
|
@cindex Indicating commands, definitions, etc.
|
|
|
|
Texinfo has commands for indicating just what kind of object a piece of
|
|
text refers to. For example, metasyntactic variables are marked by
|
|
@code{@@var}, and code by @code{@@code}. Since the pieces of text are
|
|
labelled by commands that tell what kind of object they are, it is easy
|
|
to change the way the Texinfo formatters prepare such text. (Texinfo is
|
|
an @emph{intentional} formatting language rather than a @emph{typesetting}
|
|
formatting language.)@refill
|
|
|
|
For example, in a printed manual,
|
|
code is usually illustrated in a typewriter font;
|
|
@code{@@code} tells @TeX{} to typeset this text in this font. But it
|
|
would be easy to change the way @TeX{} highlights code to use another
|
|
font, and this change would not effect how keystroke examples are
|
|
highlighted. If straight typesetting commands were used in the body
|
|
of the file and you wanted to make a change, you would need to check
|
|
every single occurrence to make sure that you were changing code and
|
|
not something else that should not be changed.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Useful Highlighting, code, , Indicating
|
|
@ifinfo
|
|
@subheading Highlighting Commands are Useful
|
|
@end ifinfo
|
|
|
|
The highlighting commands can be used to generate useful information
|
|
from the file, such as lists of functions or file names. It is
|
|
possible, for example, to write a program in Emacs Lisp (or a keyboard
|
|
macro) to insert an index entry after every paragraph that contains
|
|
words or phrases marked by a specified command. You could do this to
|
|
construct an index of functions if you had not already made the
|
|
entries.@refill
|
|
|
|
The commands serve a variety of purposes:@refill
|
|
|
|
@table @code
|
|
@item @@code@{@var{sample-code}@}
|
|
Indicate text that is a literal example of a piece of a program.@refill
|
|
|
|
@item @@kbd@{@var{keyboard-characters}@}
|
|
Indicate keyboard input.@refill
|
|
|
|
@item @@key@{@var{key-name}@}
|
|
Indicate the conventional name for a key on a keyboard.@refill
|
|
|
|
@item @@samp@{@var{text}@}
|
|
Indicate text that is a literal example of a sequence of characters.@refill
|
|
|
|
@item @@var@{@var{metasyntactic-variable}@}
|
|
Indicate a metasyntactic variable.@refill
|
|
|
|
@item @@file@{@var{file-name}@}
|
|
Indicate the name of a file.@refill
|
|
|
|
@item @@dfn@{@var{term}@}
|
|
Indicate the introductory or defining use of a term.@refill
|
|
|
|
@item @@cite@{@var{reference}@}
|
|
Indicate the name of a book.@refill
|
|
|
|
@ignore
|
|
@item @@ctrl@{@var{ctrl-char}@}
|
|
Use for an @sc{ascii} control character.@refill
|
|
@end ignore
|
|
@end table
|
|
|
|
@node code, kbd, Useful Highlighting, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@code}@{@var{sample-code}@}
|
|
@findex code
|
|
|
|
Use the @code{@@code} command to indicate text that is a piece of a
|
|
program and which consists of entire syntactic tokens. Enclose the
|
|
text in braces.@refill
|
|
|
|
Thus, you should use @code{@@code} for an expression in a program, for
|
|
the name of a variable or function used in a program, or for a
|
|
keyword. Also, you should use @code{@@code} for the name of a
|
|
program, such as @code{diff}, that is a name used in the machine. (You
|
|
should write the name of a program in the ordinary text font if you
|
|
regard it as a new English word, such as `Emacs' or `Bison'.)@refill
|
|
|
|
Use @code{@@code} for environment variables such as @code{TEXINPUTS},
|
|
and other variables.@refill
|
|
|
|
Use @code{@@code} for command names in command languages that
|
|
resemble programming languages, such as Texinfo or the shell.
|
|
For example, @code{@@code} and @code{@@samp} are produced by writing
|
|
@samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo
|
|
source, respectively.@refill
|
|
|
|
Note, however, that you should not use @code{@@code} for shell options
|
|
such as @samp{-c} when such options stand alone. (Use @code{@@samp}.)
|
|
Also, an entire shell command often looks better if written using
|
|
@code{@@samp} rather than @code{@@code}. In this case, the rule is to
|
|
choose the more pleasing format.@refill
|
|
|
|
It is incorrect to alter the case of a word inside an @code{@@code}
|
|
command when it appears at the beginning of a sentence. Most computer
|
|
languages are case sensitive. In C, for example, @code{Printf} is
|
|
different from the identifier @code{printf}, and most likely is a
|
|
misspelling of it. Even in languages which are not case sensitive, it
|
|
is confusing to a human reader to see identifiers spelled in different
|
|
ways. Pick one spelling and always use that. If you do not want to
|
|
start a sentence with a command written all in lower case, you should
|
|
rearrange the sentence.@refill
|
|
|
|
Do not use the @code{@@code} command for a string of characters shorter
|
|
than a syntactic token. If you are writing about @samp{TEXINPU}, which
|
|
is just a part of the name for the @code{TEXINPUTS} environment
|
|
variable, you should use @code{@@samp}.@refill
|
|
|
|
In particular, you should not use the @code{@@code} command when writing
|
|
about the characters used in a token; do not, for example, use
|
|
@code{@@code} when you are explaining what letters or printable symbols
|
|
can be used in the names of functions. (Use @code{@@samp}.) Also, you
|
|
should not use @code{@@code} to mark text that is considered input to
|
|
programs unless the input is written in a language that is like a
|
|
programming language. For example, you should not use @code{@@code} for
|
|
the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although
|
|
you may use @code{@@code} for the names of the Emacs Lisp functions that
|
|
the keystroke commands invoke.@refill
|
|
|
|
In the printed manual, @code{@@code} causes @TeX{} to typeset the
|
|
argument in a typewriter face. In the Info file, it causes the Info
|
|
formatting commands to use single quotation marks around the text.
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
Use @@code@{diff@} to compare two files.
|
|
@end example
|
|
|
|
@noindent
|
|
produces this in the printed manual:@refill
|
|
|
|
@quotation
|
|
Use @code{diff} to compare two files.
|
|
@end quotation
|
|
@iftex
|
|
|
|
@noindent
|
|
and this in the Info file:@refill
|
|
|
|
@example
|
|
Use `diff' to compare two files.
|
|
@end example
|
|
@end iftex
|
|
|
|
@node kbd, key, code, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@kbd}@{@var{keyboard-characters}@}
|
|
@findex kbd
|
|
|
|
Use the @code{@@kbd} command for characters of input to be typed by
|
|
users. For example, to refer to the characters @kbd{M-a},
|
|
write@refill
|
|
|
|
@example
|
|
@@kbd@{M-a@}
|
|
@end example
|
|
|
|
@noindent
|
|
and to refer to the characters @kbd{M-x shell}, write@refill
|
|
|
|
@example
|
|
@@kbd@{M-x shell@}
|
|
@end example
|
|
|
|
The @code{@@kbd} command has the same effect as @code{@@code} in Info,
|
|
but may produce a different font in a printed manual.@refill
|
|
|
|
You can embed another @@-command inside the braces of an @code{@@kbd}
|
|
command. Here, for example, is the way to describe a command that
|
|
would be described more verbosely as ``press an @samp{r} and then
|
|
press the @key{RET} key'':@refill
|
|
|
|
@example
|
|
@@kbd@{r @@key@{RET@}@}
|
|
@end example
|
|
|
|
@noindent
|
|
This produces: @kbd{r @key{RET}}
|
|
|
|
You also use the @code{@@kbd} command if you are spelling out the letters
|
|
you type; for example:@refill
|
|
|
|
@example
|
|
To give the @@code@{logout@} command,
|
|
type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@quotation
|
|
To give the @code{logout} command,
|
|
type the characters @kbd{l o g o u t @key{RET}}.
|
|
@end quotation
|
|
|
|
(Also, this example shows that you can add spaces for clarity. If you
|
|
really want to mention a space character as one of the characters of
|
|
input, write @kbd{@@key@{SPC@}} for it.)@refill
|
|
|
|
@node key, samp, kbd, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@key}@{@var{key-name}@}
|
|
@findex key
|
|
|
|
Use the @code{@@key} command for the conventional name for a key on a
|
|
keyboard, as in:@refill
|
|
|
|
@example
|
|
@@key@{RET@}
|
|
@end example
|
|
|
|
You can use the @code{@@key} command within the argument of an
|
|
@code{@@kbd} command when the sequence of characters to be typed
|
|
includes one or more keys that are described by name.@refill
|
|
|
|
@need 700
|
|
For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
|
|
|
|
@example
|
|
@@kbd@{C-x @@key@{ESC@}@}
|
|
@end example
|
|
|
|
@c bob: this next sentence looks weird, having a semi-colon followed by
|
|
@c a colon that ends the "sentence".. --mew
|
|
Here is a list of the recommended names for keys; they are all in
|
|
upper case:@refill
|
|
@cindex Recommended names for keys
|
|
@cindex Keys, recommended names
|
|
@cindex Names recommended for keys
|
|
@cindex Abbreviations for keys
|
|
|
|
@quotation
|
|
@table @t
|
|
@item SPC
|
|
Space
|
|
@item RET
|
|
Return
|
|
@item LFD
|
|
Linefeed
|
|
@item TAB
|
|
Tab
|
|
@item BS
|
|
Backspace
|
|
@item ESC
|
|
Escape
|
|
@item DEL
|
|
Delete
|
|
@item SFT
|
|
Shift
|
|
@item CTL
|
|
Control
|
|
@item META
|
|
Meta
|
|
@end table
|
|
@end quotation
|
|
|
|
There are subtleties to handling words like `meta' or `ctl' that are
|
|
names of shift keys. When mentioning a character in which the shift
|
|
key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command alone;
|
|
do not use the @code{@@key} command; but when you are referring to the
|
|
shift key in isolation, use the @code{@@key} command. For example,
|
|
write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
|
|
@samp{@@key@{META@}} to produce @key{META}. This is because
|
|
@kbd{Meta-a} refers to keys that you press on a keyboard, but
|
|
@key{META} refers to a key without implying that you press it. In
|
|
short, use @code{@@kbd} for what you do, and use @code{@@key} for what
|
|
you talk about: ``Press @code{@@kbd@{M-a@}} to move point to the
|
|
beginning of the sentence. The @code{@@key@{META@}} key is often in the
|
|
lower left of the keyboard.''@refill
|
|
@cindex META key
|
|
|
|
@node samp, var, key, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@samp}@{@var{text}@}
|
|
@findex samp
|
|
|
|
Use the @code{@@samp} command to indicate text that is a literal example
|
|
or `sample' of a sequence of characters in a file, string, pattern, etc.
|
|
Enclose the text in braces. The argument appears within single
|
|
quotation marks in both the Info file and the printed manual; in
|
|
addition, it is printed in a fixed-width font.@refill
|
|
|
|
@example
|
|
To match @@samp@{foo@} at the end of the line,
|
|
use the regexp @@samp@{foo$@}.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
To match @samp{foo} at the end of the line, use the regexp
|
|
@samp{foo$}.@refill
|
|
@end quotation
|
|
|
|
Any time you are referring to single characters, you should use
|
|
@code{@@samp} unless @code{@@kbd} is more appropriate. Use
|
|
@code{@@samp} for the names of command-line options. Also, you may use
|
|
@code{@@samp} for entire statements in C and for entire shell
|
|
commands---in this case, @code{@@samp} often looks better than
|
|
@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
|
|
not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
|
|
|
|
Only include punctuation marks within braces if they are part of the
|
|
string you are specifying. Write punctuation marks outside the braces
|
|
if those punctuation marks are part of the English text that surrounds
|
|
the string. In the following sentence, for example, the commas and
|
|
period are outside of the braces:@refill
|
|
|
|
@example
|
|
@group
|
|
In English, the vowels are @@samp@{a@}, @@samp@{e@},
|
|
@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
|
|
@@samp@{y@}.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@quotation
|
|
In English, the vowels are @samp{a}, @samp{e},
|
|
@samp{i}, @samp{o}, @samp{u}, and sometimes
|
|
@samp{y}.
|
|
@end quotation
|
|
|
|
@node var, file, samp, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@var}@{@var{metasyntactic-variable}@}
|
|
@findex var
|
|
|
|
Use the @code{@@var} command to indicate metasyntactic variables. A
|
|
@dfn{metasyntactic variable} is something that stands for another piece of
|
|
text. For example, you should use a metasyntactic variable in the
|
|
documentation of a function to describe the arguments that are passed
|
|
to that function.@refill
|
|
|
|
Do not use @code{@@var} for the names of particular variables in
|
|
programming languages. These are specific names from a program, so
|
|
@code{@@code} is correct for them. For example, the Lisp variable
|
|
@code{texinfo-tex-command} is not a metasyntactic variable; it is
|
|
properly formatted using @code{@@code}.@refill
|
|
|
|
The effect of @code{@@var} in the Info file is to change the case of
|
|
the argument to all upper case; in the printed manual, to italicize it.
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
To delete file @@var@{filename@},
|
|
type @@code@{rm @@var@{filename@}@}.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
To delete file @var{filename}, type @code{rm @var{filename}}.
|
|
@end quotation
|
|
|
|
@noindent
|
|
(Note that @code{@@var} may appear inside @code{@@code},
|
|
@code{@@samp}, @code{@@file}, etc.)@refill
|
|
|
|
Write a metasyntactic variable all in lower case without spaces, and
|
|
use hyphens to make it more readable. Thus, the Texinfo source for
|
|
the illustration of how to begin a Texinfo manual looks like
|
|
this:@refill
|
|
|
|
@example
|
|
@group
|
|
\input texinfo
|
|
@@@@setfilename @@var@{info-file-name@}
|
|
@@@@settitle @@var@{name-of-manual@}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@example
|
|
@group
|
|
\input texinfo
|
|
@@setfilename @var{info-file-name}
|
|
@@settitle @var{name-of-manual}
|
|
@end group
|
|
@end example
|
|
|
|
In some documentation styles, metasyntactic variables are shown with
|
|
angle brackets, for example:@refill
|
|
|
|
@example
|
|
@dots{}, type rm <filename>
|
|
@end example
|
|
|
|
@noindent
|
|
However, that is not the style that Texinfo uses. (You can, of
|
|
course, modify the sources to @TeX{} and the Info formatting commands
|
|
to output the @code{<@dots{}>} format if you wish.)@refill
|
|
|
|
@node file, dfn, var, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@file}@{@var{file-name}@}
|
|
@findex file
|
|
|
|
Use the @code{@@file} command to indicate text that is the name of a
|
|
file, buffer, or directory, or is the name of a node in Info. You can
|
|
also use the command for file name suffixes. Do not use @code{@@file}
|
|
for symbols in a programming language; use @code{@@code}.
|
|
|
|
Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
|
|
For example,@refill
|
|
|
|
@example
|
|
The @@file@{.el@} files are in
|
|
the @@file@{/usr/local/emacs/lisp@} directory.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
The @file{.el} files are in
|
|
the @file{/usr/local/emacs/lisp} directory.
|
|
@end quotation
|
|
|
|
@node dfn, cite, file, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@dfn}@{@var{term}@}
|
|
@findex dfn
|
|
|
|
Use the @code{@@dfn} command to identify the introductory or defining
|
|
use of a technical term. Use the command only in passages whose
|
|
purpose is to introduce a term which will be used again or which the
|
|
reader ought to know. Mere passing mention of a term for the first
|
|
time does not deserve @code{@@dfn}. The command generates italics in
|
|
the printed manual, and double quotation marks in the Info file. For
|
|
example:@refill
|
|
|
|
@example
|
|
Getting rid of a file is called @@dfn@{deleting@} it.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
Getting rid of a file is called @dfn{deleting} it.
|
|
@end quotation
|
|
|
|
As a general rule, a sentence containing the defining occurrence of a
|
|
term should be a definition of the term. The sentence does not need
|
|
to say explicitly that it is a definition, but it should contain the
|
|
information of a definition---it should make the meaning clear.
|
|
|
|
@node cite, , dfn, Indicating
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@cite}@{@var{reference}@}
|
|
@findex cite
|
|
|
|
Use the @code{@@cite} command for the name of a book that lacks a
|
|
companion Info file. The command produces italics in the printed
|
|
manual, and quotation marks in the Info file.@refill
|
|
|
|
(If a book is written in Texinfo, it is better to use a cross reference
|
|
command since a reader can easily follow such a reference in Info.
|
|
@xref{xref, , @code{@@xref}}.)@refill
|
|
@ignore
|
|
|
|
@c node ctrl, , cite, Indicating
|
|
@comment node-name, next, previous, up
|
|
@c subsection @code{@@ctrl}@{@var{ctrl-char}@}
|
|
@findex ctrl
|
|
|
|
The @code{@@ctrl} command is seldom used. It describes an @sc{ascii}
|
|
control character by inserting the actual character into the Info
|
|
file.
|
|
|
|
Usually, in Texinfo, you talk what you type as keyboard entry by
|
|
describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
|
|
@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control
|
|
character that is typed on the keyboard by the user. When talking
|
|
about a control character appearing in a file or a string, do not use
|
|
@code{@@kbd} since the control character is not typed. Also, do not
|
|
use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
|
|
to make it easier for a reader to understand.@refill
|
|
|
|
@code{@@ctrl} is an idea from the beginnings of Texinfo which may not
|
|
really fit in to the scheme of things. But there may be times when
|
|
you want to use the command. The pattern is
|
|
@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character
|
|
whose control-equivalent is wanted. For example, to specify
|
|
@samp{control-f}, you would enter@refill
|
|
|
|
@example
|
|
@@ctrl@{f@}
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
@ctrl{f}
|
|
@end quotation
|
|
|
|
In the Info file, this generates the specified control character, output
|
|
literally into the file. This is done so a user can copy the specified
|
|
control character (along with whatever else he or she wants) into another
|
|
Emacs buffer and use it. Since the `control-h',`control-i', and
|
|
`control-j' characters are formatting characters, they should not be
|
|
indicated with @code{@@ctrl}.@refill
|
|
|
|
In a printed manual, @code{@@ctrl} generates text to describe or
|
|
identify that control character: an uparrow followed by the character
|
|
@var{ch}.@refill
|
|
@end ignore
|
|
|
|
@node Emphasis, , Indicating, Marking Text
|
|
@comment node-name, next, previous, up
|
|
@section Emphasizing Text
|
|
@cindex Emphasizing text
|
|
|
|
Usually, Texinfo changes the font to mark words in the text according to
|
|
what category the words belong to; an example is the @code{@@code} command.
|
|
Most often, this is the best way to mark words.
|
|
However, sometimes you will want to emphasize text without indicating a
|
|
category. Texinfo has two commands to do this. Also, Texinfo has
|
|
several commands that specify the font in which @TeX{} will typeset
|
|
text. These commands have no affect on Info and only one of them,
|
|
the @code{@@r} command, has any regular use.@refill
|
|
|
|
@menu
|
|
* emph & strong:: How to emphasize text in Texinfo.
|
|
* Smallcaps:: How to use the small caps font.
|
|
* Fonts:: Various font commands for printed output.
|
|
@end menu
|
|
|
|
@node emph & strong, Smallcaps, , Emphasis
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
|
|
@cindex Emphasizing text, font for
|
|
@findex emph
|
|
@findex strong
|
|
|
|
The @code{@@emph} and @code{@@strong} commands are for emphasis;
|
|
@code{@@strong} is stronger. In printed output, @code{@@emph}
|
|
produces @emph{italics} and @code{@@strong} produces
|
|
@strong{bold}.@refill
|
|
|
|
@need 800
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@quotation
|
|
@@strong@{Caution:@} @@code@{rm * .[^.]*@} removes @@emph@{all@}
|
|
files in the directory.
|
|
@@end quotation
|
|
@end group
|
|
@end example
|
|
|
|
@iftex
|
|
@noindent
|
|
produces the following in printed output:
|
|
|
|
@quotation
|
|
@strong{Caution}: @code{rm * .[^.]*} removes @emph{all}
|
|
files in the directory.
|
|
@end quotation
|
|
|
|
@noindent
|
|
and the following in Info:
|
|
@end iftex
|
|
@ifinfo
|
|
@noindent
|
|
produces:
|
|
@end ifinfo
|
|
|
|
@example
|
|
*Caution*: `rm * .[^.]*' removes *all*
|
|
files in the directory.
|
|
@end example
|
|
|
|
The @code{@@strong} command is seldom used except to mark what is, in
|
|
effect, a typographical element, such as the word `Caution' in the
|
|
preceding example.
|
|
|
|
In the Info file, both @code{@@emph} and @code{@@strong} put asterisks
|
|
around the text.@refill
|
|
|
|
@quotation
|
|
@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the
|
|
word @samp{Note}; Info will mistake the combination for a cross
|
|
reference. Use a phrase such as @strong{Please note} or
|
|
@strong{Caution} instead.@refill
|
|
@end quotation
|
|
|
|
@node Smallcaps, Fonts, emph & strong, Emphasis
|
|
@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
|
|
@cindex Small caps font
|
|
@findex sc @r{(small caps font)}
|
|
|
|
@iftex
|
|
Use the @samp{@@sc} command to set text in the printed output in @sc{a
|
|
small caps font} and set text in the Info file in upper case letters.@refill
|
|
@end iftex
|
|
@ifinfo
|
|
Use the @samp{@@sc} command to set text in the printed output in a
|
|
small caps font and set text in the Info file in upper case letters.@refill
|
|
@end ifinfo
|
|
|
|
Write the text between braces in lower case, like this:@refill
|
|
|
|
@example
|
|
The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@display
|
|
The @sc{acm} and @sc{ieee} are technical societies.
|
|
@end display
|
|
|
|
@TeX{} typesets the small caps font in a manner that prevents the
|
|
letters from `jumping out at you on the page'. This makes small caps
|
|
text easier to read than text in all upper case. The Info formatting
|
|
commands set all small caps text in upper case.@refill
|
|
|
|
@ifinfo
|
|
If the text between the braces of an @code{@@sc} command is upper case,
|
|
@TeX{} typesets in full-size capitals. Use full-size capitals
|
|
sparingly.@refill
|
|
@end ifinfo
|
|
@iftex
|
|
If the text between the braces of an @code{@@sc} command is upper case,
|
|
@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals
|
|
sparingly.@refill
|
|
@end iftex
|
|
|
|
You may also use the small caps font for a jargon word such as
|
|
@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill
|
|
|
|
There are subtleties to using the small caps font with a jargon word
|
|
such as @sc{cdr}, a word used in Lisp programming. In this case, you
|
|
should use the small caps font when the word refers to the second and
|
|
subsequent elements of a list (the @sc{cdr} of the list), but you
|
|
should use @samp{@@code} when the word refers to the Lisp function of
|
|
the same spelling.@refill
|
|
|
|
@node Fonts, , Smallcaps, Emphasis
|
|
@comment node-name, next, previous, up
|
|
@subsection Fonts for Printing, Not Info
|
|
@cindex Fonts for printing, not for Info
|
|
@findex i @r{(italic font)}
|
|
@findex b @r{(bold font)}
|
|
@findex t @r{(typewriter font)}
|
|
@findex r @r{(Roman font)}
|
|
|
|
Texinfo provides four font commands that specify font changes in the
|
|
printed manual but have no effect in the Info file. @code{@@i}
|
|
requests @i{italic} font (in some versions of @TeX{}, a slanted font
|
|
is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
|
|
@t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
|
|
@r{roman} font, which is the usual font in which text is printed. All
|
|
four commands apply to an argument that follows, surrounded by
|
|
braces.@refill
|
|
|
|
Only the @code{@@r} command has much use: in example programs, you
|
|
can use the @code{@@r} command to convert code comments from the
|
|
fixed-width font to a roman font. This looks better in printed
|
|
output.@refill
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@lisp
|
|
(+ 2 2) ; @@r@{Add two plus two.@}
|
|
@@end lisp
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@lisp
|
|
(+ 2 2) ; @r{Add two plus two.}
|
|
@end lisp
|
|
|
|
If possible, you should avoid using the other three font commands. If
|
|
you need to use one, it probably indicates a gap in the Texinfo
|
|
language.@refill
|
|
|
|
@node Quotations and Examples, Lists and Tables, Marking Text, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Quotations and Examples
|
|
|
|
Quotations and examples are blocks of text consisting of one or more
|
|
whole paragraphs that are set off from the bulk of the text and
|
|
treated differently. They are usually indented.@refill
|
|
|
|
In Texinfo, you always begin a quotation or example by writing an
|
|
@@-command at the beginning of a line by itself, and end it by writing
|
|
an @code{@@end} command that is also at the beginning of a line by
|
|
itself. For instance, you begin an example by writing @code{@@example}
|
|
by itself at the beginning of a line and end the example by writing
|
|
@code{@@end example} on a line by itself, at the beginning of that
|
|
line.@refill
|
|
@findex end
|
|
|
|
@menu
|
|
* 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 @code{@@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.
|
|
@end menu
|
|
|
|
@node Block Enclosing Commands, quotation, , Quotations and Examples
|
|
@section The Block Enclosing Commands
|
|
|
|
Here are commands for quotations and examples:@refill
|
|
|
|
@table @code
|
|
@item @@quotation
|
|
Indicate text that is quoted. The text is filled, indented, and
|
|
printed in a roman font by default.@refill
|
|
|
|
@item @@example
|
|
Illustrate code, commands, and the like. The text is printed
|
|
in a fixed-width font, and indented but not filled.@refill
|
|
|
|
@item @@lisp
|
|
Illustrate Lisp code. The text is printed in a fixed-width font,
|
|
and indented but not filled.@refill
|
|
|
|
@item @@smallexample
|
|
Illustrate code, commands, and the like. Similar to
|
|
@code{@@example}, except that in @TeX{} this command typesets text in
|
|
a smaller font for the smaller @code{@@smallbook} format than for the
|
|
8.5 by 11 inch format.@refill
|
|
|
|
@item @@smalllisp
|
|
Illustrate Lisp code. Similar to @code{@@lisp}, except that
|
|
in @TeX{} this command typesets text in a smaller font for the smaller
|
|
@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill
|
|
|
|
@item @@display
|
|
Display illustrative text. The text is indented but not filled, and
|
|
no font is specified (so, by default, the font is roman).@refill
|
|
|
|
@item @@format
|
|
Print illustrative text. The text is not indented and not filled
|
|
and no font is specified (so, by default, the font is roman).@refill
|
|
@end table
|
|
|
|
The @code{@@exdent} command is used within the above constructs to
|
|
undo the indentation of a line.
|
|
|
|
The @code{@@flushleft} and @code{@@flushright} commands are used to line
|
|
up the left or right margins of unfilled text.@refill
|
|
|
|
The @code{@@noindent} command may be used after one of the above
|
|
constructs to prevent the following text from being indented as a new
|
|
paragraph.@refill
|
|
|
|
You can use the @code{@@cartouche} command within one of the above
|
|
constructs to highlight the example or quotation by drawing a box with
|
|
rounded corners around it. (The @code{@@cartouche} command affects
|
|
only the printed manual; it has no effect in the Info file; see
|
|
@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill
|
|
|
|
@node quotation, example, Block Enclosing Commands, Quotations and Examples
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@quotation}
|
|
@cindex Quotations
|
|
@findex quotation
|
|
|
|
The text of a quotation is
|
|
processed normally except that:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
the margins are closer to the center of the page, so the whole of the
|
|
quotation is indented;@refill
|
|
|
|
@item
|
|
the first lines of paragraphs are indented no more than other
|
|
lines;@refill
|
|
|
|
@item
|
|
in the printed output, interparagraph spacing is reduced.@refill
|
|
@end itemize
|
|
|
|
@quotation
|
|
This is an example of text written between an @code{@@quotation}
|
|
command and an @code{@@end quotation} command. An @code{@@quotation}
|
|
command is most often used to indicate text that is excerpted from
|
|
another (real or hypothetical) printed work.@refill
|
|
@end quotation
|
|
|
|
Write an @code{@@quotation} command as text on a line by itself. This
|
|
line will disappear from the output. Mark the end of the quotation
|
|
with a line beginning with and containing only @code{@@end quotation}.
|
|
The @code{@@end quotation} line will likewise disappear from the
|
|
output. Thus, the following,@refill
|
|
|
|
@example
|
|
@@quotation
|
|
This is
|
|
a foo.
|
|
@@end quotation
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
This is a foo.
|
|
@end quotation
|
|
|
|
@node example, noindent, quotation, Quotations and Examples
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@example}
|
|
@cindex Examples, formatting them
|
|
@cindex Formatting examples
|
|
@findex example
|
|
|
|
The @code{@@example} command is used to indicate an example that is
|
|
not part of the running text, such as computer input or output.@refill
|
|
|
|
@example
|
|
@group
|
|
This is an example of text written between an
|
|
@code{@@example} command
|
|
and an @code{@@end example} command.
|
|
The text is indented but not filled.
|
|
@end group
|
|
|
|
@group
|
|
In the printed manual, the text is typeset in a
|
|
fixed-width font, and extra spaces and blank lines are
|
|
significant. In the Info file, an analogous result is
|
|
obtained by indenting each line with five spaces.
|
|
@end group
|
|
@end example
|
|
|
|
Write an @code{@@example} command at the beginning of a line by itself.
|
|
This line will disappear from the output. Mark the end of the example
|
|
with an @code{@@end example} command, also written at the beginning of a
|
|
line by itself. The @code{@@end example} will disappear from the
|
|
output.@refill
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
@@example
|
|
mv foo bar
|
|
@@end example
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
mv foo bar
|
|
@end example
|
|
|
|
Since the lines containing @code{@@example} and @code{@@end example}
|
|
will disappear, you should put a blank line before the
|
|
@code{@@example} and another blank line after the @code{@@end
|
|
example}. (Remember that blank lines between the beginning
|
|
@code{@@example} and the ending @code{@@end example} will appear in
|
|
the output.)@refill
|
|
|
|
@quotation
|
|
@strong{Caution:} Do not use tabs in the lines of an example (or anywhere
|
|
else in Texinfo, for that matter)! @TeX{} treats tabs as single
|
|
spaces, and that is not what they look like. This is a problem with
|
|
@TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to
|
|
convert tabs in a region to multiple spaces.)@refill
|
|
@end quotation
|
|
|
|
Examples are often, logically speaking, ``in the middle'' of a
|
|
paragraph, and the text continues after an example should not be
|
|
indented. The @code{@@noindent} command prevents a piece of text from
|
|
being indented as if it were a new paragraph.
|
|
@ifinfo
|
|
(@xref{noindent}.)
|
|
@end ifinfo
|
|
|
|
(The @code{@@code} command is used for examples of code that are
|
|
embedded within sentences, not set off from preceding and following
|
|
text. @xref{code, , @code{@@code}}.)
|
|
|
|
@node noindent, Lisp Example, example, Quotations and Examples
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@noindent}
|
|
@findex noindent
|
|
|
|
An example or other inclusion can break a paragraph into segments.
|
|
Ordinarily, the formatters indent text that follows an example as a new
|
|
paragraph. However, you can prevent this by writing @code{@@noindent}
|
|
at the beginning of a line by itself preceding the continuation
|
|
text.@refill
|
|
|
|
@need 750
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
@@example
|
|
This is an example
|
|
@@end example
|
|
|
|
@@noindent
|
|
This line is not indented. As you can see, the
|
|
beginning of the line is fully flush left with the line
|
|
that follows after it. (This whole example is between
|
|
@@code@{@@@@display@} and @@code@{@@@@end display@}.)
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@display
|
|
@example
|
|
This is an example
|
|
@end example
|
|
@tex
|
|
% Remove extra vskip; this is a kludge to counter the effect of display
|
|
\vskip-3.5\baselineskip
|
|
@end tex
|
|
|
|
@noindent
|
|
This line is not indented. As you can see, the
|
|
beginning of the line is fully flush left with the line
|
|
that follows after it. (This whole example is between
|
|
@code{@@display} and @code{@@end display}.)
|
|
@end display
|
|
|
|
To adjust the number of blank lines properly in the Info file output,
|
|
remember that the line containing @code{@@noindent} does not generate a
|
|
blank line, and neither does the @code{@@end example} line.@refill
|
|
|
|
In the Texinfo source file for this manual, each line that says
|
|
`produces' is preceded by a line containing @code{@@noindent}.@refill
|
|
|
|
Do not put braces after an @code{@@noindent} command; they are not
|
|
necessary, since @code{@@noindent} is a command used outside of
|
|
paragraphs (@pxref{Command Syntax}).@refill
|
|
|
|
@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@lisp}
|
|
@cindex Lisp example
|
|
@findex lisp
|
|
|
|
The @code{@@lisp} command is used for Lisp code. It is synonymous
|
|
with the @code{@@example} command.
|
|
|
|
@lisp
|
|
This is an example of text written between an
|
|
@code{@@lisp} command and an @code{@@end lisp} command.
|
|
@end lisp
|
|
|
|
Use @code{@@lisp} instead of @code{@@example} so as to preserve
|
|
information regarding the nature of the example. This is useful, for
|
|
example, if you write a function that evaluates only and all the Lisp
|
|
code in a Texinfo file. Then you can use the Texinfo file as a Lisp
|
|
library.@footnote{It would be straightforward to extend Texinfo to
|
|
work in a similar fashion for C, @sc{fortran}, or other languages.}@refill
|
|
|
|
Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
|
|
itself.@refill
|
|
|
|
@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@smallexample} and @code{@@smalllisp}
|
|
@cindex Small book example
|
|
@cindex Example for a small book
|
|
@cindex Lisp example for a small book
|
|
@findex smallexample
|
|
@findex smalllisp
|
|
|
|
In addition to the regular @code{@@example} and @code{@@lisp} commands,
|
|
Texinfo has two other ``example-style'' commands. These are the
|
|
@code{@@smallexample} and @code{@@smalllisp} commands. Both these
|
|
commands are designed for use with the @code{@@smallbook} command that
|
|
causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format
|
|
rather than the regular 8.5 by 11 inch format.@refill
|
|
|
|
In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands
|
|
typeset text in a smaller font for the smaller @code{@@smallbook}
|
|
format than for the 8.5 by 11 inch format. Consequently, many examples
|
|
containing long lines fit in a narrower, @code{@@smallbook} page
|
|
without needing to be shortened. Both commands typeset in the normal
|
|
font size when you format for the 8.5 by 11 inch size; indeed,
|
|
in this situation, the @code{@@smallexample} and @code{@@smalllisp}
|
|
commands are defined to be the @code{@@example} and @code{@@lisp}
|
|
commands.@refill
|
|
|
|
In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are
|
|
equivalent to the @code{@@example} and @code{@@lisp} commands, and work
|
|
exactly the same.@refill
|
|
|
|
Mark the end of @code{@@smallexample} or @code{@@smalllisp} with
|
|
@code{@@end smallexample} or @code{@@end smalllisp},
|
|
respectively.@refill
|
|
|
|
@iftex
|
|
Here is an example written in the small font used by the
|
|
@code{@@smallexample} and @code{@@smalllisp} commands:
|
|
|
|
@ifclear smallbook
|
|
@display
|
|
@tex
|
|
% Remove extra vskip; this is a kludge to counter the effect of display
|
|
\vskip-3\baselineskip
|
|
{\ninett
|
|
\dots{} to make sure that you have the freedom to
|
|
distribute copies of free software (and charge for
|
|
this service if you wish), that you receive source
|
|
code or can get it if you want it, that you can
|
|
change the software or use pieces of it in new free
|
|
programs; and that you know you can do these things.}
|
|
@end tex
|
|
@end display
|
|
@end ifclear
|
|
@end iftex
|
|
@ifset smallbook
|
|
@iftex
|
|
@smallexample
|
|
This is an example of text written between @code{@@smallexample} and
|
|
@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
|
|
this text appears in its normal size; but in a 7 by 9.25 inch manual,
|
|
this text appears in a smaller font.
|
|
@end smallexample
|
|
@end iftex
|
|
@end ifset
|
|
@ifinfo
|
|
@smallexample
|
|
This is an example of text written between @code{@@smallexample} and
|
|
@code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
|
|
this text appears in its normal size; but in a 7 by 9.25 inch manual,
|
|
this text appears in a smaller font.
|
|
@end smallexample
|
|
@end ifinfo
|
|
|
|
The @code{@@smallexample} and @code{@@smalllisp} commands make it
|
|
easier to prepare smaller format manuals without forcing you to edit
|
|
examples by hand to fit them onto narrower pages.@refill
|
|
|
|
As a general rule, a printed document looks better if you write all the
|
|
examples in a chapter consistently in @code{@@example} or in
|
|
@code{@@smallexample}. Only occasionally should you mix the two
|
|
formats.@refill
|
|
|
|
@xref{smallbook, , Printing ``Small'' Books}, for more information
|
|
about the @code{@@smallbook} command.@refill
|
|
|
|
@node display, format, smallexample & smalllisp, Quotations and Examples
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@display}
|
|
@cindex Display formatting
|
|
@findex display
|
|
|
|
The @code{@@display} command begins a kind of example. It is like the
|
|
@code{@@example} command
|
|
except that, in
|
|
a printed manual, @code{@@display} does not select the fixed-width
|
|
font. In fact, it does not specify the font at all, so that the text
|
|
appears in the same font it would have appeared in without the
|
|
@code{@@display} command.@refill
|
|
|
|
@display
|
|
This is an example of text written between an @code{@@display} command
|
|
and an @code{@@end display} command. The @code{@@display} command
|
|
indents the text, but does not fill it.
|
|
@end display
|
|
|
|
@node format, exdent, display, Quotations and Examples
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@format}
|
|
@findex format
|
|
|
|
The @code{@@format} command is similar to @code{@@example} except
|
|
that, in the printed manual, @code{@@format} does not select the
|
|
fixed-width font and does not narrow the margins.@refill
|
|
|
|
@format
|
|
This is an example of text written between an @code{@@format} command
|
|
and an @code{@@end format} command. As you can see
|
|
from this example,
|
|
the @code{@@format} command does not fill the text.
|
|
@end format
|
|
|
|
@node exdent, flushleft & flushright, format, Quotations and Examples
|
|
@section @code{@@exdent}: Undoing a Line's Indentation
|
|
@cindex Indentation undoing
|
|
@findex exdent
|
|
|
|
The @code{@@exdent} command removes any indentation a line might have.
|
|
The command is written at the beginning of a line and applies only to
|
|
the text that follows the command that is on the same line. Do not use
|
|
braces around the text. In a printed manual, the text on an
|
|
@code{@@exdent} line is printed in the roman font.@refill
|
|
|
|
@code{@@exdent} is usually used within examples. Thus,@refill
|
|
|
|
@example
|
|
@group
|
|
@@example
|
|
This line follows an @@@@example command.
|
|
@@exdent This line is exdented.
|
|
This line follows the exdented line.
|
|
The @@@@end example comes on the next line.
|
|
@@end group
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
This line follows an @@example command.
|
|
@exdent This line is exdented.
|
|
This line follows the exdented line.
|
|
The @@end example comes on the next line.
|
|
@end group
|
|
@end example
|
|
|
|
In practice, the @code{@@exdent} command is rarely used.
|
|
Usually, you un-indent text by ending the example and
|
|
returning the page to its normal width.@refill
|
|
|
|
@node flushleft & flushright, cartouche, exdent, Quotations and Examples
|
|
@section @code{@@flushleft} and @code{@@flushright}
|
|
@findex flushleft
|
|
@findex flushright
|
|
|
|
The @code{@@flushleft} and @code{@@flushright} commands line up the
|
|
ends of lines on the left and right margins of a page,
|
|
but do not fill the text. The commands are written on lines of their
|
|
own, without braces. The @code{@@flushleft} and @code{@@flushright}
|
|
commands are ended by @code{@@end flushleft} and @code{@@end
|
|
flushright} commands on lines of their own.@refill
|
|
|
|
@need 800
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@flushleft
|
|
This text is
|
|
written flushleft.
|
|
@@end flushleft
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
@flushleft
|
|
This text is
|
|
written flushleft.
|
|
@end flushleft
|
|
@end quotation
|
|
|
|
|
|
Flushright produces the type of indentation often used in the return
|
|
address of letters.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@flushright
|
|
Here is an example of text written
|
|
flushright. The @@code@{@@flushright@} command
|
|
right justifies every line but leaves the
|
|
left end ragged.
|
|
@@end flushright
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@flushright
|
|
Here is an example of text written
|
|
flushright. The @code{@@flushright} command
|
|
right justifies every line but leaves the
|
|
left end ragged.
|
|
@end flushright
|
|
|
|
@node cartouche, , flushleft & flushright, Quotations and Examples
|
|
@section Drawing Cartouches Around Examples
|
|
@findex cartouche
|
|
@cindex Box with rounded corners
|
|
|
|
In a printed manual, the @code{@@cartouche} command draws a box with
|
|
rounded corners around its contents. You can use this command to
|
|
further highlight an example or quotation. For instance, you could
|
|
write a manual in which one type of example is surrounded by a cartouche
|
|
for emphasis.@refill
|
|
|
|
The @code{@@cartouche} command affects only the printed manual; it has
|
|
no effect in the Info file.@refill
|
|
|
|
@need 1500
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@example
|
|
@@cartouche
|
|
% pwd
|
|
/usr/local/lib/emacs/info
|
|
@@end cartouche
|
|
@@end example
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
surrounds the two-line example with a box with rounded corners, in the
|
|
printed manual.
|
|
|
|
@iftex
|
|
In a printed manual, the example looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@cartouche
|
|
% pwd
|
|
/usr/local/lib/emacs/info
|
|
@end cartouche
|
|
@end group
|
|
@end example
|
|
@end iftex
|
|
|
|
@node Lists and Tables, Indices, Quotations and Examples, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Making Lists and Tables
|
|
@cindex Making lists and tables
|
|
@cindex Lists and tables, making them
|
|
@cindex Tables and lists, making them
|
|
|
|
Texinfo has several ways of making lists and two-column tables. Lists can
|
|
be bulleted or numbered, while two-column tables can highlight the items in
|
|
the first column.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@ifinfo
|
|
@node Introducing Lists, itemize, , Lists and Tables
|
|
@heading Introducing Lists
|
|
@end ifinfo
|
|
|
|
Texinfo automatically indents the text in lists or tables, and numbers
|
|
an enumerated list. This last feature is useful if you modify the
|
|
list, since you do not need to renumber it yourself.@refill
|
|
|
|
Numbered lists and tables begin with the appropriate @@-command at the
|
|
beginning of a line, and end with the corresponding @code{@@end}
|
|
command on a line by itself. The table and itemized-list commands
|
|
also require that you write formatting information on the same line as
|
|
the beginning @@-command.@refill
|
|
|
|
Begin an enumerated list, for example, with an @code{@@enumerate}
|
|
command and end the list with an @code{@@end enumerate} command.
|
|
Begin an itemized list with an @code{@@itemize} command, followed on
|
|
the same line by a formatting command such as @code{@@bullet}, and end
|
|
the list with an @code{@@end itemize} command.@refill
|
|
@findex end
|
|
|
|
Precede each element of a list with an @code{@@item} or @code{@@itemx}
|
|
command.@refill
|
|
|
|
@sp 1
|
|
@noindent
|
|
Here is an itemized list of the different kinds of table and lists:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Itemized lists with and without bullets.
|
|
|
|
@item
|
|
Enumerated lists, using numbers or letters.
|
|
|
|
@item
|
|
Two-column tables with highlighting.
|
|
@end itemize
|
|
|
|
@sp 1
|
|
@noindent
|
|
Here is an enumerated list with the same items:@refill
|
|
|
|
@enumerate
|
|
@item
|
|
Itemized lists with and without bullets.
|
|
|
|
@item
|
|
Enumerated lists, using numbers or letters.
|
|
|
|
@item
|
|
Two-column tables with highlighting.
|
|
@end enumerate
|
|
|
|
@sp 1
|
|
@noindent
|
|
And here is a two-column table with the same items and their
|
|
@w{@@-commands}:@refill
|
|
|
|
@table @code
|
|
@item @@itemize
|
|
Itemized lists with and without bullets.
|
|
|
|
@item @@enumerate
|
|
Enumerated lists, using numbers or letters.
|
|
|
|
@item @@table
|
|
@itemx @@ftable
|
|
@itemx @@vtable
|
|
Two-column tables with highlighting.
|
|
@end table
|
|
|
|
@node itemize, enumerate, Introducing Lists, Lists and Tables
|
|
@comment node-name, next, previous, up
|
|
@section Making an Itemized List
|
|
@cindex Itemization
|
|
@findex itemize
|
|
|
|
The @code{@@itemize} command produces sequences of indented
|
|
paragraphs, with a bullet or other mark inside the left margin
|
|
at the beginning of each paragraph for which such a mark is desired.@refill
|
|
|
|
Begin an itemized list by writing @code{@@itemize} at the beginning of
|
|
a line. Follow the command, on the same line, with a character or a
|
|
Texinfo command that generates a mark. Usually, you will write
|
|
@code{@@bullet} after @code{@@itemize}, but you can use
|
|
@code{@@minus}, or any character or any special symbol that results in
|
|
a single character in the Info file. (When you write @code{@@bullet}
|
|
or @code{@@minus} after an @code{@@itemize} command, you may omit the
|
|
@samp{@{@}}.)@refill
|
|
|
|
Write the text of the indented paragraphs themselves after the
|
|
@code{@@itemize}, up to another line that says @code{@@end
|
|
itemize}.@refill
|
|
|
|
Before each paragraph for which a mark in the margin is desired, write
|
|
a line that says just @code{@@item}. Do not write any other text on this
|
|
line.@refill
|
|
@findex item
|
|
|
|
Usually, you should put a blank line before an @code{@@item}. This
|
|
puts a blank line in the Info file. (@TeX{} inserts the proper
|
|
interline whitespace in either case.) Except when the entries are
|
|
very brief, these blank lines make the list look better.@refill
|
|
|
|
Here is an example of the use of @code{@@itemize}, followed by the
|
|
output it produces. Note that @code{@@bullet} produces an @samp{*} in
|
|
Info and a round dot in @TeX{}.@refill
|
|
|
|
@example
|
|
@group
|
|
@@itemize @@bullet
|
|
@@item
|
|
Some text for foo.
|
|
|
|
@@item
|
|
Some text
|
|
for bar.
|
|
@@end itemize
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@quotation
|
|
@itemize @bullet
|
|
@item
|
|
Some text for foo.
|
|
|
|
@item
|
|
Some text
|
|
for bar.
|
|
@end itemize
|
|
@end quotation
|
|
|
|
Itemized lists may be embedded within other itemized lists. Here is a
|
|
list marked with dashes embedded in a list marked with bullets:@refill
|
|
|
|
@example
|
|
@group
|
|
@@itemize @@bullet
|
|
@@item
|
|
First item.
|
|
|
|
@@itemize @@minus
|
|
@@item
|
|
Inner item.
|
|
|
|
@@item
|
|
Second inner item.
|
|
@@end itemize
|
|
|
|
@@item
|
|
Second outer item.
|
|
@@end itemize
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@quotation
|
|
@itemize @bullet
|
|
@item
|
|
First item.
|
|
|
|
@itemize @minus
|
|
@item
|
|
Inner item.
|
|
|
|
@item
|
|
Second inner item.
|
|
@end itemize
|
|
|
|
@item
|
|
Second outer item.
|
|
@end itemize
|
|
@end quotation
|
|
|
|
@node enumerate, Two-column Tables, itemize, Lists and Tables
|
|
@comment node-name, next, previous, up
|
|
@section Making a Numbered or Lettered List
|
|
@cindex Enumeration
|
|
@findex enumerate
|
|
|
|
@code{@@enumerate} is like @code{@@itemize} except that the marks in
|
|
the left margin contain successive integers or letters.
|
|
(@xref{itemize, , @code{@@itemize}}.)@refill
|
|
|
|
Write the @code{@@enumerate} command at the beginning of a line.
|
|
The command does not require an argument, but accepts either a number or
|
|
a letter as an option.
|
|
Without an argument, @code{@@enumerate} starts the list
|
|
with the number 1. With a numeric argument, such as 3,
|
|
the command starts the list with that number.
|
|
With an upper or lower case letter, such as @kbd{a} or @kbd{A},
|
|
the command starts the list with that letter.@refill
|
|
|
|
Write the text of the enumerated list in the same way you write an
|
|
itemized list: put @code{@@item} on a line of its own before the start of
|
|
each paragraph that you want enumerated. Do not write any other text on
|
|
the line beginning with @code{@@item}.@refill
|
|
|
|
You should put a blank line between entries in the list.
|
|
This generally makes it easier to read the Info file.@refill
|
|
|
|
@need 1500
|
|
Here is an example of @code{@@enumerate} without an argument:@refill
|
|
|
|
@example
|
|
@group
|
|
@@enumerate
|
|
@@item
|
|
Underlying causes.
|
|
|
|
@@item
|
|
Proximate causes.
|
|
@@end enumerate
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@enumerate
|
|
@item
|
|
Underlying causes.
|
|
|
|
@item
|
|
Proximate causes.
|
|
@end enumerate
|
|
@sp 1
|
|
Here is an example with an argument of @kbd{3}:@refill
|
|
@sp 1
|
|
@example
|
|
@group
|
|
@@enumerate 3
|
|
@@item
|
|
Predisposing causes.
|
|
|
|
@@item
|
|
Precipitating causes.
|
|
|
|
@@item
|
|
Perpetuating causes.
|
|
@@end enumerate
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@enumerate 3
|
|
@item
|
|
Predisposing causes.
|
|
|
|
@item
|
|
Precipitating causes.
|
|
|
|
@item
|
|
Perpetuating causes.
|
|
@end enumerate
|
|
@sp 1
|
|
Here is a brief summary of the alternatives. The summary is constructed
|
|
using @code{@@enumerate} with an argument of @kbd{a}.@refill
|
|
@sp 1
|
|
@enumerate a
|
|
@item
|
|
@code{@@enumerate}
|
|
|
|
Without an argument, produce a numbered list, starting with the number
|
|
1.@refill
|
|
|
|
@item
|
|
@code{@@enumerate @var{positive-integer}}
|
|
|
|
With a (positive) numeric argument, start a numbered list with that
|
|
number. You can use this to continue a list that you interrupted with
|
|
other text.@refill
|
|
|
|
@item
|
|
@code{@@enumerate @var{upper-case-letter}}
|
|
|
|
With an upper case letter as argument, start a list
|
|
in which each item is marked
|
|
by a letter, beginning with that upper case letter.@refill
|
|
|
|
@item
|
|
@code{@@enumerate @var{lower-case-letter}}
|
|
|
|
With a lower case letter as argument, start a list
|
|
in which each item is marked by
|
|
a letter, beginning with that lower case letter.@refill
|
|
@end enumerate
|
|
|
|
You can also nest enumerated lists, as in an outline.@refill
|
|
|
|
@node Two-column Tables, , enumerate, Lists and Tables
|
|
@comment node-name, next, previous, up
|
|
@section Making a Two-column Table
|
|
@cindex Tables, making two-column
|
|
@findex table
|
|
|
|
@code{@@table} is similar to @code{@@itemize}, but the command allows
|
|
you to specify a name or heading line for each item. (@xref{itemize,
|
|
, @code{@@itemize}}.) The @code{@@table} command is used to produce
|
|
two-column tables, and is especially useful for glossaries and
|
|
explanatory exhibits.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@ifinfo
|
|
@node table, ftable vtable, , Two-column Tables
|
|
@subheading Using the @code{@@table} Command
|
|
|
|
Use the @code{@@table} command to produce two-column tables.@refill
|
|
@end ifinfo
|
|
|
|
Write the @code{@@table} command at the beginning of a line and follow
|
|
it on the same line with an argument that is a Texinfo command such as
|
|
@code{@@code}, @code{@@samp}, @code{@@var}, or @code{@@kbd}.
|
|
Although these commands are usually followed by arguments in braces,
|
|
in this case you use the command name without an argument because
|
|
@code{@@item} will supply the argument. This command will be applied
|
|
to the text that goes into the first column of each item and
|
|
determines how it will be highlighted. For example, @code{@@samp}
|
|
will cause the text in the first column to be highlighted with an
|
|
@code{@@samp} command.@refill
|
|
|
|
You may also choose to use the @code{@@asis} command as an argument to
|
|
@code{@@table}. @code{@@asis} is a command that does nothing; if you use this
|
|
command after @code{@@table}, @TeX{} and the Info formatting commands
|
|
output the first column entries without added highlighting (`as
|
|
is').@refill
|
|
|
|
(The @code{@@table} command may work with other commands besides those
|
|
listed here. However, you can only use commands
|
|
that normally take arguments in braces.)@refill
|
|
|
|
Begin each table entry with an @code{@@item} command at the beginning
|
|
of a line. Write the first column text on the same line as the
|
|
@code{@@item} command. Write the second column text on the line
|
|
following the @code{@@item} line and on subsequent lines. (You do not
|
|
need to type anything for an empty second column entry.) You may
|
|
write as many lines of supporting text as you wish, even several
|
|
paragraphs. But only text on the same line as the @code{@@item} will
|
|
be placed in the first column.@refill
|
|
@findex item
|
|
|
|
Normally, you should put a blank line before an @code{@@item} line.
|
|
This puts a blank like in the Info file. Except when the entries are
|
|
very brief, a blank line looks better.@refill
|
|
|
|
@need 1500
|
|
The following table, for example, highlights the text in the first
|
|
column with an @code{@@samp} command:@refill
|
|
|
|
@example
|
|
@group
|
|
@@table @@samp
|
|
@@item foo
|
|
This is the text for
|
|
@@samp@{foo@}.
|
|
|
|
@@item bar
|
|
Text for @@samp@{bar@}.
|
|
@@end table
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@table @samp
|
|
@item foo
|
|
This is the text for
|
|
@samp{foo}.
|
|
@item bar
|
|
Text for @samp{bar}.
|
|
@end table
|
|
|
|
If you want to list two or more named items with a single block of
|
|
text, use the @code{@@itemx} command. (@xref{itemx, ,
|
|
@code{@@itemx}}.)@refill
|
|
|
|
@node ftable vtable, itemx, table, Two-column Tables
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@ftable} and @code{@@vtable}
|
|
@cindex Tables with indexes
|
|
@cindex Indexing table entries automatically
|
|
@findex ftable
|
|
@findex vtable
|
|
|
|
The @code{@@ftable} and @code{@@vtable} commands are the same as the
|
|
@code{@@table} command except that @code{@@ftable} automatically enters
|
|
each of the items in the first column of the table into the index of
|
|
functions and @code{@@vtable} automatically enters each of the items in
|
|
the first column of the table into the index of variables. This
|
|
simplifies the task of creating indices. Only the items on the same
|
|
line as the @code{@@item} commands are indexed, and they are indexed in
|
|
exactly the form that they appear on that line. @xref{Indices, ,
|
|
Creating Indices}, for more information about indices.@refill
|
|
|
|
Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
|
|
writing the @@-command at the beginning of a line, followed on the same
|
|
line by an argument that is a Texinfo command such as @code{@@code},
|
|
exactly as you would for an @code{@@table} command; and end the table
|
|
with an @code{@@end ftable} or @code{@@end vtable} command on a line by
|
|
itself.
|
|
|
|
@node itemx, , ftable vtable, Two-column Tables
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@itemx}
|
|
@cindex Two named items for @code{@@table}
|
|
@findex itemx
|
|
|
|
Use the @code{@@itemx} command inside a table when you have two or
|
|
more first column entries for the same item, each of which should
|
|
appear on a line of its own. Use @code{@@itemx} for all but the first
|
|
entry. The @code{@@itemx} command works exactly like @code{@@item}
|
|
except that it does not generate extra vertical space above the first
|
|
column text.@refill
|
|
|
|
@need 1000
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@table @@code
|
|
@@item upcase
|
|
@@itemx downcase
|
|
These two functions accept a character or a string as
|
|
argument, and return the corresponding upper case (lower
|
|
case) character or string.
|
|
@@end table
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This produces:
|
|
|
|
@table @code
|
|
@item upcase
|
|
@itemx downcase
|
|
These two functions accept a character or a string as
|
|
argument, and return the corresponding upper case (lower
|
|
case) character or string.@refill
|
|
@end table
|
|
|
|
@noindent
|
|
(Note also that this example illustrates multi-line supporting text in
|
|
a two-column table.)@refill
|
|
|
|
@node Indices, Insertions, Lists and Tables, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating Indices
|
|
@cindex Indices
|
|
@cindex Creating indices
|
|
|
|
Using Texinfo, you can generate indices without having to sort and
|
|
collate entries manually. In an index, the entries are listed in
|
|
alphabetical order, together with information on how to find the
|
|
discussion of each entry. In a printed manual, this information
|
|
consists of page numbers. In an Info file, this information is a menu
|
|
entry leading to the first node referenced.@refill
|
|
|
|
Texinfo provides several predefined kinds of index: an index
|
|
for functions, an index for variables, an index for concepts, and so
|
|
on. You can combine indices or use them for other than their
|
|
canonical purpose. If you wish, you can define your own indices.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Index Entries, Predefined Indices, , Indices
|
|
@comment node-name, next, previous, up
|
|
@section Making Index Entries
|
|
@cindex Index entries, making
|
|
@cindex Entries, making index
|
|
|
|
When you are making index entries, it is good practice to think of the
|
|
different ways people may look for something. Different people
|
|
@emph{do not} think of the same words when they look something up. A
|
|
helpful index will have items indexed under all the different words
|
|
that people may use. For example, one reader may think it obvious that
|
|
the two-letter names for indices should be listed under ``Indices,
|
|
two-letter names'', since the word ``Index'' is the general concept.
|
|
But another reader may remember the specific concept of two-letter
|
|
names and search for the entry listed as ``Two letter names for
|
|
indices''. A good index will have both entries and will help both
|
|
readers.@refill
|
|
|
|
Like typesetting, the construction of an index is a highly skilled,
|
|
professional art, the subtleties of which are not appreciated until you
|
|
need to do it yourself.@refill
|
|
|
|
@xref{Printing Indices & Menus}, for information about printing an index
|
|
at the end of a book or creating an index menu in an Info file.@refill
|
|
|
|
@node Predefined Indices, Indexing Commands, Index Entries, Indices
|
|
@comment node-name, next, previous, up
|
|
@section Predefined Indices
|
|
|
|
Texinfo provides six predefined indices:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A @dfn{concept index} listing concepts that are discussed.@refill
|
|
|
|
@item
|
|
A @dfn{function index} listing functions (such as entry points of
|
|
libraries).@refill
|
|
|
|
@item
|
|
A @dfn{variables index} listing variables (such as global variables
|
|
of libraries).@refill
|
|
|
|
@item
|
|
A @dfn{keystroke index} listing keyboard commands.@refill
|
|
|
|
@item
|
|
A @dfn{program index} listing names of programs.@refill
|
|
|
|
@item
|
|
A @dfn{data type index} listing data types (such as structures defined in
|
|
header files).@refill
|
|
@end itemize
|
|
|
|
@noindent
|
|
Not every manual needs all of these, and most manuals use two or three
|
|
of them. This manual has two indices: a
|
|
concept index and an @@-command index (that is actually the function
|
|
index but is called a command index in the chapter heading). Two or
|
|
more indices can be combined into one using the @code{@@synindex} or
|
|
@code{@@syncodeindex} commands. @xref{Combining Indices}.@refill
|
|
|
|
@node Indexing Commands, Combining Indices, Predefined Indices, Indices
|
|
@comment node-name, next, previous, up
|
|
@section Defining the Entries of an Index
|
|
@cindex Defining indexing entries
|
|
@cindex Index entries
|
|
@cindex Entries for an index
|
|
@cindex Specifying index entries
|
|
@cindex Creating index entries
|
|
|
|
The data to make an index come from many individual indexing commands
|
|
scattered throughout the Texinfo source file. Each command says to add
|
|
one entry to a particular index; after formatting, the index will give
|
|
the current page number or node name as the reference.@refill
|
|
|
|
An index entry consists of an indexing command at the beginning of a
|
|
line followed, on the rest of the line, by the entry.@refill
|
|
|
|
For example, this section begins with the following five entries for
|
|
the concept index:@refill
|
|
|
|
@example
|
|
@@cindex Defining indexing entries
|
|
@@cindex Index entries
|
|
@@cindex Entries for an index
|
|
@@cindex Specifying index entries
|
|
@@cindex Creating index entries
|
|
@end example
|
|
|
|
Each predefined index has its own indexing command---@code{@@cindex}
|
|
for the concept index, @code{@@findex} for the function index, and so
|
|
on.@refill
|
|
|
|
@cindex Capitalizing index entries
|
|
@cindex Index entry capitalization
|
|
The usual convention is to capitalize the first word of each index
|
|
entry, unless that word is the name of a function, variable, or other
|
|
such entity that should not be capitalized. Thus, if you are
|
|
documenting Emacs Lisp, you should usually capitalize entries in
|
|
the concept index, but not those in the function index.
|
|
However, if your
|
|
concept index entries are consistently short (one or two words each)
|
|
it may look better for each regular entry to start with a lower case
|
|
letter. Whichever convention you adapt, please be consistent!
|
|
|
|
By default, entries for a concept index are printed in a small roman
|
|
font and entries for the other indices are printed in a small
|
|
@code{@@code} font. You may change the way part of an entry is
|
|
printed with the usual Texinfo commands, such as @code{@@file} for
|
|
file names and @code{@@emph} for emphasis (@pxref{Marking
|
|
Text}).@refill
|
|
@cindex Index font types
|
|
|
|
@cindex Predefined indexing commands
|
|
@cindex Indexing commands, predefined
|
|
The six indexing commands for predefined indices are:
|
|
|
|
@table @code
|
|
@item @@cindex @var{concept}
|
|
@findex cindex
|
|
Make an entry in the concept index for @var{concept}.@refill
|
|
|
|
@item @@findex @var{function}
|
|
@findex findex
|
|
Make an entry in the function index for @var{function}.@refill
|
|
|
|
@item @@vindex @var{variable}
|
|
@findex vindex
|
|
Make an entry in the variable index for @var{variable}.@refill
|
|
|
|
@item @@kindex @var{keystroke}
|
|
@findex kindex
|
|
Make an entry in the key index for @var{keystroke}.@refill
|
|
|
|
@item @@pindex @var{program}
|
|
@findex pindex
|
|
Make an entry in the program index for @var{program}.@refill
|
|
|
|
@item @@tindex @var{data type}
|
|
@findex tindex
|
|
Make an entry in the data type index for @var{data type}.@refill
|
|
@end table
|
|
|
|
@quotation
|
|
@strong{Caution:} Do not use a colon in an index entry. In Info, a
|
|
colon separates the menu entry name from the node name. An extra
|
|
colon confuses Info.
|
|
@xref{Menu Parts, , The Parts of a Menu},
|
|
for more information about the structure of a menu entry.@refill
|
|
@end quotation
|
|
|
|
If you write several identical index entries in different places in a
|
|
Texinfo file, the index in the printed manual will list all the pages to
|
|
which those entries refer. However, the index in the Info file will
|
|
list @strong{only} the node that references the @strong{first} of those
|
|
index entries. Therefore, it is best to write indices in which each
|
|
entry refers to only one place in the Texinfo file. Fortunately, this
|
|
constraint is a feature rather than a loss since it means that the index
|
|
will be easy to use. Otherwise, you could create an index that lists
|
|
several pages for one entry and your reader would not know to which page
|
|
to turn. If you have two identical entries for one topic, change the
|
|
topics slightly, or qualify them to indicate the difference.@refill
|
|
|
|
You are not actually required to use the predefined indices for their
|
|
canonical purposes. For example, suppose you wish to index some C
|
|
preprocessor macros. You could put them in the function index along
|
|
with actual functions, just by writing @code{@@findex} commands for
|
|
them; then, when you print the ``Function Index'' as an unnumbered
|
|
chapter, you could give it the title `Function and Macro Index' and
|
|
all will be consistent for the reader. Or you could put the macros in
|
|
with the data types by writing @code{@@tindex} commands for them, and
|
|
give that index a suitable title so the reader will understand.
|
|
(@xref{Printing Indices & Menus}.)@refill
|
|
|
|
@node Combining Indices, New Indices, Indexing Commands, Indices
|
|
@comment node-name, next, previous, up
|
|
@section Combining Indices
|
|
@cindex Combining indices
|
|
@cindex Indices, combining them
|
|
|
|
Sometimes you will want to combine two disparate indices such as functions
|
|
and concepts, perhaps because you have few enough of one of them that
|
|
a separate index for them would look silly.@refill
|
|
|
|
You could put functions into the concept index by writing
|
|
@code{@@cindex} commands for them instead of @code{@@findex} commands,
|
|
and produce a consistent manual by printing the concept index with the
|
|
title `Function and Concept Index' and not printing the `Function
|
|
Index' at all; but this is not a robust procedure. It works only if
|
|
your document is never included as part of another
|
|
document that is designed to have a separate function index; if your
|
|
document were to be included with such a document, the functions from
|
|
your document and those from the other would not end up together.
|
|
Also, to make your function names appear in the right font in the
|
|
concept index, you would need to enclose every one of them between
|
|
the braces of @code{@@code}.@refill
|
|
|
|
@menu
|
|
* syncodeindex:: How to merge two indices, using @code{@@code}
|
|
font for the merged-from index.
|
|
* synindex:: How to merge two indices, using the
|
|
default font of the merged-to index.
|
|
@end menu
|
|
|
|
@node syncodeindex, synindex, , Combining Indices
|
|
@subsubsection @code{@@syncodeindex}
|
|
@findex syncodeindex
|
|
|
|
When you want to combine functions and concepts into one index, you
|
|
should index the functions with @code{@@findex} and index the concepts
|
|
with @code{@@cindex}, and use the @code{@@syncodeindex} command to
|
|
redirect the function index entries into the concept index.@refill
|
|
@findex syncodeindex
|
|
|
|
The @code{@@syncodeindex} command takes two arguments; they are the name
|
|
of the index to redirect, and the name of the index to redirect it to.
|
|
The template looks like this:@refill
|
|
|
|
@example
|
|
@@syncodeindex @var{from} @var{to}
|
|
@end example
|
|
|
|
@cindex Predefined names for indices
|
|
@cindex Two letter names for indices
|
|
@cindex Indices, two letter names
|
|
@cindex Names for indices
|
|
For this purpose, the indices are given two-letter names:@refill
|
|
|
|
@table @samp
|
|
@item cp
|
|
concept index
|
|
@item fn
|
|
function index
|
|
@item vr
|
|
variable index
|
|
@item ky
|
|
key index
|
|
@item pg
|
|
program index
|
|
@item tp
|
|
data type index
|
|
@end table
|
|
|
|
Write an @code{@@syncodeindex} command before or shortly after the
|
|
end-of-header line at the beginning of a Texinfo file. For example,
|
|
to merge a function index with a concept index, write the
|
|
following:@refill
|
|
|
|
@example
|
|
@@syncodeindex fn cp
|
|
@end example
|
|
|
|
@noindent
|
|
This will cause all entries designated for the function index to merge
|
|
in with the concept index instead.@refill
|
|
|
|
To merge both a variables index and a function index into a concept
|
|
index, write the following:@refill
|
|
|
|
@example
|
|
@group
|
|
@@syncodeindex vr cp
|
|
@@syncodeindex fn cp
|
|
@end group
|
|
@end example
|
|
|
|
@cindex Fonts for indices
|
|
The @code{@@syncodeindex} command puts all the entries from the `from'
|
|
index (the redirected index) into the @code{@@code} font, overriding
|
|
whatever default font is used by the index to which the entries are
|
|
now directed. This way, if you direct function names from a function
|
|
index into a concept index, all the function names are printed in the
|
|
@code{@@code} font as you would expect.@refill
|
|
|
|
@node synindex, , syncodeindex, Combining Indices
|
|
@subsubsection @code{@@synindex}
|
|
@findex synindex
|
|
|
|
The @code{@@synindex} command is nearly the same as the
|
|
@code{@@syncodeindex} command, except that it does not put the
|
|
`from' index entries into the @code{@@code} font; rather it puts
|
|
them in the roman font. Thus, you use @code{@@synindex} when you
|
|
merge a concept index into a function index.@refill
|
|
|
|
@xref{Printing Indices & Menus}, for information about printing an index
|
|
at the end of a book or creating an index menu in an Info file.@refill
|
|
|
|
@node New Indices, , Combining Indices, Indices
|
|
@section Defining New Indices
|
|
@cindex Defining new indices
|
|
@cindex Indices, defining new
|
|
@cindex New index defining
|
|
@findex defindex
|
|
@findex defcodeindex
|
|
|
|
In addition to the predefined indices, you may use the
|
|
@code{@@defindex} and @code{@@defcodeindex} commands to define new
|
|
indices. These commands create new indexing @@-commands with which
|
|
you mark index entries. The @code{@@defindex }command is used like
|
|
this:@refill
|
|
|
|
@example
|
|
@@defindex @var{name}
|
|
@end example
|
|
|
|
The name of an index should be a two letter word, such as @samp{au}.
|
|
For example:@refill
|
|
|
|
@example
|
|
@@defindex au
|
|
@end example
|
|
|
|
This defines a new index, called the @samp{au} index. At the same
|
|
time, it creates a new indexing command, @code{@@auindex}, that you
|
|
can use to make index entries. Use the new indexing command just as
|
|
you would use a predefined indexing command.@refill
|
|
|
|
For example, here is a section heading followed by a concept index
|
|
entry and two @samp{au} index entries.@refill
|
|
|
|
@example
|
|
@@section Cognitive Semantics
|
|
@@cindex kinesthetic image schemas
|
|
@@auindex Johnson, Mark
|
|
@@auindex Lakoff, George
|
|
@end example
|
|
|
|
@noindent
|
|
(Evidently, @samp{au} serves here as an abbreviation for ``author''.)
|
|
Texinfo constructs the new indexing command by concatenating the name
|
|
of the index with @samp{index}; thus, defining an @samp{au} index
|
|
leads to the automatic creation of an @code{@@auindex} command.@refill
|
|
|
|
Use the @code{@@printindex} command to print the index, as you do with
|
|
the predefined indices. For example:@refill
|
|
|
|
@example
|
|
@group
|
|
@@node Author Index, Subject Index, , Top
|
|
@@unnumbered Author Index
|
|
|
|
@@printindex au
|
|
@end group
|
|
@end example
|
|
|
|
The @code{@@defcodeindex} is like the @code{@@defindex} command, except
|
|
that, in the printed output, it prints entries in an @code{@@code} font
|
|
instead of a roman font. Thus, it parallels the @code{@@findex} command
|
|
rather than the @code{@@cindex} command.@refill
|
|
|
|
You should define new indices within or right after the end-of-header
|
|
line of a Texinfo file, before any @code{@@synindex} or
|
|
@code{@@syncodeindex} commands (@pxref{Header}).@refill
|
|
|
|
@node Insertions, Glyphs, Indices, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Special Insertions
|
|
@cindex Inserting special characters and symbols
|
|
@cindex Special insertions
|
|
|
|
Texinfo provides several commands for formatting dimensions, for
|
|
inserting single characters that have special meaning in Texinfo, such
|
|
as braces, and for inserting special graphic symbols that do not
|
|
correspond to characters, such as dots and bullets.@refill
|
|
|
|
@iftex
|
|
These are:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Braces, @samp{@@} and periods.
|
|
|
|
@item
|
|
Format a dimension, such as @samp{12@dmn{pt}}.
|
|
|
|
@item
|
|
Dots and bullets.
|
|
|
|
@item
|
|
The @TeX{} logo and the copyright symbol.
|
|
|
|
@item
|
|
A minus sign.
|
|
@end itemize
|
|
@end iftex
|
|
|
|
@menu
|
|
* Braces Atsigns Periods:: How to insert braces, @samp{@@} 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.
|
|
@end menu
|
|
|
|
@node Braces Atsigns Periods, dmn, , Insertions
|
|
@comment node-name, next, previous, up
|
|
@section Inserting @samp{@@}, Braces, and Periods
|
|
@cindex Inserting @@, braces, and periods
|
|
@cindex Braces, inserting
|
|
@cindex Periods, inserting
|
|
@cindex Single characters, commands to insert
|
|
@cindex Commands to insert single characters
|
|
|
|
@samp{@@} and curly braces are special characters in Texinfo. To
|
|
insert these characters so they appear in text, you must put an @samp{@@} in front
|
|
of these characters to prevent Texinfo from misinterpreting them.@refill
|
|
|
|
Periods are also special. Depending on whether the period is inside
|
|
or at the end of a sentence, less or more space is inserted after a
|
|
period in a typeset manual. Since it is not always possible for
|
|
Texinfo to determine when a period ends a sentence and when it is used
|
|
in an abbreviation, special commands are needed in some circumstances.
|
|
(Usually, Texinfo can guess how to handle periods, so you do not need
|
|
to use the special commands; you just enter a period as you would if
|
|
you were using a typewriter, which means you put two spaces after the
|
|
period, question mark, or exclamation mark that ends a
|
|
sentence.)@refill
|
|
|
|
Do not put braces after any of these commands; they are not
|
|
necessary.@refill
|
|
|
|
@menu
|
|
* Inserting An Atsign::
|
|
* Inserting Braces:: How to insert @samp{@{} and @samp{@}}
|
|
* Controlling Spacing:: How to insert the right amount of space
|
|
after punctuation within a sentence.
|
|
@end menu
|
|
|
|
@node Inserting An Atsign, Inserting Braces, , Braces Atsigns Periods
|
|
@comment node-name, next, previous, up
|
|
@subsection Inserting @samp{@@} with @@@@
|
|
@findex @@ @r{(single @samp{@@})}
|
|
|
|
@code{@@@@} stands for a single @samp{@@} in either printed or Info
|
|
output.@refill
|
|
|
|
Do not put braces after an @code{@@@@} command.@refill
|
|
|
|
@node Inserting Braces, Controlling Spacing, Inserting An Atsign, Braces Atsigns Periods
|
|
@comment node-name, next, previous, up
|
|
@subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
|
|
@findex @{ @r{(single @samp{@{})}
|
|
@findex @} @r{(single @samp{@}})}
|
|
|
|
@code{@@@{} stands for a single @samp{@{} in either printed or Info
|
|
output.@refill
|
|
|
|
@code{@@@}} stands for a single @samp{@}} in either printed or Info
|
|
output.@refill
|
|
|
|
Do not put braces after either an @code{@@@{} or an @code{@@@}}
|
|
command.@refill
|
|
|
|
@node Controlling Spacing, , Inserting Braces, Braces Atsigns Periods
|
|
@comment node-name, next, previous, up
|
|
@subsection Spacing After Colons and Periods
|
|
@findex : @r{(suppress widening)}
|
|
|
|
Use the @code{@@:}@: command after a period, question mark,
|
|
exclamation mark, or colon that should not be followed by extra space.
|
|
For example, use @code{@@:}@: after periods that end abbreviations
|
|
which are not at the ends of sentences. @code{@@:}@: has no effect on
|
|
the Info file output.@refill
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
The s.o.p.@@: has three parts @dots{}
|
|
The s.o.p. has three parts @dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
@ifinfo
|
|
produces
|
|
@end ifinfo
|
|
@iftex
|
|
produces the following. If you look carefully at this printed output,
|
|
you will see a little more whitespace after @samp{s.o.p.} in the second
|
|
line.@refill
|
|
@end iftex
|
|
|
|
@quotation
|
|
The s.o.p.@: has three parts @dots{}@*
|
|
The s.o.p. has three parts @dots{}
|
|
@end quotation
|
|
|
|
@noindent
|
|
@kbd{@@:} has no effect on the Info output. (@samp{s.o.p} is an acronym
|
|
for ``Standard Operating Procedure''.)
|
|
|
|
@findex . @r{(true end of sentence)}
|
|
Use @code{@@.}@: instead of a period at the end of a sentence that
|
|
ends with a single capital letter. Otherwise, @TeX{} will think the
|
|
letter is an abbreviation and will not insert the correct
|
|
end-of-sentence spacing. Here is an example:@refill
|
|
|
|
@example
|
|
Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
|
|
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
|
|
@end example
|
|
|
|
@noindent
|
|
@ifinfo
|
|
produces
|
|
@end ifinfo
|
|
@iftex
|
|
produces the following. If you look carefully at this printed output,
|
|
you will see a little more whitespace after the @samp{W} in the first
|
|
line.@refill
|
|
@end iftex
|
|
|
|
@quotation
|
|
Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
|
|
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
|
|
@end quotation
|
|
|
|
In the Info file output, @code{@@.}@: is equivalent to a simple
|
|
@samp{.}.@refill
|
|
|
|
The meanings of @code{@@:}@: and @code{@@.}@: in Texinfo are designed
|
|
to work well with the Emacs sentence motion commands. This made it
|
|
necessary for them to be incompatible with some other formatting
|
|
systems that use @@-commands.@refill
|
|
|
|
Do not put braces after either an @code{@@:} or an @code{@@.} command.@refill
|
|
|
|
@node dmn, Dots Bullets, Braces Atsigns Periods, Insertions
|
|
@section @code{@@dmn}@{@var{dimension}@}: Format a Dimension
|
|
@cindex Thin space between number, dimension
|
|
@cindex Dimension formatting
|
|
@cindex Format a dimension
|
|
@findex dmn
|
|
|
|
At times, you may want to write @samp{12@dmn{pt}} or
|
|
@samp{8.5@dmn{in}} with little or no space between the number and the
|
|
abbreviation for the dimension. You can use the @code{@@dmn} command
|
|
to do this. On seeing the command, @TeX{} inserts just enough space
|
|
for proper typesetting; the Info formatting commands insert no space
|
|
at all, since the Info file does not require it.@refill
|
|
|
|
To use the @code{@@dmn} command, write the number and then follow it
|
|
immediately, with no intervening space, by @code{@@dmn}, and then by
|
|
the dimension within braces.@refill
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
A4 paper is 8.27@@dmn@{in@} wide.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
A4 paper is 8.27@dmn{in} wide.
|
|
@end quotation
|
|
|
|
Not everyone uses this style. Instead of writing
|
|
@w{@samp{8.27@@dmn@{in@}}} in the Texinfo file, you may write
|
|
@w{@samp{8.27 in.}} or @w{@samp{8.27 inches}}. (In these cases, the
|
|
formatters may insert a line break between the number and the
|
|
dimension. Also, if you write a period after an abbreviation within a
|
|
sentence, you should write @samp{@@:} after the period to prevent
|
|
@TeX{} from inserting extra whitespace. @xref{Controlling Spacing, ,
|
|
Spacing After Colons and Periods}.)@refill
|
|
|
|
@node Dots Bullets, TeX and copyright, dmn, Insertions
|
|
@comment node-name, next, previous, up
|
|
@section Inserting Ellipsis, Dots, and Bullets
|
|
@cindex Dots, inserting
|
|
@cindex Bullets, inserting
|
|
@cindex Ellipsis, inserting
|
|
@cindex Inserting ellipsis
|
|
@cindex Inserting dots
|
|
@cindex Special typesetting commands
|
|
@cindex Typesetting commands for dots, etc.
|
|
|
|
An @dfn{ellipsis} (a line of dots) is not typeset as a string of
|
|
periods, so a special command is used for ellipsis in Texinfo. The
|
|
@code{@@bullet} command is special, too. Each of these commands is
|
|
followed by a pair of braces, @samp{@{@}}, without any whitespace
|
|
between the name of the command and the braces. (You need to use braces
|
|
with these commands because you can use them next to other text; without
|
|
the braces, the formatters would be confused. @xref{Command Syntax, ,
|
|
@@-Command Syntax}, for further information.)@refill
|
|
|
|
@menu
|
|
* dots:: How to insert dots @dots{}
|
|
* bullet:: How to insert a bullet.
|
|
@end menu
|
|
|
|
@node dots, bullet, , Dots Bullets
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@dots}@{@}
|
|
@findex dots
|
|
@cindex Inserting dots
|
|
@cindex Dots, inserting
|
|
|
|
Use the @code{@@dots@{@}} command to generate an ellipsis, which is
|
|
three dots in a row, appropriately spaced, like this: `@dots{}'. Do
|
|
not simply write three periods in the input file; that would work for
|
|
the Info file output, but would produce the wrong amount of space
|
|
between the periods in the printed manual.@refill
|
|
|
|
@iftex
|
|
Here is an ellipsis: @dots{}
|
|
|
|
Here are three periods in a row: ...
|
|
|
|
In printed output, the three periods in a row are closer together than
|
|
the dots in the ellipsis.
|
|
@end iftex
|
|
|
|
@node bullet, , dots, Dots Bullets
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@bullet}@{@}
|
|
@findex bullet
|
|
|
|
Use the @code{@@bullet@{@}} command to generate a large round dot, or
|
|
the closest possible thing to one. In Info, an asterisk is used.@refill
|
|
|
|
Here is a bullet: @bullet{}
|
|
|
|
When you use @code{@@bullet} in @code{@@itemize}, you do not need to
|
|
type the braces, because @code{@@itemize} supplies them. @xref{itemize}.@refill
|
|
|
|
@node TeX and copyright, minus, Dots Bullets, Insertions
|
|
@comment node-name, next, previous, up
|
|
@section Inserting @TeX{} and the Copyright Symbol
|
|
|
|
The logo `@TeX{}' is typeset in a special fashion and it needs an
|
|
@@-command. The copyright symbol, `@copyright{}', is also special.
|
|
Each of these commands is followed by a pair of braces, @samp{@{@}},
|
|
without any whitespace between the name of the command and the
|
|
braces.@refill
|
|
|
|
@menu
|
|
* tex:: How to insert the @TeX{} logo.
|
|
* copyright symbol:: How to use @code{@@copyright}@{@}.
|
|
@end menu
|
|
|
|
@node tex, copyright symbol, , TeX and copyright
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@TeX}@{@}
|
|
@findex tex (command)
|
|
|
|
Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
|
|
manual, this is a special logo that is different from three ordinary
|
|
letters. In Info, it just looks like @samp{TeX}. The
|
|
@code{@@TeX@{@}} command is unique among Texinfo commands in that the
|
|
@key{T} and the @key{X} are in upper case.@refill
|
|
|
|
@node copyright symbol, , tex, TeX and copyright
|
|
@comment node-name, next, previous, up
|
|
@subsection @code{@@copyright}@{@}
|
|
@findex copyright
|
|
|
|
Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
|
|
a printed manual, this is a @samp{c} inside a circle, and in Info,
|
|
this is @samp{(C)}.@refill
|
|
|
|
@node minus, , TeX and copyright, Insertions
|
|
@section @code{@@minus}@{@}: Inserting a Minus Sign
|
|
@findex minus
|
|
|
|
Use the @code{@@minus@{@}} command to generate a minus sign. In a
|
|
fixed-width font, this is a single hyphen, but in a proportional font,
|
|
the symbol is the customary length for a minus sign---a little longer
|
|
than a hyphen.@refill
|
|
|
|
You can compare the two forms:
|
|
|
|
@display
|
|
@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
|
|
|
|
`-' is a hyphen generated with the character @samp{-}.
|
|
@end display
|
|
|
|
@noindent
|
|
In the fixed-width font used by Info, @code{@@minus@{@}} is the same
|
|
as a hyphen.@refill
|
|
|
|
You should not use @code{@@minus@{@}} inside @code{@@code} or
|
|
@code{@@example} because the width distinction is not made in the
|
|
fixed-width font they use.@refill
|
|
|
|
When you use @code{@@minus} to specify the mark beginning each entry in
|
|
an itemized list, you do not need to type the braces
|
|
(@pxref{itemize}).@refill
|
|
|
|
@node Glyphs, Breaks, Insertions, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Glyphs for Examples
|
|
@cindex Glyphs
|
|
|
|
In Texinfo, code is often illustrated in examples that are delimited
|
|
by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
|
|
@code{@@end lisp}. In such examples, you can indicate the results of
|
|
evaluation or an expansion using @samp{@result{}} or
|
|
@samp{@expansion{}}. Likewise, there are commands to insert glyphs
|
|
to indicate
|
|
printed output, error messages, equivalence of expressions, and the
|
|
location of point.@refill
|
|
|
|
The glyph-insertion commands do not need to be used within an example, but
|
|
most often they are. Every glyph-insertion command is followed by a pair of
|
|
left- and right-hand braces.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Glyphs Summary, result, , Glyphs
|
|
@ifinfo
|
|
@heading Glyphs Summary
|
|
|
|
Here are the different glyph commands:@refill
|
|
@end ifinfo
|
|
|
|
@table @asis
|
|
@item @result{}
|
|
@code{@@result@{@}} points to the result of an expression.@refill
|
|
|
|
@item @expansion{}
|
|
@code{@@expansion@{@}} shows the results of a macro expansion.@refill
|
|
|
|
@item @print{}
|
|
@code{@@print@{@}} indicates printed output.@refill
|
|
|
|
@item @error{}
|
|
@code{@@error@{@}} indicates that the following text is an error
|
|
message.@refill
|
|
|
|
@item @equiv{}
|
|
@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
|
|
|
|
@item @point{}
|
|
@code{@@point@{@}} shows the location of point.@refill
|
|
@end table
|
|
|
|
@node result, expansion, Glyphs Summary, Glyphs
|
|
@section @result{}: Indicating Evaluation
|
|
@cindex Result of an expression
|
|
@cindex Indicating evaluation
|
|
@cindex Evaluation glyph
|
|
@cindex Value of an expression, indicating
|
|
|
|
Use the @code{@@result@{@}} command to indicate the result of
|
|
evaluating an expression.@refill
|
|
|
|
@iftex
|
|
The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
|
|
as @samp{@result{}} in the printed output.
|
|
@end iftex
|
|
@ifinfo
|
|
The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
|
|
and as a double stemmed arrow in the printed output.@refill
|
|
@end ifinfo
|
|
|
|
Thus, the following,
|
|
|
|
@lisp
|
|
(cdr '(1 2 3))
|
|
@result{} (2 3)
|
|
@end lisp
|
|
|
|
@noindent
|
|
may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
|
|
|
|
@node expansion, Print Glyph, result, Glyphs
|
|
@section @expansion{}: Indicating an Expansion
|
|
@cindex Expansion, indicating it
|
|
|
|
When an expression is a macro call, it expands into a new expression.
|
|
You can indicate the result of the expansion with the
|
|
@code{@@expansion@{@}} command.@refill
|
|
|
|
@iftex
|
|
The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
|
|
as @samp{@expansion{}} in the printed output.
|
|
@end iftex
|
|
@ifinfo
|
|
The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
|
|
in Info and as a long arrow with a flat base in the printed output.@refill
|
|
@end ifinfo
|
|
|
|
@need 700
|
|
For example, the following
|
|
|
|
@example
|
|
@group
|
|
@@lisp
|
|
(third '(a b c))
|
|
@@expansion@{@} (car (cdr (cdr '(a b c))))
|
|
@@result@{@} c
|
|
@@end lisp
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@lisp
|
|
@group
|
|
(third '(a b c))
|
|
@expansion{} (car (cdr (cdr '(a b c))))
|
|
@result{} c
|
|
@end group
|
|
@end lisp
|
|
|
|
@noindent
|
|
which may be read as:
|
|
|
|
@quotation
|
|
@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
|
|
the result of evaluating the expression is @code{c}.
|
|
@end quotation
|
|
|
|
@noindent
|
|
Often, as in this case, an example looks better if the
|
|
@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
|
|
five spaces.@refill
|
|
|
|
@node Print Glyph, Error Glyph, expansion, Glyphs
|
|
@section @print{}: Indicating Printed Output
|
|
@cindex Printed output, indicating it
|
|
|
|
Sometimes an expression will print output during its execution. You
|
|
can indicate the printed output with the @code{@@print@{@}} command.@refill
|
|
|
|
@iftex
|
|
The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
|
|
as @samp{@print{}} in the printed output.
|
|
@end iftex
|
|
@ifinfo
|
|
The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
|
|
and similarly, as a horizontal dash butting against a vertical bar, in
|
|
the printed output.@refill
|
|
@end ifinfo
|
|
|
|
In the following example, the printed text is indicated with
|
|
@samp{@print{}}, and the value of the expression follows on the
|
|
last line.@refill
|
|
|
|
@lisp
|
|
@group
|
|
(progn (print 'foo) (print 'bar))
|
|
@print{} foo
|
|
@print{} bar
|
|
@result{} bar
|
|
@end group
|
|
@end lisp
|
|
|
|
@noindent
|
|
In a Texinfo source file, this example is written as follows:
|
|
|
|
@lisp
|
|
@group
|
|
@@lisp
|
|
(progn (print 'foo) (print 'bar))
|
|
@@print@{@} foo
|
|
@@print@{@} bar
|
|
@@result@{@} bar
|
|
@@end lisp
|
|
@end group
|
|
@end lisp
|
|
|
|
@node Error Glyph, Equivalence, Print Glyph, Glyphs
|
|
@section @error{}: Indicating an Error Message
|
|
@cindex Error message, indicating it
|
|
|
|
A piece of code may cause an error when you evaluate it. You can
|
|
designate the error message with the @code{@@error@{@}} command.@refill
|
|
|
|
@iftex
|
|
The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
|
|
and as @samp{@error{}} in the printed output.
|
|
@end iftex
|
|
@ifinfo
|
|
The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
|
|
and as the word `error' in a box in the printed output.@refill
|
|
@end ifinfo
|
|
|
|
@need 700
|
|
Thus,
|
|
|
|
@example
|
|
@@lisp
|
|
(+ 23 'x)
|
|
@@error@{@} Wrong type argument: integer-or-marker-p, x
|
|
@@end lisp
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@lisp
|
|
(+ 23 'x)
|
|
@error{} Wrong type argument: integer-or-marker-p, x
|
|
@end lisp
|
|
|
|
@noindent
|
|
This indicates that the following error message is printed
|
|
when you evaluate the expression:
|
|
|
|
@lisp
|
|
Wrong type argument: integer-or-marker-p, x
|
|
@end lisp
|
|
|
|
Note that @samp{@error{}} itself is not part of the error
|
|
message.
|
|
|
|
@node Equivalence, Point Glyph, Error Glyph, Glyphs
|
|
@section @equiv{}: Indicating Equivalence
|
|
@cindex Equivalence, indicating it
|
|
|
|
Sometimes two expressions produce identical results. You can indicate the
|
|
exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
|
|
|
|
@iftex
|
|
The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
|
|
as @samp{@equiv{}} in the printed output.
|
|
@end iftex
|
|
@ifinfo
|
|
The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
|
|
and as a three parallel horizontal lines in the printed output.@refill
|
|
@end ifinfo
|
|
|
|
Thus,
|
|
|
|
@example
|
|
@@lisp
|
|
(make-sparse-keymap) @@equiv@{@} (list 'keymap)
|
|
@@end lisp
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@lisp
|
|
(make-sparse-keymap) @equiv{} (list 'keymap)
|
|
@end lisp
|
|
|
|
@noindent
|
|
This indicates that evaluating @code{(make-sparse-keymap)} produces
|
|
identical results to evaluating @code{(list 'keymap)}.
|
|
|
|
@c Cannot write point command here because it causes trouble with TOC.
|
|
@node Point Glyph, , Equivalence, Glyphs
|
|
@section Indicating Point in a Buffer
|
|
@cindex Point, indicating it in a buffer
|
|
|
|
Sometimes you need to show an example of text in an Emacs buffer. In
|
|
such examples, the convention is to include the entire contents of the
|
|
buffer in question between two lines of dashes containing the buffer
|
|
name.@refill
|
|
|
|
You can use the @samp{@@point@{@}} command to show the location of point
|
|
in the text in the buffer. (The symbol for point, of course, is not
|
|
part of the text in the buffer; it indicates the place @emph{between}
|
|
two characters where point is located.)@refill
|
|
|
|
@iftex
|
|
The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
|
|
as @samp{@point{}} in the printed output.
|
|
@end iftex
|
|
@ifinfo
|
|
The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
|
|
and as a small five pointed star in the printed output.@refill
|
|
@end ifinfo
|
|
|
|
The following example shows the contents of buffer @file{foo} before
|
|
and after evaluating a Lisp command to insert the word @code{changed}.@refill
|
|
|
|
@example
|
|
@group
|
|
---------- Buffer: foo ----------
|
|
This is the @point{}contents of foo.
|
|
---------- Buffer: foo ----------
|
|
|
|
@end group
|
|
@end example
|
|
|
|
@example
|
|
@group
|
|
(insert "changed ")
|
|
@result{} nil
|
|
---------- Buffer: foo ----------
|
|
This is the changed @point{}contents of foo.
|
|
---------- Buffer: foo ----------
|
|
|
|
@end group
|
|
@end example
|
|
|
|
In a Texinfo source file, the example is written like this:@refill
|
|
|
|
@example
|
|
@@example
|
|
---------- Buffer: foo ----------
|
|
This is the @@point@{@}contents of foo.
|
|
---------- Buffer: foo ----------
|
|
|
|
(insert "changed ")
|
|
@@result@{@} nil
|
|
---------- Buffer: foo ----------
|
|
This is the changed @@point@{@}contents of foo.
|
|
---------- Buffer: foo ----------
|
|
@@end example
|
|
@end example
|
|
|
|
@node Breaks, Definition Commands, Glyphs, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Making and Preventing Breaks
|
|
@cindex Making line and page breaks
|
|
@cindex Preventing line and page breaks
|
|
|
|
Usually, a Texinfo file is processed both by @TeX{} and by one of the
|
|
Info formatting commands. Line, paragraph, or page breaks sometimes
|
|
occur in the `wrong' place in one or other form of output. You must
|
|
ensure that text looks right both in the printed manual and in the
|
|
Info file.@refill
|
|
|
|
For example, in a printed manual, page breaks may occur awkwardly in
|
|
the middle of an example; to prevent this, you can hold text together
|
|
using a grouping command that keeps the text from being split across
|
|
two pages. Conversely, you may want to force a page break where none
|
|
would occur normally. Fortunately, problems like these do not often
|
|
arise. When they do, use the break, break prevention, or pagination
|
|
commands.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@ifinfo
|
|
@node Break Commands, Line Breaks, , Breaks
|
|
@heading The Break Commands
|
|
@end ifinfo
|
|
@iftex
|
|
@sp 1
|
|
@end iftex
|
|
|
|
The break commands create line and paragraph breaks:@refill
|
|
|
|
@table @code
|
|
@item @@*
|
|
Force a line break.
|
|
|
|
@item @@sp @var{n}
|
|
Skip @var{n} blank lines.@refill
|
|
@end table
|
|
@iftex
|
|
@sp 1
|
|
@end iftex
|
|
|
|
The line-break-prevention command holds text together all on one
|
|
line:@refill
|
|
|
|
@table @code
|
|
@item @@w@{@var{text}@}
|
|
Prevent @var{text} from being split and hyphenated across two lines.@refill
|
|
@end table
|
|
@iftex
|
|
@sp 1
|
|
@end iftex
|
|
|
|
The pagination commands apply only to printed output, since Info
|
|
files do not have pages.@refill
|
|
|
|
@table @code
|
|
@item @@page
|
|
Start a new page in the printed manual.@refill
|
|
|
|
@item @@group
|
|
Hold text together that must appear on one printed page.@refill
|
|
|
|
@item @@need @var{mils}
|
|
Start a new printed page if not enough space on this one.@refill
|
|
@end table
|
|
|
|
@node Line Breaks, w, Break Commands, Breaks
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@*}: Generate Line Breaks
|
|
@findex * @r{(force line break)}
|
|
@cindex Line breaks
|
|
@cindex Breaks in a line
|
|
|
|
The @code{@@*} command forces a line break in both the printed manual and
|
|
in Info.@refill
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
This line @@* is broken @@*in two places.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
This line
|
|
is broken
|
|
in two places.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(Note that the space after the first @code{@@*} command is faithfully
|
|
carried down to the next line.)@refill
|
|
|
|
@need 800
|
|
The @code{@@*} command is often used in a file's copyright page:@refill
|
|
|
|
@example
|
|
@group
|
|
This is edition 2.0 of the Texinfo documentation,@@*
|
|
and is for @dots{}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
In this case, the @code{@@*} command keeps @TeX{} from stretching the
|
|
line across the whole page in an ugly manner.@refill
|
|
|
|
@quotation
|
|
@strong{Please note:} Do not write braces after an @code{@@*} command;
|
|
they are not needed.@refill
|
|
|
|
Do not write an @code{@@refill} command at the end of a paragraph
|
|
containing an @code{@@*} command; it will cause the paragraph to be
|
|
refilled after the line break occurs, negating the effect of the line
|
|
break.@refill
|
|
@end quotation
|
|
|
|
@node w, sp, Line Breaks, Breaks
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@w}@{@var{text}@}: Prevent Line Breaks
|
|
@findex w @r{(prevent line break)}
|
|
@cindex Line breaks, preventing
|
|
|
|
@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
|
|
within @var{text}.@refill
|
|
|
|
You can use the @code{@@w} command to prevent @TeX{} from automatically
|
|
hyphenating a long name or phrase that accidentally falls near the end
|
|
of a line.@refill
|
|
|
|
@example
|
|
You can copy GNU software from @@w@{@@file@{prep.ai.mit.edu@}@}.
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
You can copy GNU software from @w{@file{prep.ai.mit.edu}}.
|
|
@end quotation
|
|
|
|
In the Texinfo file, you must write the @code{@@w} command and its
|
|
argument (all the affected text) all on one line.@refill
|
|
|
|
@quotation
|
|
@strong{Caution:} Do not write an @code{@@refill} command at the end
|
|
of a paragraph containing an @code{@@w} command; it will cause the
|
|
paragraph to be refilled and may thereby negate the effect of the
|
|
@code{@@w} command.@refill
|
|
@end quotation
|
|
|
|
@node sp, page, w, Breaks
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@sp} @var{n}: Insert Blank Lines
|
|
@findex sp @r{(line spacing)}
|
|
@cindex Spaces (blank lines)
|
|
@cindex Blank lines
|
|
@cindex Line spacing
|
|
|
|
A line beginning with and containing only @code{@@sp @var{n}}
|
|
generates @var{n} blank lines of space in both the printed manual and
|
|
the Info file. @code{@@sp} also forces a paragraph break. For
|
|
example,@refill
|
|
|
|
@example
|
|
@@sp 2
|
|
@end example
|
|
|
|
@noindent
|
|
generates two blank lines.
|
|
|
|
The @code{@@sp} command is most often used in the title page.@refill
|
|
|
|
@ignore
|
|
@c node br, page, sp, Breaks
|
|
@comment node-name, next, previous, up
|
|
@c section @code{@@br}: Generate Paragraph Breaks
|
|
@findex br @r{(paragraph breaks)}
|
|
@cindex Paragraph breaks
|
|
@cindex Breaks in a paragraph
|
|
|
|
The @code{@@br} command forces a paragraph break. It inserts a blank
|
|
line. You can use the command within or at the end of a line. If
|
|
used within a line, the @code{@@br@{@}} command must be followed by
|
|
left and right braces (as shown here) to mark the end of the
|
|
command.@refill
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
This line @@br@{@}contains and is ended by paragraph breaks@@br
|
|
and is followed by another line.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@example
|
|
@group
|
|
This line
|
|
|
|
contains and is ended by paragraph breaks
|
|
|
|
and is followed by another line.
|
|
@end group
|
|
@end example
|
|
|
|
The @code{@@br} command is seldom used.
|
|
@end ignore
|
|
|
|
@node page, group, sp, Breaks
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@page}: Start a New Page
|
|
@cindex Page breaks
|
|
@findex page
|
|
|
|
A line containing only @code{@@page} starts a new page in a printed
|
|
manual. The command has no effect on Info files since they are not
|
|
paginated. An @code{@@page} command is often used in the @code{@@titlepage}
|
|
section of a Texinfo file to start the copyright page.@refill
|
|
|
|
@node group, need, page, Breaks
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@group}: Prevent Page Breaks
|
|
@cindex Group (hold text together vertically)
|
|
@cindex Holding text together vertically
|
|
@cindex Vertically holding text together
|
|
@findex group
|
|
|
|
The @code{@@group} command (on a line by itself) is used inside an
|
|
@code{@@example} or similar construct to begin an unsplittable vertical
|
|
group, which will appear entirely on one page in the printed output.
|
|
The group is terminated by a line containing only @code{@@end group}.
|
|
These two lines produce no output of their own, and in the Info file
|
|
output they have no effect at all.@refill
|
|
|
|
@c Once said that these environments
|
|
@c turn off vertical spacing between ``paragraphs''.
|
|
@c Also, quotation used to work, but doesn't in texinfo-2.72
|
|
Although @code{@@group} would make sense conceptually in a wide
|
|
variety of contexts, its current implementation works reliably only
|
|
within @code{@@example} and variants, and within @code{@@display},
|
|
@code{@@format}, @code{@@flushleft} and @code{@@flushright}.
|
|
@xref{Quotations and Examples}. (What all these commands have in
|
|
common is that each line of input produces a line of output.) In
|
|
other contexts, @code{@@group} can cause anomalous vertical
|
|
spacing.@refill
|
|
|
|
@need 750
|
|
This formatting requirement means that you should write:
|
|
|
|
@example
|
|
@group
|
|
@@example
|
|
@@group
|
|
@dots{}
|
|
@@end group
|
|
@@end example
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
with the @code{@@group} and @code{@@end group} commands inside the
|
|
@code{@@example} and @code{@@end example} commands.
|
|
|
|
The @code{@@group} command is most often used to hold an example
|
|
together on one page. In this Texinfo manual, more than 100 examples
|
|
contain text that is enclosed between @code{@@group} and @code{@@end
|
|
group}.
|
|
|
|
If you forget to end a group, you may get strange and unfathomable
|
|
error messages when you run @TeX{}. This is because @TeX{} keeps
|
|
trying to put the rest of the Texinfo file onto the one page and does
|
|
not start to generate error messages until it has processed
|
|
considerable text. It is a good rule of thumb to look for a missing
|
|
@code{@@end group} if you get incomprehensible error messages in
|
|
@TeX{}.@refill
|
|
|
|
@node need, , group, Breaks
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@need @var{mils}}: Prevent Page Breaks
|
|
@cindex Need space at page bottom
|
|
@findex need
|
|
|
|
A line containing only @code{@@need @var{n}} starts
|
|
a new page in a printed manual if fewer than @var{n} mils (thousandths
|
|
of an inch) remain on the current page. Do not use
|
|
braces around the argument @var{n}. The @code{@@need} command has no
|
|
effect on Info files since they are not paginated.@refill
|
|
|
|
@need 800
|
|
This paragraph is preceded by an @code{@@need} command that tells
|
|
@TeX{} to start a new page if fewer than 800 mils (eight-tenths
|
|
inch) remain on the page. It looks like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@need 800
|
|
This paragraph is preceded by @dots{}
|
|
@end group
|
|
@end example
|
|
|
|
The @code{@@need} command is useful for preventing orphans (single
|
|
lines at the bottoms of printed pages).@refill
|
|
|
|
@node Definition Commands, Footnotes, Breaks, Top
|
|
@chapter Definition Commands
|
|
@cindex Definition commands
|
|
|
|
The @code{@@deffn} command and the other @dfn{definition commands}
|
|
enable you to describe functions, variables, macros, commands, user
|
|
options, special forms and other such artifacts in a uniform
|
|
format.@refill
|
|
|
|
In the Info file, a definition causes the entity
|
|
category---`Function', `Variable', or whatever---to appear at the
|
|
beginning of the first line of the definition, followed by the
|
|
entity's name and arguments. In the printed manual, the command
|
|
causes @TeX{} to print the entity's name and its arguments on the left
|
|
margin and print the category next to the right margin. In both
|
|
output formats, the body of the definition is indented. Also, the
|
|
name of the entity is entered into the appropriate index:
|
|
@code{@@deffn} enters the name into the index of functions,
|
|
@code{@@defvr} enters it into the index of variables, and so
|
|
on.@refill
|
|
|
|
A manual need not and should not contain more than one definition for
|
|
a given name. An appendix containing a summary should use
|
|
@code{@@table} rather than the definition commands.@refill
|
|
|
|
@menu
|
|
* 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::
|
|
@end menu
|
|
|
|
@node Def Cmd Template, Optional Arguments, , Definition Commands
|
|
@section The Template for a Definition
|
|
@cindex Definition template
|
|
@cindex Template for a definition
|
|
|
|
The @code{@@deffn} command is used for definitions of entities that
|
|
resemble functions. To write a definition using the @code{@@deffn}
|
|
command, write the @code{@@deffn} command at the beginning of a line
|
|
and follow it on the same line by the category of the entity, the name
|
|
of the entity itself, and its arguments (if any). Then write the body
|
|
of the definition on succeeding lines. (You may embed examples in the
|
|
body.) Finally, end the definition with an @code{@@end deffn} command
|
|
written on a line of its own. (The other definition commands follow
|
|
the same format.)@refill
|
|
|
|
The template for a definition looks like this:
|
|
|
|
@example
|
|
@group
|
|
@@deffn @var{category} @var{name} @var{arguments}@dots{}
|
|
@var{body-of-definition}
|
|
@@end deffn
|
|
@end group
|
|
@end example
|
|
|
|
@need 700
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@deffn Command forward-word count
|
|
This command moves point forward @@var@{count@} words
|
|
(or backward if @@var@{count@} is negative). @dots{}
|
|
@@end deffn
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
@deffn Command forward-word count
|
|
This function moves point forward @var{count} words
|
|
(or backward if @var{count} is negative). @dots{}
|
|
@end deffn
|
|
@end quotation
|
|
|
|
Capitalize the category name like a title. If the name of the
|
|
category contains spaces, as in the phrase `Interactive Command',
|
|
write braces around it. For example:@refill
|
|
|
|
@example
|
|
@group
|
|
@@deffn @{Interactive Command@} isearch-forward
|
|
@dots{}
|
|
@@end deffn
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
Otherwise, the second word will be mistaken for the name of the
|
|
entity.@refill
|
|
|
|
Some of the definition commands are more general than others. The
|
|
@code{@@deffn} command, for example, is the general definition command
|
|
for functions and the like---for entities that may take arguments. When
|
|
you use this command, you specify the category to which the entity
|
|
belongs. The @code{@@deffn} command possesses three predefined,
|
|
specialized variations, @code{@@defun}, @code{@@defmac}, and
|
|
@code{@@defspec}, that specify the category for you: ``Function'',
|
|
``Macro'', and ``Special Form'' respectively. The @code{@@defvr}
|
|
command also is accompanied by several predefined, specialized
|
|
variations for describing particular kinds of variables.@refill
|
|
|
|
The template for a specialized definition, such as @code{@@defun}, is
|
|
similar to the template for a generalized definition, except that you
|
|
do not need to specify the category:@refill
|
|
|
|
@example
|
|
@group
|
|
@@defun @var{name} @var{arguments}@dots{}
|
|
@var{body-of-definition}
|
|
@@end defun
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
Thus,
|
|
|
|
@example
|
|
@group
|
|
@@defun buffer-end flag
|
|
This function returns @@code@{(point-min)@} if @@var@{flag@}
|
|
is less than 1, @@code@{(point-max)@} otherwise.
|
|
@dots{}
|
|
@@end defun
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@quotation
|
|
@defun buffer-end flag
|
|
This function returns @code{(point-min)} if @var{flag} is less than 1,
|
|
@code{(point-max)} otherwise. @dots{}
|
|
@end defun
|
|
@end quotation
|
|
|
|
@noindent
|
|
@xref{Sample Function Definition, Sample Function Definition, A Sample
|
|
Function Definition}, for a more detailed example of a function
|
|
definition, including the use of @code{@@example} inside the
|
|
definition.@refill
|
|
|
|
The other specialized commands work like @code{@@defun}.@refill
|
|
|
|
@node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
|
|
@section Optional and Repeated Arguments
|
|
@cindex Optional and repeated arguments
|
|
@cindex Repeated and optional arguments
|
|
@cindex Arguments, repeated and optional
|
|
@cindex Syntax, optional & repeated arguments
|
|
@cindex Meta-syntactic chars for arguments
|
|
|
|
Some entities take optional or repeated arguments, which may be
|
|
specified by a distinctive glyph that uses square brackets and
|
|
ellipses. For @w{example}, a special form often breaks its argument list
|
|
into separate arguments in more complicated ways than a
|
|
straightforward function.@refill
|
|
|
|
@iftex
|
|
An argument enclosed within square brackets is optional.
|
|
Thus, the phrase
|
|
@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
|
|
@var{optional-arg} is optional.
|
|
An argument followed by an ellipsis is optional
|
|
and may be repeated more than once.
|
|
@c This is consistent with Emacs Lisp Reference manual
|
|
Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
|
|
Parentheses are used when several arguments are grouped
|
|
into additional levels of list structure in Lisp.
|
|
@end iftex
|
|
@c The following looks better in Info (no `r', `samp' and `code'):
|
|
@ifinfo
|
|
An argument enclosed within square brackets is optional.
|
|
Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
|
|
An argument followed by an ellipsis is optional
|
|
and may be repeated more than once.
|
|
@c This is consistent with Emacs Lisp Reference manual
|
|
Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
|
|
Parentheses are used when several arguments are grouped
|
|
into additional levels of list structure in Lisp.
|
|
@end ifinfo
|
|
|
|
Here is the @code{@@defspec} line of an example of an imaginary
|
|
special form:@refill
|
|
|
|
@quotation
|
|
@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
|
|
@end defspec
|
|
@tex
|
|
\vskip \parskip
|
|
@end tex
|
|
@end quotation
|
|
|
|
@noindent
|
|
In this example, the arguments @var{from} and @var{to} are optional,
|
|
but must both be present or both absent. If they are present,
|
|
@var{inc} may optionally be specified as well. These arguments are
|
|
grouped with the argument @var{var} into a list, to distinguish them
|
|
from @var{body}, which includes all remaining elements of the
|
|
form.@refill
|
|
|
|
In a Texinfo source file, this @code{@@defspec} line is written like
|
|
this (except it would not be split over two lines, as it is in this
|
|
example).@refill
|
|
|
|
@example
|
|
@group
|
|
@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
|
|
[@@var@{inc@}]]) @@var@{body@}@@dots@{@}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
The function is listed in the Command and Variable Index under
|
|
@samp{foobar}.@refill
|
|
|
|
@node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
|
|
@section Two or More `First' Lines
|
|
@cindex Two `First' Lines for @code{@@deffn}
|
|
@cindex Grouping two definitions together
|
|
@cindex Definitions grouped together
|
|
@findex deffnx
|
|
|
|
To create two or more `first' or header lines for a definition, follow
|
|
the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
|
|
The @code{@@deffnx} command works exactly like @code{@@deffn}
|
|
except that it does not generate extra vertical white space between it
|
|
and the preceding line.@refill
|
|
|
|
@need 1000
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@deffn @{Interactive Command@} isearch-forward
|
|
@@deffnx @{Interactive Command@} isearch-backward
|
|
These two search commands are similar except @dots{}
|
|
@@end deffn
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces
|
|
|
|
@deffn {Interactive Command} isearch-forward
|
|
@deffnx {Interactive Command} isearch-backward
|
|
These two search commands are similar except @dots{}
|
|
@end deffn
|
|
|
|
Each of the other definition commands has an `x' form: @code{@@defunx},
|
|
@code{@@defvrx}, @code{@@deftypefunx}, etc.
|
|
|
|
The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
|
|
|
|
@node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
|
|
@section The Definition Commands
|
|
|
|
Texinfo provides more than a dozen definition commands, all of which
|
|
are described in this section.@refill
|
|
|
|
The definition commands automatically enter the name of the entity in
|
|
the appropriate index: for example, @code{@@deffn}, @code{@@defun},
|
|
and @code{@@defmac} enter function names in the index of functions;
|
|
@code{@@defvr} and @code{@@defvar} enter variable names in the index
|
|
of variables.@refill
|
|
|
|
Although the examples that follow mostly illustrate Lisp, the commands
|
|
can be used for other programming languages.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Functions Commands, Variables Commands, , Def Cmds in Detail
|
|
@subsection Functions and Similar Entities
|
|
|
|
This section describes the commands for describing functions and similar
|
|
entities:@refill
|
|
|
|
@table @code
|
|
@findex deffn
|
|
@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
|
|
The @code{@@deffn} command is the general definition command for
|
|
functions, interactive commands, and similar entities that may take
|
|
arguments. You must choose a term to describe the category of entity
|
|
being defined; for example, ``Function'' could be used if the entity is
|
|
a function. The @code{@@deffn} command is written at the beginning of a
|
|
line and is followed on the same line by the category of entity being
|
|
described, the name of this particular entity, and its arguments, if
|
|
any. Terminate the definition with @code{@@end deffn} on a line of its
|
|
own.@refill
|
|
|
|
@need 750
|
|
For example, here is a definition:
|
|
|
|
@example
|
|
@group
|
|
@@deffn Command forward-char nchars
|
|
Move point forward @@var@{nchars@} characters.
|
|
@@end deffn
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This shows a rather terse definition for a ``command'' named
|
|
@code{forward-char} with one argument, @var{nchars}.
|
|
|
|
@code{@@deffn} prints argument names such as @var{nchars} in italics or
|
|
upper case, as if @code{@@var} had been used, because we think of these
|
|
names as metasyntactic variables---they stand for the actual argument
|
|
values. Within the text of the description, write an argument name
|
|
explicitly with @code{@@var} to refer to the value of the argument. In
|
|
the example above, we used @samp{@@var@{nchars@}} in this way.
|
|
|
|
The template for @code{@@deffn} is:
|
|
|
|
@example
|
|
@group
|
|
@@deffn @var{category} @var{name} @var{arguments}@dots{}
|
|
@var{body-of-definition}
|
|
@@end deffn
|
|
@end group
|
|
@end example
|
|
|
|
@findex defun
|
|
@item @@defun @var{name} @var{arguments}@dots{}
|
|
The @code{@@defun} command is the definition command for functions.
|
|
@code{@@defun} is equivalent to @samp{@@deffn Function
|
|
@dots{}}.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@defun set symbol new-value
|
|
Change the value of the symbol @@var@{symbol@}
|
|
to @@var@{new-value@}.
|
|
@@end defun
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
shows a rather terse definition for a function @code{set} whose
|
|
arguments are @var{symbol} and @var{new-value}. The argument names on
|
|
the @code{@@defun} line automatically appear in italics or upper case as
|
|
if they were enclosed in @code{@@var}. Terminate the definition with
|
|
@code{@@end defun} on a line of its own.@refill
|
|
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@defun @var{function-name} @var{arguments}@dots{}
|
|
@var{body-of-definition}
|
|
@@end defun
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@defun} creates an entry in the index of functions.
|
|
|
|
@findex defmac
|
|
@item @@defmac @var{name} @var{arguments}@dots{}
|
|
The @code{@@defmac} command is the definition command for macros.
|
|
@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
|
|
works like @code{@@defun}.@refill
|
|
|
|
@findex defspec
|
|
@item @@defspec @var{name} @var{arguments}@dots{}
|
|
The @code{@@defspec} command is the definition command for special
|
|
forms. (In Lisp, a special form is an entity much like a function.)
|
|
@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
|
|
@dots{}} and works like @code{@@defun}.@refill
|
|
@end table
|
|
|
|
@node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
|
|
@subsection Variables and Similar Entities
|
|
|
|
Here are the commands for defining variables and similar
|
|
entities:@refill
|
|
|
|
@table @code
|
|
@findex defvr
|
|
@item @@defvr @var{category} @var{name}
|
|
The @code{@@defvr} command is a general definition command for
|
|
something like a variable---an entity that records a value. You must
|
|
choose a term to describe the category of entity being defined; for
|
|
example, ``Variable'' could be used if the entity is a variable.
|
|
Write the @code{@@defvr} command at the beginning of a line and
|
|
followed it on the same line by the category of the entity and the
|
|
name of the entity.@refill
|
|
|
|
Capitalize the category name like a title. If the name of the
|
|
category contains spaces, as in the name `User Option', write braces
|
|
around it. Otherwise, the second word will be mistaken for the name
|
|
of the entity, for example:
|
|
|
|
@example
|
|
@group
|
|
@@defvr @{User Option@} fill-column
|
|
This buffer-local variable specifies
|
|
the maximum width of filled lines.
|
|
@dots{}
|
|
@@end defvr
|
|
@end group
|
|
@end example
|
|
|
|
Terminate the definition with @code{@@end defvr} on a line of its
|
|
own.@refill
|
|
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@defvr @var{category} @var{name}
|
|
@var{body-of-definition}
|
|
@@end defvr
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@defvr} creates an entry in the index of variables for @var{name}.
|
|
|
|
@findex defvar
|
|
@item @@defvar @var{name}
|
|
The @code{@@defvar} command is the definition command for variables.
|
|
@code{@@defvar} is equivalent to @samp{@@defvr Variable
|
|
@dots{}}.@refill
|
|
|
|
@need 750
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
@@defvar kill-ring
|
|
@dots{}
|
|
@@end defvar
|
|
@end group
|
|
@end example
|
|
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@defvar @var{name}
|
|
@var{body-of-definition}
|
|
@@end defvar
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@defvar} creates an entry in the index of variables for
|
|
@var{name}.@refill
|
|
|
|
@findex defopt
|
|
@item @@defopt @var{name}
|
|
The @code{@@defopt} command is the definition command for user
|
|
options. @code{@@defopt} is equivalent to @samp{@@defvr @{User
|
|
Option@} @dots{}} and works like @code{@@defvar}.@refill
|
|
@end table
|
|
|
|
@node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
|
|
@subsection Functions in Typed Languages
|
|
|
|
The @code{@@deftypefn} command and its variations are for describing
|
|
functions in C or any other language in which you must declare types
|
|
of variables and functions.@refill
|
|
|
|
@table @code
|
|
@findex deftypefn
|
|
@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
|
|
The @code{@@deftypefn} command is the general definition command for
|
|
functions and similar entities that may take arguments and that are
|
|
typed. The @code{@@deftypefn} command is written at the beginning of
|
|
a line and is followed on the same line by the category of entity
|
|
being described, the type of the returned value, the name of this
|
|
particular entity, and its arguments, if any.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@deftypefn @{Library Function@} int foobar
|
|
(int @@var@{foo@}, float @@var@{bar@})
|
|
@dots{}
|
|
@@end deftypefn
|
|
@end group
|
|
@end example
|
|
|
|
@need 1000
|
|
@noindent
|
|
(where the text before the ``@dots{}'', shown above as two lines, would
|
|
actually be a single line in a real Texinfo file) produces the following
|
|
in Info:
|
|
|
|
@smallexample
|
|
@group
|
|
-- Library Function: int foobar (int FOO, float BAR)
|
|
@dots{}
|
|
@end group
|
|
@end smallexample
|
|
@iftex
|
|
|
|
In a printed manual, it produces:
|
|
|
|
@quotation
|
|
@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
|
|
@dots{}
|
|
@end deftypefn
|
|
@end quotation
|
|
@end iftex
|
|
|
|
This means that @code{foobar} is a ``library function'' that returns an
|
|
@code{int}, and its arguments are @var{foo} (an @code{int}) and
|
|
@var{bar} (a @code{float}).@refill
|
|
|
|
The argument names that you write in @code{@@deftypefn} are not subject
|
|
to an implicit @code{@@var}---since the actual names of the arguments in
|
|
@code{@@deftypefn} are typically scattered among data type names and
|
|
keywords, Texinfo cannot find them without help. Instead, you must write
|
|
@code{@@var} explicitly around the argument names. In the example
|
|
above, the argument names are @samp{foo} and @samp{bar}.@refill
|
|
|
|
The template for @code{@@deftypefn} is:@refill
|
|
|
|
@example
|
|
@group
|
|
@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
|
|
@var{body-of-description}
|
|
@@end deftypefn
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
Note that if the @var{category} or @var{data type} is more than one
|
|
word then it must be enclosed in braces to make it a single argument.@refill
|
|
|
|
If you are describing a procedure in a language that has packages,
|
|
such as Ada, you might consider using @code{@@deftypefn} in a manner
|
|
somewhat contrary to the convention described in the preceding
|
|
paragraphs.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
@@deftypefn stacks private push
|
|
(@@var@{s@}:in out stack;
|
|
@@var@{n@}:in integer)
|
|
@dots{}
|
|
@@end deftypefn
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(The @code{@@deftypefn} arguments are shown split into three lines, but
|
|
would be a single line in a real Texinfo file.)
|
|
|
|
In this instance, the procedure is classified as belonging to the
|
|
package @code{stacks} rather than classified as a `procedure' and its
|
|
data type is described as @code{private}. (The name of the procedure
|
|
is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
|
|
|
|
@code{@@deftypefn} creates an entry in the index of functions for
|
|
@var{name}.@refill
|
|
|
|
@findex deftypefun
|
|
@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
|
|
The @code{@@deftypefun} command is the specialized definition command
|
|
for functions in typed languages. The command is equivalent to
|
|
@samp{@@deftypefn Function @dots{}}.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
Thus,
|
|
|
|
@smallexample
|
|
@group
|
|
@@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
|
|
@dots{}
|
|
@@end deftypefun
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
produces the following in Info:
|
|
|
|
@example
|
|
@group
|
|
-- Function: int foobar (int FOO, float BAR)
|
|
@dots{}
|
|
@end group
|
|
@end example
|
|
@iftex
|
|
|
|
@need 800
|
|
@noindent
|
|
and the following in a printed manual:
|
|
|
|
@quotation
|
|
@deftypefun int foobar (int @var{foo}, float @var{bar})
|
|
@dots{}
|
|
@end deftypefun
|
|
@end quotation
|
|
@end iftex
|
|
|
|
@need 800
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@deftypefun @var{type} @var{name} @var{arguments}@dots{}
|
|
@var{body-of-description}
|
|
@@end deftypefun
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@deftypefun} creates an entry in the index of functions for
|
|
@var{name}.@refill
|
|
@end table
|
|
|
|
@node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
|
|
@subsection Variables in Typed Languages
|
|
|
|
Variables in typed languages are handled in a manner similar to
|
|
functions in typed languages. @xref{Typed Functions}. The general
|
|
definition command @code{@@deftypevr} corresponds to
|
|
@code{@@deftypefn} and the specialized definition command
|
|
@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
|
|
|
|
@table @code
|
|
@findex deftypevr
|
|
@item @@deftypevr @var{category} @var{data-type} @var{name}
|
|
The @code{@@deftypevr} command is the general definition command for
|
|
something like a variable in a typed language---an entity that records
|
|
a value. You must choose a term to describe the category of the
|
|
entity being defined; for example, ``Variable'' could be used if the
|
|
entity is a variable.@refill
|
|
|
|
The @code{@@deftypevr} command is written at the beginning of a line
|
|
and is followed on the same line by the category of the entity
|
|
being described, the data type, and the name of this particular
|
|
entity.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
@@deftypevr @{Global Flag@} int enable
|
|
@dots{}
|
|
@@end deftypevr
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces the following in Info:
|
|
|
|
@example
|
|
@group
|
|
-- Global Flag: int enable
|
|
@dots{}
|
|
@end group
|
|
@end example
|
|
@iftex
|
|
|
|
@noindent
|
|
and the following in a printed manual:
|
|
|
|
@quotation
|
|
@deftypevr {Global Flag} int enable
|
|
@dots{}
|
|
@end deftypevr
|
|
@end quotation
|
|
@end iftex
|
|
|
|
@need 800
|
|
The template is:
|
|
|
|
@example
|
|
@@deftypevr @var{category} @var{data-type} @var{name}
|
|
@var{body-of-description}
|
|
@@end deftypevr
|
|
@end example
|
|
|
|
@code{@@deftypevr} creates an entry in the index of variables for
|
|
@var{name}.@refill
|
|
|
|
@findex deftypevar
|
|
@item @@deftypevar @var{data-type} @var{name}
|
|
The @code{@@deftypevar} command is the specialized definition command
|
|
for variables in typed languages. @code{@@deftypevar} is equivalent
|
|
to @samp{@@deftypevr Variable @dots{}}.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
@@deftypevar int fubar
|
|
@dots{}
|
|
@@end deftypevar
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
produces the following in Info:
|
|
|
|
@example
|
|
@group
|
|
-- Variable: int fubar
|
|
@dots{}
|
|
@end group
|
|
@end example
|
|
@iftex
|
|
|
|
@need 800
|
|
@noindent
|
|
and the following in a printed manual:
|
|
|
|
@quotation
|
|
@deftypevar int fubar
|
|
@dots{}
|
|
@end deftypevar
|
|
@end quotation
|
|
@end iftex
|
|
|
|
@need 800
|
|
@noindent
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@deftypevar @var{data-type} @var{name}
|
|
@var{body-of-description}
|
|
@@end deftypevar
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@deftypevar} creates an entry in the index of variables for
|
|
@var{name}.@refill
|
|
@end table
|
|
|
|
@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail
|
|
@subsection Object-Oriented Programming
|
|
|
|
Here are the commands for formatting descriptions about abstract
|
|
objects, such as are used in object-oriented programming. A class is
|
|
a defined type of abstract object. An instance of a class is a
|
|
particular object that has the type of the class. An instance
|
|
variable is a variable that belongs to the class but for which each
|
|
instance has its own value.@refill
|
|
|
|
In a definition, if the name of a class is truly a name defined in the
|
|
programming system for a class, then you should write an @code{@@code}
|
|
around it. Otherwise, it is printed in the usual text font.@refill
|
|
|
|
@table @code
|
|
@findex defcv
|
|
@item @@defcv @var{category} @var{class} @var{name}
|
|
The @code{@@defcv} command is the general definition command for
|
|
variables associated with classes in object-oriented programming. The
|
|
@code{@@defcv} command is followed by three arguments: the category of
|
|
thing being defined, the class to which it belongs, and its
|
|
name. Thus,@refill
|
|
|
|
@example
|
|
@group
|
|
@@defcv @{Class Option@} Window border-pattern
|
|
@dots{}
|
|
@@end defcv
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
illustrates how you would write the first line of a definition of the
|
|
@code{border-pattern} class option of the class @code{Window}.@refill
|
|
|
|
The template is
|
|
|
|
@example
|
|
@group
|
|
@@defcv @var{category} @var{class} @var{name}
|
|
@dots{}
|
|
@@end defcv
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@defcv} creates an entry in the index of variables.
|
|
|
|
@findex defivar
|
|
@item @@defivar @var{class} @var{name}
|
|
The @code{@@defivar} command is the definition command for instance
|
|
variables in object-oriented programming. @code{@@defivar} is
|
|
equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
|
|
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@defivar @var{class} @var{instance-variable-name}
|
|
@var{body-of-definition}
|
|
@@end defivar
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@defivar} creates an entry in the index of variables.
|
|
|
|
@findex defop
|
|
@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
|
|
The @code{@@defop} command is the general definition command for
|
|
entities that may resemble methods in object-oriented programming.
|
|
These entities take arguments, as functions do, but are associated
|
|
with particular classes of objects.@refill
|
|
|
|
For example, some systems have constructs called @dfn{wrappers} that
|
|
are associated with classes as methods are, but that act more like
|
|
macros than like functions. You could use @code{@@defop Wrapper} to
|
|
describe one of these.@refill
|
|
|
|
Sometimes it is useful to distinguish methods and @dfn{operations}.
|
|
You can think of an operation as the specification for a method.
|
|
Thus, a window system might specify that all window classes have a
|
|
method named @code{expose}; we would say that this window system
|
|
defines an @code{expose} operation on windows in general. Typically,
|
|
the operation has a name and also specifies the pattern of arguments;
|
|
all methods that implement the operation must accept the same
|
|
arguments, since applications that use the operation do so without
|
|
knowing which method will implement it.@refill
|
|
|
|
Often it makes more sense to document operations than methods. For
|
|
example, window application developers need to know about the
|
|
@code{expose} operation, but need not be concerned with whether a
|
|
given class of windows has its own method to implement this operation.
|
|
To describe this operation, you would write:@refill
|
|
|
|
@example
|
|
@@defop Operation windows expose
|
|
@end example
|
|
|
|
The @code{@@defop} command is written at the beginning of a line and
|
|
is followed on the same line by the overall name of the category of
|
|
operation, the name of the class of the operation, the name of the
|
|
operation, and its arguments, if any.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
|
|
@var{body-of-definition}
|
|
@@end defop
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@defop} creates an entry, such as `@code{expose} on
|
|
@code{windows}', in the index of functions.@refill
|
|
|
|
@findex defmethod
|
|
@item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
|
|
The @code{@@defmethod} command is the definition command for methods
|
|
in object-oriented programming. A method is a kind of function that
|
|
implements an operation for a particular class of objects and its
|
|
subclasses. In the Lisp Machine, methods actually were functions, but
|
|
they were usually defined with @code{defmethod}.
|
|
|
|
@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
|
|
The command is written at the beginning of a line and is followed by
|
|
the name of the class of the method, the name of the method, and its
|
|
arguments, if any.@refill
|
|
|
|
@need 800
|
|
@noindent
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
@@defmethod @code{bar-class} bar-method argument
|
|
@dots{}
|
|
@@end defmethod
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
illustrates the definition for a method called @code{bar-method} of
|
|
the class @code{bar-class}. The method takes an argument.@refill
|
|
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
|
|
@var{body-of-definition}
|
|
@@end defmethod
|
|
@end group
|
|
@end example
|
|
|
|
@c !!! reworded to prevent overfull hbox --bob 26 Mar 93
|
|
@code{@@defmethod} creates an entry in the index of functions, such as
|
|
`@code{bar-method} on @code{bar-class}'.@refill
|
|
@end table
|
|
|
|
@node Data Types, , Abstract Objects, Def Cmds in Detail
|
|
@subsection Data Types
|
|
|
|
Here is the command for data types:@refill
|
|
|
|
@table @code
|
|
@findex deftp
|
|
@item @@deftp @var{category} @var{name} @var{attributes}@dots{}
|
|
The @code{@@deftp} command is the generic definition command for data
|
|
types. The command is written at the beginning of a line and is
|
|
followed on the same line by the category, by the name of the type
|
|
(which is a word like @code{int} or @code{float}), and then by names of
|
|
attributes of objects of that type. Thus, you could use this command
|
|
for describing @code{int} or @code{float}, in which case you could use
|
|
@code{data type} as the category. (A data type is a category of
|
|
certain objects for purposes of deciding which operations can be
|
|
performed on them.)@refill
|
|
|
|
In Lisp, for example, @dfn{pair} names a particular data
|
|
type, and an object of that type has two slots called the
|
|
@sc{car} and the @sc{cdr}. Here is how you would write the first line
|
|
of a definition of @code{pair}.@refill
|
|
|
|
@example
|
|
@group
|
|
@@deftp @{Data type@} pair car cdr
|
|
@dots{}
|
|
@@end deftp
|
|
@end group
|
|
@end example
|
|
|
|
@need 950
|
|
The template is:
|
|
|
|
@example
|
|
@group
|
|
@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
|
|
@var{body-of-definition}
|
|
@@end deftp
|
|
@end group
|
|
@end example
|
|
|
|
@code{@@deftp} creates an entry in the index of data types.
|
|
@end table
|
|
|
|
@node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
|
|
@section Conventions for Writing Definitions
|
|
@cindex Definition conventions
|
|
@cindex Conventions for writing definitions
|
|
|
|
When you write a definition using @code{@@deffn}, @code{@@defun}, or
|
|
one of the other definition commands, please take care to use
|
|
arguments that indicate the meaning, as with the @var{count} argument
|
|
to the @code{forward-word} function. Also, if the name of an argument
|
|
contains the name of a type, such as @var{integer}, take care that the
|
|
argument actually is of that type.@refill
|
|
|
|
@node Sample Function Definition, , Def Cmd Conventions, Definition Commands
|
|
@section A Sample Function Definition
|
|
@cindex Function definitions
|
|
@cindex Command definitions
|
|
@cindex Macro definitions
|
|
@cindex Sample function definition
|
|
|
|
A function definition uses the @code{@@defun} and @code{@@end defun}
|
|
commands. The name of the function follows immediately after the
|
|
@code{@@defun} command and it is followed, on the same line, by the
|
|
parameter list.@refill
|
|
|
|
Here is a definition from @cite{The GNU Emacs Lisp Reference Manual}.
|
|
(@xref{Calling Functions, , Calling Functions, elisp, The GNU Emacs
|
|
Lisp Reference Manual}.)
|
|
|
|
@quotation
|
|
@defun apply function &rest arguments
|
|
@code{apply} calls @var{function} with @var{arguments}, just
|
|
like @code{funcall} but with one difference: the last of
|
|
@var{arguments} is a list of arguments to give to
|
|
@var{function}, rather than a single argument. We also say
|
|
that this list is @dfn{appended} to the other arguments.
|
|
|
|
@code{apply} returns the result of calling @var{function}.
|
|
As with @code{funcall}, @var{function} must either be a Lisp
|
|
function or a primitive function; special forms and macros
|
|
do not make sense in @code{apply}.
|
|
|
|
@example
|
|
(setq f 'list)
|
|
@result{} list
|
|
(apply f 'x 'y 'z)
|
|
@error{} Wrong type argument: listp, z
|
|
(apply '+ 1 2 '(3 4))
|
|
@result{} 10
|
|
(apply '+ '(1 2 3 4))
|
|
@result{} 10
|
|
|
|
(apply 'append '((a b c) nil (x y z) nil))
|
|
@result{} (a b c x y z)
|
|
@end example
|
|
|
|
An interesting example of using @code{apply} is found in the description
|
|
of @code{mapcar}.@refill
|
|
@end defun
|
|
@end quotation
|
|
|
|
@need 1200
|
|
In the Texinfo source file, this example looks like this:
|
|
|
|
@example
|
|
@group
|
|
@@defun apply function &rest arguments
|
|
|
|
@@code@{apply@} calls @@var@{function@} with
|
|
@@var@{arguments@}, just like @@code@{funcall@} but with one
|
|
difference: the last of @@var@{arguments@} is a list of
|
|
arguments to give to @@var@{function@}, rather than a single
|
|
argument. We also say that this list is @@dfn@{appended@}
|
|
to the other arguments.
|
|
@end group
|
|
|
|
@group
|
|
@@code@{apply@} returns the result of calling
|
|
@@var@{function@}. As with @@code@{funcall@},
|
|
@@var@{function@} must either be a Lisp function or a
|
|
primitive function; special forms and macros do not make
|
|
sense in @@code@{apply@}.
|
|
@end group
|
|
|
|
@group
|
|
@@example
|
|
(setq f 'list)
|
|
@@result@{@} list
|
|
(apply f 'x 'y 'z)
|
|
@@error@{@} Wrong type argument: listp, z
|
|
(apply '+ 1 2 '(3 4))
|
|
@@result@{@} 10
|
|
(apply '+ '(1 2 3 4))
|
|
@@result@{@} 10
|
|
|
|
(apply 'append '((a b c) nil (x y z) nil))
|
|
@@result@{@} (a b c x y z)
|
|
@@end example
|
|
@end group
|
|
|
|
@group
|
|
An interesting example of using @@code@{apply@} is found
|
|
in the description of @@code@{mapcar@}.@@refill
|
|
@@end defun
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
In this manual, this function is listed in the Command and Variable
|
|
Index under @code{apply}.@refill
|
|
|
|
Ordinary variables and user options are described using a format like
|
|
that for functions except that variables do not take arguments.
|
|
|
|
@node Footnotes, Conditionals, Definition Commands, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Footnotes
|
|
@cindex Footnotes
|
|
@findex footnote
|
|
|
|
A @dfn{footnote} is for a reference that documents or elucidates the
|
|
primary text.@footnote{A footnote should complement or expand upon
|
|
the primary text, but a reader should not need to read a footnote to
|
|
understand the primary text. For a thorough discussion of footnotes,
|
|
see @cite{The Chicago Manual of Style}, which is published by the
|
|
University of Chicago Press.}@refill
|
|
|
|
In Texinfo, footnotes are created with the @code{@@footnote} command.
|
|
This command is followed immediately by a left brace, then by the text
|
|
of the footnote, and then by a terminating right brace. The template
|
|
is:
|
|
|
|
@example
|
|
@@footnote@{@var{text}@}
|
|
@end example
|
|
|
|
Footnotes may be of any length, but are usually short.@refill
|
|
|
|
For example, this clause is followed by a sample
|
|
footnote@footnote{Here is the sample footnote.}; in the Texinfo
|
|
source, it looks like this:@refill
|
|
|
|
@example
|
|
@dots{}a sample footnote @@footnote@{Here is the sample
|
|
footnote.@}; in the Texinfo source@dots{}
|
|
@end example
|
|
|
|
In a printed manual or book, the reference mark for a footnote is a
|
|
small, superscripted number; the text of the footnote is written at
|
|
the bottom of the page, below a horizontal line.@refill
|
|
|
|
In Info, the reference mark for a footnote is a pair of parentheses
|
|
with the footnote number between them, like this: @samp{(1)}.@refill
|
|
|
|
Info has two footnote styles, which determine where the text of the
|
|
footnote is located:@refill
|
|
|
|
@itemize @bullet
|
|
@cindex @samp{@r{End}} node footnote style
|
|
@item
|
|
In the `End' node style, all the footnotes for a single node
|
|
are placed at the end of that node. The footnotes are separated from
|
|
the rest of the node by a line of dashes with the word
|
|
@samp{Footnotes} within it. Each footnote begins with an
|
|
@samp{(@var{n})} reference mark.@refill
|
|
|
|
@need 700
|
|
@noindent
|
|
Here is an example of a single footnote in the end of node style:@refill
|
|
|
|
@example
|
|
@group
|
|
--------- Footnotes ---------
|
|
|
|
(1) Here is a sample footnote.
|
|
@end group
|
|
@end example
|
|
|
|
@cindex @samp{@r{Separate}} footnote style
|
|
@item
|
|
In the `Separate' node style, all the footnotes for a single
|
|
node are placed in an automatically constructed node of
|
|
their own. In this style, a ``footnote reference'' follows
|
|
each @samp{(@var{n})} reference mark in the body of the
|
|
node. The footnote reference is actually a cross reference
|
|
which you use to reach the footnote node.@refill
|
|
|
|
The name of the node containing the footnotes is constructed
|
|
by appending @w{@samp{-Footnotes}} to the name of the node
|
|
that contains the footnotes. (Consequently, the footnotes'
|
|
node for the @file{Footnotes} node is
|
|
@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
|
|
`Up' node pointer that leads back to its parent node.@refill
|
|
|
|
@noindent
|
|
Here is how the first footnote in this manual looks after being
|
|
formatted for Info in the separate node style:@refill
|
|
|
|
@smallexample
|
|
@group
|
|
File: texinfo.info Node: Overview-Footnotes, Up: Overview
|
|
|
|
(1) Note that the first syllable of "Texinfo" is
|
|
pronounced like "speck", not "hex". @dots{}
|
|
@end group
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
A Texinfo file may be formatted into an Info file with either footnote
|
|
style.@refill
|
|
|
|
@findex footnotestyle
|
|
Use the @code{@@footnotestyle} command to specify an Info file's
|
|
footnote style. Write this command at the beginning of a line followed
|
|
by an argument, either @samp{end} for the end node style or
|
|
@samp{separate} for the separate node style.
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
@@footnotestyle end
|
|
@end example
|
|
@noindent
|
|
or
|
|
@example
|
|
@@footnotestyle separate
|
|
@end example
|
|
|
|
Write an @code{@@footnotestyle} command before or shortly after the
|
|
end-of-header line at the beginning of a Texinfo file. (If you
|
|
include the @code{@@footnotestyle} command between the start-of-header
|
|
and end-of-header lines, the region formatting commands will format
|
|
footnotes as specified.)@refill
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
If you do not specify a footnote style, the formatting commands use
|
|
their default style. Currently, @code{makeinfo} uses the `end' style,
|
|
while @code{texinfo-format-buffer} and @code{texinfo-format-region}
|
|
use the `separate' style.@refill
|
|
|
|
@c !!! note: makeinfo's --footnote-style option overrides footnotestyle
|
|
@ignore
|
|
If you use @code{makeinfo} to create the Info file, the
|
|
@samp{--footnote-style} option determines which style is used,
|
|
@samp{end} for the end of node style or @samp{separate} for the
|
|
separate node style. Thus, to format the Texinfo manual in the
|
|
separate node style, you would use the following shell command:@refill
|
|
|
|
@example
|
|
makeinfo --footnote-style=separate texinfo.texi
|
|
@end example
|
|
|
|
@noindent
|
|
To format the Texinfo manual in the end of node style, you would
|
|
type:@refill
|
|
|
|
@example
|
|
makeinfo --footnote-style=end texinfo.texi
|
|
@end example
|
|
@end ignore
|
|
@ignore
|
|
If you use @code{texinfo-format-buffer} or
|
|
@code{texinfo-format-region} to create the Info file, the value of the
|
|
@code{texinfo-footnote-style} variable controls the footnote style.
|
|
It can be either @samp{"separate"} for the separate node style or
|
|
@samp{"end"} for the end of node style. (You can change the value of
|
|
this variable with the @kbd{M-x edit-options} command (@pxref{Edit
|
|
Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or
|
|
with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
|
|
and Setting Variables, emacs, The GNU Emacs Manual}).@refill
|
|
|
|
The @code{texinfo-footnote-style} variable also controls the style if
|
|
you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
|
|
command in Emacs.@refill
|
|
@end ignore
|
|
This chapter contains two footnotes.@refill
|
|
|
|
@node Conditionals, Format/Print Hardcopy, Footnotes, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Conditionally Visible Text
|
|
@cindex Conditionally visible text
|
|
@cindex Text, conditionally visible
|
|
@cindex Visibility of conditional text
|
|
@cindex If text conditionally visible
|
|
@findex ifinfo
|
|
@findex iftex
|
|
|
|
Sometimes it is good to use different text for a printed manual and
|
|
its corresponding Info file. In this case, you can use the
|
|
@dfn{conditional commands} to specify which text is for the printed manual
|
|
and which is for the Info file.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Conditional Commands, Using Ordinary TeX Commands, , Conditionals
|
|
@ifinfo
|
|
@heading Using @code{@@ifinfo} and @code{@@iftex}
|
|
@end ifinfo
|
|
|
|
@code{@@ifinfo} begins segments of text that should be ignored
|
|
by @TeX{} when it
|
|
typesets the printed manual. The segment of text appears only
|
|
in the Info file.
|
|
The @code{@@ifinfo} command should appear on a line by itself; end
|
|
the Info-only text with a line containing @code{@@end ifinfo} by
|
|
itself. At the beginning of a Texinfo file, the Info permissions are
|
|
contained within a region marked by @code{@@ifinfo} and @code{@@end
|
|
ifinfo}. (@xref{Info Summary and Permissions}.)@refill
|
|
|
|
The @code{@@iftex} and @code{@@end iftex} commands are similar to the
|
|
@code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
|
|
specify text that will appear in the printed manual but not in the Info
|
|
file.@refill
|
|
|
|
@need 700
|
|
For example,
|
|
|
|
@example
|
|
@@iftex
|
|
This text will appear only in the printed manual.
|
|
@@end iftex
|
|
|
|
@@ifinfo
|
|
However, this text will appear only in Info.
|
|
@@end ifinfo
|
|
@end example
|
|
|
|
@noindent
|
|
The preceding example produces the following line:
|
|
|
|
@iftex
|
|
This text will appear only in the printed manual.
|
|
@end iftex
|
|
|
|
@ifinfo
|
|
However, this text will appear only in Info.
|
|
@end ifinfo
|
|
|
|
@noindent
|
|
Note how you only see one of the two lines, depending on whether you
|
|
are reading the Info version or the printed version of this
|
|
manual.@refill
|
|
|
|
The @code{@@titlepage} command is a special variant of @code{@@iftex} that
|
|
is used for making the title and copyright pages of the printed
|
|
manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill
|
|
|
|
@node Using Ordinary TeX Commands, set clear value, Conditional Commands, Conditionals
|
|
@comment node-name, next, previous, up
|
|
@section Using Ordinary @TeX{} Commands
|
|
@cindex @TeX{} commands, using ordinary
|
|
@cindex Ordinary @TeX{} commands, using
|
|
@cindex Commands using ordinary @TeX{}
|
|
@cindex Plain@TeX{}
|
|
|
|
Inside a region delineated by @code{@@iftex} and @code{@@end iftex},
|
|
you can embed some Plain@TeX{} commands. Info will ignore these
|
|
commands since they are only in that part of the file which is seen by
|
|
@TeX{}. You can write the @TeX{} commands as you would write them in
|
|
a normal @TeX{} file, except that you must replace the @samp{\} used
|
|
by @TeX{} with an @samp{@@}. For example, in the @code{@@titlepage}
|
|
section of a Texinfo file, you can use the @TeX{} command
|
|
@code{@@vskip} to format the copyright page. (The @code{@@titlepage}
|
|
command causes Info to ignore the region automatically, as it does
|
|
with the @code{@@iftex} command.)@refill
|
|
|
|
However, many features of Plain@TeX{} will not work, as they are
|
|
overridden by features of Texinfo.
|
|
|
|
@findex tex
|
|
You can enter Plain@TeX{} completely, and use @samp{\} in the @TeX{}
|
|
commands, by delineating a region with the @code{@@tex} and @code{@@end
|
|
tex} commands. (The @code{@@tex} command also causes Info to ignore the
|
|
region, like the @code{@@iftex}
|
|
command.)@refill
|
|
|
|
@cindex Mathematical expressions
|
|
For example, here is a mathematical expression written in
|
|
Plain@TeX{}:@refill
|
|
|
|
@example
|
|
@@tex
|
|
$$ \chi^2 = \sum_@{i=1@}^N
|
|
\left (y_i - (a + b x_i)
|
|
\over \sigma_i\right)^2 $$
|
|
@@end tex
|
|
@end example
|
|
|
|
@noindent
|
|
The output of this example will appear only in a printed manual. If
|
|
you are reading this in Info, you will not see anything after this
|
|
paragraph.
|
|
@iftex
|
|
In a printed manual, the above expression looks like
|
|
this:
|
|
@end iftex
|
|
|
|
@tex
|
|
$$ \chi^2 = \sum_{i=1}^N
|
|
\left(y_i - (a + b x_i)
|
|
\over \sigma_i\right)^2 $$
|
|
@end tex
|
|
|
|
@node set clear value, , Using Ordinary TeX Commands, Conditionals
|
|
@comment node-name, next, previous, up
|
|
@section @code{@@set}, @code{@@clear}, and @code{@@value}
|
|
|
|
You can direct the Texinfo formatting commands to format or ignore parts
|
|
of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
|
|
and @code{@@ifclear} commands.@refill
|
|
|
|
In addition, you can use the @code{@@set @var{flag}} command to set the
|
|
value of @var{flag} to a string of characters; and use
|
|
@code{@@value@{@var{flag}@}} to insert that string. You can use
|
|
@code{@@set}, for example, to set a date and use @code{@@value} to
|
|
insert the date in several places in the Texinfo file.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node ifset ifclear, value, , set clear value
|
|
@subsection @code{@@ifset} and @code{@@ifclear}
|
|
|
|
@findex ifset
|
|
When a @var{flag} is set, the Texinfo formatting commands format text
|
|
between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
|
|
ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
|
|
commands do @emph{not} format the text.
|
|
|
|
Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a
|
|
@var{flag}; a @dfn{flag} can be any single word. The format for the
|
|
command looks like this:@refill
|
|
@findex set
|
|
|
|
@example
|
|
@@set @var{flag}
|
|
@end example
|
|
|
|
Write the conditionally formatted text between @code{@@ifset @var{flag}}
|
|
and @code{@@end ifset} commands, like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@ifset @var{flag}
|
|
@var{conditional-text}
|
|
@@end ifset
|
|
@end group
|
|
@end example
|
|
|
|
For example, you can create one document that has two variants, such as
|
|
a manual for a `large' and `small' model:@refill
|
|
|
|
@example
|
|
You can use this machine to dig up shrubs
|
|
without hurting them.
|
|
|
|
@@set large
|
|
|
|
@@ifset large
|
|
It can also dig up fully grown trees.
|
|
@@end ifset
|
|
|
|
Remember to replant promptly @dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
In the example, the formatting commands will format the text between
|
|
@code{@@ifset large} and @code{@@end ifset} because the @code{large}
|
|
flag is set.@refill
|
|
|
|
@findex clear
|
|
Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear},
|
|
a flag. Clearing a flag is the opposite of setting a flag. The
|
|
command looks like this:@refill
|
|
|
|
@example
|
|
@@clear @var{flag}
|
|
@end example
|
|
|
|
@noindent
|
|
Write the command on a line of its own.
|
|
|
|
When @var{flag} is cleared, the Texinfo formatting commands do
|
|
@emph{not} format the text between @code{@@ifset @var{flag}} and
|
|
@code{@@end ifset}; that text is ignored and does not appear in either
|
|
printed or Info output.@refill
|
|
|
|
For example, if you clear the flag of the preceding example by writing
|
|
an @code{@@clear large} command after the @code{@@set large} command
|
|
(but before the conditional text), then the Texinfo formatting commands
|
|
ignore the text between the @code{@@ifset large} and @code{@@end ifset}
|
|
commands. In the formatted output, that text does not appear; in both
|
|
printed and Info output, you see only the lines that say, ``You can use
|
|
this machine to dig up shrubs without hurting them. Remember to replant
|
|
promptly @dots{}''.
|
|
|
|
@findex ifclear
|
|
If a flag is cleared with an @code{@@clear @var{flag}} command, then
|
|
the formatting commands format text between subsequent pairs of
|
|
@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
|
|
is set with @code{@@set @var{flag}}, then the formatting commands do
|
|
@emph{not} format text between an @code{@@ifclear} and an @code{@@end
|
|
ifclear} command; rather, they ignore that text. An @code{@@ifclear}
|
|
command looks like this:@refill
|
|
|
|
@example
|
|
@@ifclear @var{flag}
|
|
@end example
|
|
|
|
@need 700
|
|
In brief, the commands are:@refill
|
|
|
|
@table @code
|
|
@item @@set @var{flag}
|
|
Tell the Texinfo formatting commands that @var{flag} is set.@refill
|
|
|
|
@item @@clear @var{flag}
|
|
Tell the Texinfo formatting commands that @var{flag} is cleared.@refill
|
|
|
|
@item @@ifset @var{flag}
|
|
If @var{flag} is set, tell the Texinfo formatting commands to format
|
|
the text up to the following @code{@@end ifset} command.@refill
|
|
|
|
If @var{flag} is cleared, tell the Texinfo formatting commands to
|
|
ignore text up to the following @code{@@end ifset} command.@refill
|
|
|
|
@item @@ifclear @var{flag}
|
|
If @var{flag} is set, tell the Texinfo formatting commands to ignore
|
|
the text up to the following @code{@@end ifclear} command.@refill
|
|
|
|
If @var{flag} is cleared, tell the Texinfo formatting commands to
|
|
format the text up to the following @code{@@end ifclear}
|
|
command.@refill
|
|
@end table
|
|
|
|
@node value, value Example, ifset ifclear, set clear value
|
|
@subsection @code{@@value}
|
|
@findex value
|
|
|
|
You can use the @code{@@set} command to specify a value for a flag,
|
|
which is expanded by the @code{@@value} command. The value is a string
|
|
a characters.
|
|
|
|
Write the @code{@@set} command like this:
|
|
|
|
@example
|
|
@@set foo This is a string.
|
|
@end example
|
|
|
|
@noindent
|
|
This sets the value of @code{foo} to ``This is a string.''
|
|
|
|
The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with
|
|
the string to which @var{flag} is set.@refill
|
|
|
|
Thus, when @code{foo} is set as shown above, the Texinfo formatters convert
|
|
|
|
@example
|
|
@group
|
|
@@value@{foo@}
|
|
@exdent @r{to}
|
|
This is a string.
|
|
@end group
|
|
@end example
|
|
|
|
You can write an @code{@@value} command within a paragraph; but you
|
|
must write an @code{@@set} command on a line of its own.
|
|
|
|
If you write the @code{@@set} command like this:
|
|
|
|
@example
|
|
@@set foo
|
|
@end example
|
|
|
|
@noindent
|
|
without specifying a string, the value of @code{foo} is an empty string.
|
|
|
|
If you clear a previously set flag with an @code{@@clear @var{flag}}
|
|
command, a subsequent @code{@@value@{flag@}} command is invalid and the
|
|
string is replaced with an error message that says @samp{@{No value for
|
|
"@var{flag}"@}}.
|
|
|
|
For example, if you set @code{foo} as follows:@refill
|
|
|
|
@example
|
|
@@set how-much very, very, very
|
|
@end example
|
|
|
|
@noindent
|
|
then the formatters transform
|
|
|
|
@example
|
|
@group
|
|
It is a @@value@{how-much@} wet day.
|
|
@exdent @r{into}
|
|
It is a very, very, very wet day.
|
|
@end group
|
|
@end example
|
|
|
|
If you write
|
|
|
|
@example
|
|
@@clear how-much
|
|
@end example
|
|
|
|
@noindent
|
|
then the formatters transform
|
|
|
|
@example
|
|
@group
|
|
It is a @@value@{how-much@} wet day.
|
|
@exdent @r{into}
|
|
It is a @{No value for "how-much"@} wet day.
|
|
@end group
|
|
@end example
|
|
|
|
@node value Example, , value, set clear value
|
|
@subsection @code{@@value} Example
|
|
|
|
You can use the @code{@@value} command to limit the number of places you
|
|
need to change when you record an update to a manual.
|
|
Here is how it is done in @cite{The GNU Make Manual}:
|
|
|
|
@need 1000
|
|
@noindent
|
|
Set the flags:
|
|
|
|
@example
|
|
@group
|
|
@@set EDITION 0.35 Beta
|
|
@@set VERSION 3.63 Beta
|
|
@@set UPDATED 14 August 1992
|
|
@@set UPDATE-MONTH August 1992
|
|
@end group
|
|
@end example
|
|
|
|
@need 750
|
|
@noindent
|
|
Write text for the first @code{@@ifinfo} section, for people reading the
|
|
Texinfo file:
|
|
|
|
@example
|
|
@group
|
|
This is Edition @@value@{EDITION@},
|
|
last updated @@value@{UPDATED@},
|
|
of @@cite@{The GNU Make Manual@},
|
|
for @@code@{make@}, Version @@value@{VERSION@}.
|
|
@end group
|
|
@end example
|
|
|
|
@need 1000
|
|
@noindent
|
|
Write text for the title page, for people reading the printed manual:
|
|
@c List only the month and the year since that looks less fussy on a
|
|
@c printed cover than a date that lists the day as well.
|
|
|
|
@example
|
|
@group
|
|
@@title GNU Make
|
|
@@subtitle A Program for Directing Recompilation
|
|
@@subtitle Edition @@value@{EDITION@}, @dots{}
|
|
@@subtitle @@value@{UPDATE-MONTH@}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(On a printed cover, a date listing the month and the year looks less
|
|
fussy than a date listing the day as well as the month and year.)
|
|
|
|
@need 750
|
|
@noindent
|
|
Write text for the Top node, for people reading the Info file:
|
|
|
|
@example
|
|
@group
|
|
This is Edition @@value@{EDITION@}
|
|
of the @@cite@{GNU Make Manual@},
|
|
last updated @@value@{UPDATED@}
|
|
for @@code@{make@} Version @@value@{VERSION@}.
|
|
@end group
|
|
@end example
|
|
|
|
@need 950
|
|
After you format the manual, the text in the first @code{@@ifinfo}
|
|
section looks like this:
|
|
|
|
@example
|
|
@group
|
|
This is Edition 0.35 Beta, last updated 14 August 1992,
|
|
of `The GNU Make Manual', for `make', Version 3.63 Beta.
|
|
@end group
|
|
@end example
|
|
|
|
When you update the manual, change only the values of the flags; you do
|
|
not need to rewrite the three sections.
|
|
|
|
@node Format/Print Hardcopy, Create an Info File, Conditionals, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Format and Print Hardcopy
|
|
@cindex Format and print hardcopy
|
|
@cindex Hardcopy, printing it
|
|
@cindex Making a printed manual
|
|
@cindex Sorting indices
|
|
@cindex Indices, sorting
|
|
@cindex @TeX{} index sorting
|
|
@findex texindex
|
|
|
|
There are three major shell commands for making a printed manual from a
|
|
Texinfo file: one for converting the Texinfo file into a file that will be
|
|
printed, a second for sorting indices, and a third for printing the
|
|
formatted document. When you use the shell commands, you can either
|
|
work directly in the operating system shell or work within a shell
|
|
inside GNU Emacs.@refill
|
|
|
|
If you are using GNU Emacs, you can use commands provided by Texinfo
|
|
mode instead of shell commands. In addition to the three commands to
|
|
format a file, sort the indices, and print the result, Texinfo mode
|
|
offers key bindings for commands to recenter the output buffer, show the
|
|
print queue, and delete a job from the print queue.@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Use TeX, Shell Format & Print, , Format/Print Hardcopy
|
|
@ifinfo
|
|
@heading Use @TeX{}
|
|
@end ifinfo
|
|
|
|
The typesetting program called @TeX{} is used for formatting a Texinfo
|
|
file. @TeX{} is a very powerful typesetting program and, if used right,
|
|
does an exceptionally good job. @xref{Obtaining TeX, , How to Obtain
|
|
@TeX{}}, for information on how to obtain @TeX{}.@refill
|
|
|
|
The @code{makeinfo}, @code{texinfo-format-region}, and
|
|
@code{texinfo-format-buffer} commands read the very same @@-commands
|
|
in the Texinfo file as does @TeX{}, but process them differently to
|
|
make an Info file; see @ref{Create an Info File}.@refill
|
|
|
|
@node Shell Format & Print, Within Emacs, Use TeX, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section Format and Print Using Shell Commands
|
|
|
|
@cindex DVI file
|
|
Format the Texinfo file with the shell command @code{tex} followed by
|
|
the name of the Texinfo file. This produces a formatted @sc{dvi} file
|
|
as well as several auxiliary files containing indices, cross
|
|
references, etc. The @sc{dvi} file (for @dfn{DeVice Independent}
|
|
file) can be printed on a wide variety of printers.@refill
|
|
|
|
The @code{tex} formatting command itself does not sort the indices; it
|
|
writes an output file of unsorted index data. This is a misfeature of
|
|
@TeX{}. Hence, to generate a printed index, you first need a sorted
|
|
index to work from. The @code{texindex} command sorts indices. (The
|
|
source file @file{texindex.c} comes as part of the standard GNU
|
|
distribution and is usually installed when Emacs is installed.)@refill
|
|
@findex texindex
|
|
@ignore
|
|
Usage: texindex [-k] [-T tempdir] infile [-o outfile] ...
|
|
|
|
Each infile arg can optionally be followed by a `-o outfile' arg;
|
|
for each infile that is not followed by a -o arg, the infile name with
|
|
`s' (for `sorted') appended is used for the outfile.
|
|
|
|
-T dir is the directory to put temp files in, instead of /tmp.
|
|
-k means `keep tempfiles', for debugging.
|
|
@end ignore
|
|
|
|
The @code{tex} formatting command outputs unsorted index files under
|
|
names that obey a standard convention. These names are the name of
|
|
your main input file to the @code{tex} formatting command, with
|
|
everything after the first period thrown away, and the two letter
|
|
names of indices added at the end. For example, the raw index output
|
|
files for the input file @file{foo.texinfo} would be @file{foo.cp},
|
|
@file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and
|
|
@file{foo.ky}. Those are exactly the arguments to give to
|
|
@code{texindex}.@refill
|
|
|
|
@need 1000
|
|
Or else, you can use @samp{??} as ``wild-cards'' and give the command in
|
|
this form:@refill
|
|
|
|
@example
|
|
texindex foo.??
|
|
@end example
|
|
|
|
@noindent
|
|
This command will run @code{texindex} on all the unsorted index files,
|
|
including any that you have defined yourself using @code{@@defindex}
|
|
or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
|
|
even if there are similarly named files with two letter extensions
|
|
that are not index files, such as @samp{foo.el}. The @code{texindex}
|
|
command reports but otherwise ignores such files.)@refill
|
|
|
|
For each file specified, @code{texindex} generates a sorted index file
|
|
whose name is made by appending @samp{s} to the input file name. The
|
|
@code{@@printindex} command knows to look for a file of that name.
|
|
@code{texindex} does not alter the raw index output file.@refill
|
|
|
|
After you have sorted the indices, you need to rerun the @code{tex}
|
|
formatting command on the Texinfo file. This regenerates a formatted
|
|
@sc{dvi} file with up-to-date index entries.@footnote{If you use more
|
|
than one index and have cross references to an index other than the
|
|
first, you must run @code{tex} @emph{three times} to get correct output:
|
|
once to generate raw index data; again (after @code{texindex}) to output
|
|
the text of the indices and determine their true page numbers; and a
|
|
third time to output correct page numbers in cross references to them.
|
|
However, cross references to indices are rare.}@refill
|
|
|
|
To summarize, this is a three step process:
|
|
|
|
@enumerate
|
|
@item
|
|
Run the @code{tex} formatting command on the Texinfo file. This
|
|
generates the formatted @sc{dvi} file as well as the raw index files
|
|
with two letter extensions.@refill
|
|
|
|
@item
|
|
Run the shell command @code{texindex} on the raw index files to sort
|
|
them. This creates the corresponding sorted index files.@refill
|
|
|
|
@item
|
|
Rerun the @code{tex} formatting command on the Texinfo file. This
|
|
regenerates a formatted @sc{dvi} file with the index entries in the
|
|
correct order. This second run also corrects the page numbers for
|
|
the cross references. (The tables of contents are always correct.)@refill
|
|
@end enumerate
|
|
|
|
You need not run @code{texindex} each time after you run the
|
|
@code{tex} formatting. If you do not, on the next run, the @code{tex}
|
|
formatting command will use whatever sorted index files happen to
|
|
exist from the previous use of @code{texindex}. This is usually
|
|
@sc{ok} while you are debugging.@refill
|
|
|
|
@findex texi2dvi @r{(shell script)}
|
|
Rather than type the @code{tex} and @code{texindex} commands yourself,
|
|
you can use @code{texi2dvi}. This shell script is designed to
|
|
simplify the @code{tex}---@code{texindex}---@code{tex} sequence by
|
|
figuring out whether index files and @sc{dvi} files are up-to-date.
|
|
It runs @code{texindex} and @code{tex} only when necessary.
|
|
|
|
@need 1000
|
|
The syntax for @code{texi2dvi} is like this (where @samp{%} is the
|
|
shell prompt):@refill
|
|
|
|
@example
|
|
% texi2dvi @var{filename}@dots{}
|
|
@end example
|
|
|
|
@findex lpr @r{(@sc{dvi} print command)}
|
|
Finally, you can print the @sc{dvi} file with the @sc{dvi} print command.
|
|
The precise command to use depends on the system; @samp{lpr -d} is
|
|
common. The @sc{dvi} print command may require a file name without any
|
|
extension or with a @samp{.dvi} extension.@refill
|
|
|
|
@need 1200
|
|
The following commands, for example, sort the indices, format, and
|
|
print the @cite{Bison Manual} (where @samp{%} is the shell
|
|
prompt):@refill
|
|
|
|
@example
|
|
@group
|
|
% tex bison.texinfo
|
|
% texindex bison.??
|
|
% tex bison.texinfo
|
|
% lpr -d bison.dvi
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(Remember that the shell commands may be different at your site; but
|
|
these are commonly used versions.)@refill
|
|
|
|
@node Within Emacs, Texinfo Mode Printing, Shell Format & Print, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section From an Emacs Shell @dots{}
|
|
@cindex Print, format from Emacs shell
|
|
@cindex Format, print from Emacs shell
|
|
@cindex Shell, format, print from
|
|
@cindex Emacs shell, format, print from
|
|
@cindex GNU Emacs shell, format, print from
|
|
|
|
You can give formatting and printing commands from a shell within GNU
|
|
Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
|
|
shell, you can format and print the document. @xref{Shell Format & Print, ,
|
|
How to Format and Print Using Shell Commands}, for details.@refill
|
|
|
|
You can switch to and from the shell buffer while @code{tex} is
|
|
running and do other editing. If you are formatting a long document
|
|
on a slow machine, this can be very convenient.@refill
|
|
|
|
You can also use @code{texi2dvi} from an Emacs shell. For example,
|
|
here is how to use @code{texi2dvi} to format and print @cite{Using and
|
|
Porting GNU CC} from a shell within Emacs (where @samp{%} is the shell
|
|
prompt):@refill
|
|
|
|
@example
|
|
@group
|
|
% texi2dvi gcc.texinfo
|
|
% lpr -d gcc.dvi
|
|
@end group
|
|
@end example
|
|
@ifinfo
|
|
|
|
@xref{Texinfo Mode Printing}, for more information about formatting
|
|
and printing in Texinfo mode.@refill
|
|
@end ifinfo
|
|
|
|
@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy
|
|
@section Formatting and Printing in Texinfo Mode
|
|
@cindex Region printing in Texinfo mode
|
|
@cindex Format and print in Texinfo mode
|
|
@cindex Print and format in Texinfo mode
|
|
|
|
Texinfo mode provides several predefined key commands for @TeX{}
|
|
formatting and printing. These include commands for sorting indices,
|
|
looking at the printer queue, killing the formatting job, and
|
|
recentering the display of the buffer in which the operations
|
|
occur.@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-t C-r
|
|
@itemx M-x texinfo-tex-region
|
|
Run @TeX{} on the current region.@refill
|
|
|
|
@item C-c C-t C-b
|
|
@itemx M-x texinfo-tex-buffer
|
|
Run @TeX{} on the current buffer.@refill
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
@item C-c C-t C-i
|
|
@itemx M-x texinfo-texindex
|
|
Sort the indices of a Texinfo file that have been formatted with
|
|
@code{texinfo-tex-region} or @code{texinfo-tex-buffer}.@refill
|
|
|
|
@item C-c C-t C-p
|
|
@itemx M-x texinfo-tex-print
|
|
Print a @sc{dvi} file that was made with @code{texinfo-tex-region} or
|
|
@code{texinfo-tex-buffer}.@refill
|
|
|
|
@item C-c C-t C-q
|
|
@itemx M-x texinfo-show-tex-print-queue
|
|
Show the print queue.@refill
|
|
|
|
@item C-c C-t C-d
|
|
@itemx M-x texinfo-delete-from-tex-print-queue
|
|
Delete a job from the print queue; you will be prompted for the job
|
|
number shown by a preceding @kbd{C-c C-t C-q} command
|
|
(@code{texinfo-show-tex-print-queue}).@refill
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
@item C-c C-t C-k
|
|
@itemx M-x texinfo-kill-tex-job
|
|
Kill either the currently running @TeX{} job that has been started by
|
|
@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
|
|
process running in the Texinfo shell buffer.@refill
|
|
|
|
@item C-c C-t C-x
|
|
@itemx M-x texinfo-quit-tex-job
|
|
Quit a @TeX{} formatting job that has stopped because of an error by
|
|
sending an @key{x} to it. When you do this, @TeX{} preserves a record
|
|
of what it did in a @file{.log} file.@refill
|
|
|
|
@item C-c C-t C-l
|
|
@itemx M-x texinfo-recenter-tex-output-buffer
|
|
Redisplay the shell buffer in which the @TeX{} printing and formatting
|
|
commands are run to show its most recent output.@refill
|
|
@end table
|
|
|
|
Thus, the usual sequence of commands for formatting a buffer is as
|
|
follows (with comments to the right):@refill
|
|
|
|
@example
|
|
@group
|
|
C-c C-t C-b @r{Run @TeX{} on the buffer.}
|
|
C-c C-t C-i @r{Sort the indices.}
|
|
C-c C-t C-b @r{Rerun @TeX{} to regenerate indices.}
|
|
C-c C-t C-p @r{Print the @sc{dvi} file.}
|
|
C-c C-t C-q @r{Display the printer queue.}
|
|
@end group
|
|
@end example
|
|
|
|
The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
|
|
called the @file{*texinfo-tex-shell*}. The @code{texinfo-tex-command},
|
|
@code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
|
|
commands are all run in this shell.
|
|
|
|
You can watch the commands operate in the @samp{*texinfo-tex-shell*} buffer,
|
|
and you can switch to and from and use the @samp{*texinfo-tex-shell*} buffer
|
|
as you would any other shell buffer.@refill
|
|
|
|
@need 1500
|
|
The formatting and print commands depend on the values of several variables.
|
|
The default values are:@refill
|
|
|
|
@sp 1
|
|
@example
|
|
@group
|
|
@r{Variable} @r{Default value}
|
|
|
|
texinfo-tex-command "tex"
|
|
texinfo-texindex-command "texindex"
|
|
texinfo-tex-shell-cd-command "cd"
|
|
texinfo-tex-dvi-print-command "lpr -d"
|
|
texinfo-show-tex-queue-command "lpq"
|
|
texinfo-delete-from-print-queue-command "lprm"
|
|
texinfo-start-of-header "%**start"
|
|
texinfo-end-of-header "%**end"
|
|
texinfo-tex-trailer "@@bye"
|
|
@end group
|
|
@end example
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
The default values of both the @code{texinfo-tex-command} and the
|
|
@code{texinfo-texindex-command} variables are set in the @file{texnfo-tex.el}
|
|
file.@refill
|
|
|
|
You can change the values of these variables with the @kbd{M-x
|
|
edit-options} command (@pxref{Edit Options, , Editing Variable Values,
|
|
emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
|
|
(@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
|
|
Emacs Manual}), or with your @file{.emacs} initialization file
|
|
(@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
|
|
|
|
@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section Using the Local Variables List
|
|
@cindex Local variables
|
|
@cindex Compile command for formatting
|
|
@cindex Format with the compile command
|
|
|
|
Yet another way to apply the @TeX{} formatting command to a Texinfo
|
|
file is to put that command in a @dfn{local variables list} at the end
|
|
of the Texinfo file. You can then specify the @TeX{} formatting
|
|
command as a @code{compile-command} and have Emacs run the @TeX{}
|
|
formatting command by typing @kbd{M-x compile}. This creates a
|
|
special shell called the @samp{*compilation buffer*} in which Emacs
|
|
runs the compile command. For example, at the end of the
|
|
@file{gdb.texinfo} file, after the @code{@@bye}, you would put the
|
|
following:@refill
|
|
|
|
@example
|
|
@@c Local Variables:
|
|
@@c compile-command: "tex gdb.texinfo"
|
|
@@c End:
|
|
@end example
|
|
|
|
@noindent
|
|
This technique is most often used by programmers who also compile programs
|
|
this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
|
|
|
|
@node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section @TeX{} Formatting Requirements Summary
|
|
@cindex Requirements for formatting
|
|
@cindex Formatting requirements
|
|
|
|
Every Texinfo file that is to be input to @TeX{} must begin with a
|
|
@code{\input} command and contain an @code{@@settitle} command:@refill
|
|
|
|
@example
|
|
\input texinfo
|
|
@@settitle @var{name-of-manual}
|
|
@end example
|
|
|
|
@noindent
|
|
The first command instructs @TeX{} to load the macros it needs to
|
|
process a Texinfo file and the second command specifies the title of
|
|
printed manual.@refill
|
|
|
|
@need 1000
|
|
Every Texinfo file must end with a line that terminates @TeX{}
|
|
processing and forces out unfinished pages:@refill
|
|
|
|
@example
|
|
@@bye
|
|
@end example
|
|
|
|
Strictly speaking, these three lines are all a Texinfo file needs for
|
|
@TeX{}, besides the body. (The @code{@@setfilename} line is the only
|
|
line that a Texinfo file needs for Info formatting.)@refill
|
|
|
|
Usually, the file's first line contains an @samp{@@c -*-texinfo-*-}
|
|
comment that causes Emacs to switch to Texinfo mode when you edit the
|
|
file. In addition, the beginning usually includes an
|
|
@code{@@setfilename} for Info formatting, an @code{@@setchapternewpage}
|
|
command, a title page, a copyright page, and permissions. Besides an
|
|
@code{@@bye}, the end of a file usually includes indices and a table of
|
|
contents.@refill
|
|
|
|
@iftex
|
|
For more information, see
|
|
@ref{setchapternewpage, , @code{@@setchapternewpage}},
|
|
@ref{Headings, ,Page Headings},
|
|
@ref{Titlepage & Copyright Page},
|
|
@ref{Printing Indices & Menus}, and
|
|
@ref{Contents}.
|
|
@end iftex
|
|
@noindent
|
|
@ifinfo
|
|
For more information, see@*
|
|
@ref{setchapternewpage, , @code{@@setchapternewpage}},@*
|
|
@ref{Headings, ,Page Headings},@*
|
|
@ref{Titlepage & Copyright Page},@*
|
|
@ref{Printing Indices & Menus}, and@*
|
|
@ref{Contents}.
|
|
@end ifinfo
|
|
|
|
@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section Preparing to Use @TeX{}
|
|
@cindex Preparing to use @TeX{}
|
|
@cindex @TeX{} input initialization
|
|
@cindex @code{TEXINPUTS} environment variable
|
|
@vindex TEXINPUTS
|
|
@cindex @b{.profile} initialization file
|
|
@cindex @b{.cshrc} initialization file
|
|
@cindex Initialization file for @TeX{} input
|
|
|
|
@TeX{} needs to know where to find the @file{texinfo.tex} file
|
|
that you have told it to input with the @samp{\input texinfo} command
|
|
at the beginning of the first line. The @file{texinfo.tex} file tells
|
|
@TeX{} how to handle @@-commands. (@file{texinfo.tex} is
|
|
included in the standard GNU distributions.)@refill
|
|
|
|
Usually, the @file{texinfo.tex} file is put in the default directory
|
|
that contains @TeX{} macros (the @file{/usr/lib/tex/macros}
|
|
directory) when GNU Emacs or other GNU software is installed.
|
|
In this case, @TeX{} will
|
|
find the file and you do not need to do anything special.
|
|
Alternatively, you can put @file{texinfo.tex} in the directory in
|
|
which the Texinfo source file is located, and @TeX{} will find it
|
|
there.@refill
|
|
|
|
However, you may want to specify the location of the @code{\input} file
|
|
yourself. One way to do this is to write the complete path for the file
|
|
after the @code{\input} command. Another way is to set the
|
|
@code{TEXINPUTS} environment variable in your @file{.cshrc} or
|
|
@file{.profile} file. The @code{TEXINPUTS} environment variable will tell
|
|
@TeX{} where to find the @file{texinfo.tex} file and any other file that
|
|
you might want @TeX{} to use.@refill
|
|
|
|
Whether you use a @file{.cshrc} or @file{.profile} file depends on
|
|
whether you use @code{csh}, @code{sh}, or @code{bash} for your shell
|
|
command interpreter. When you use @code{csh}, it looks to the
|
|
@file{.cshrc} file for initialization information, and when you use
|
|
@code{sh} or @code{bash}, it looks to the @file{.profile} file.@refill
|
|
|
|
@need 1000
|
|
In a @file{.cshrc} file, you could use the following @code{csh} command
|
|
sequence:@refill
|
|
|
|
@example
|
|
setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros
|
|
@end example
|
|
|
|
@need 1000
|
|
In a @file{.profile} file, you could use the following @code{sh} command
|
|
sequence:
|
|
|
|
@example
|
|
@group
|
|
TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros
|
|
export TEXINPUTS
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This would cause @TeX{} to look for @file{\input} file first in the current
|
|
directory, indicated by the @samp{.}, then in a hypothetical user's
|
|
@file{me/mylib} directory, and finally in the system library.@refill
|
|
|
|
@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section Overfull ``hboxes''
|
|
@cindex Overfull @samp{hboxes}
|
|
@cindex @samp{hboxes}, overfull
|
|
@cindex Final output
|
|
|
|
@TeX{} is sometimes unable to typeset a line without extending it into
|
|
the right margin. This can occur when @TeX{} comes upon what it
|
|
interprets as a long word that it cannot hyphenate, such as an
|
|
electronic mail network address or a very long title. When this
|
|
happens, @TeX{} prints an error message like this:@refill
|
|
|
|
@example
|
|
Overfull \hbox (20.76302pt too wide)
|
|
@end example
|
|
|
|
@noindent
|
|
(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
|
|
The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill
|
|
|
|
@TeX{} also provides the line number in the Texinfo source file and
|
|
the text of the offending line, which is marked at all the places that
|
|
@TeX{} knows how to hyphenate words.
|
|
@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
|
|
for more information about typesetting errors.@refill
|
|
|
|
If the Texinfo file has an overfull hbox, you can rewrite the sentence
|
|
so the overfull hbox does not occur, or you can decide to leave it. A
|
|
small excursion into the right margin often does not matter and may not
|
|
even be noticeable.@refill
|
|
|
|
@cindex Black rectangle in hardcopy
|
|
@cindex Rectangle, ugly, black in hardcopy
|
|
However, unless told otherwise, @TeX{} will print a large, ugly, black
|
|
rectangle beside the line that contains the overful hbox. This is so
|
|
you will notice the location of the problem if you are correcting a
|
|
draft.@refill
|
|
|
|
@need 1000
|
|
@findex finalout
|
|
To prevent such a monstrosity from marring your final printout, write
|
|
the following in the beginning of the Texinfo file on a line of its own,
|
|
before the @code{@@titlepage} command:@refill
|
|
|
|
@example
|
|
@@finalout
|
|
@end example
|
|
|
|
@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section Printing ``Small'' Books
|
|
@findex smallbook
|
|
@cindex Small book size
|
|
@cindex Book, printing small
|
|
@cindex Page sizes for books
|
|
@cindex Size of printed book
|
|
|
|
By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
|
|
format. However, you can direct @TeX{} to typeset a document in a 7 by
|
|
9.25 inch format that is suitable for bound books by inserting the
|
|
following command on a line by itself at the beginning of the Texinfo
|
|
file, before the title page:@refill
|
|
|
|
@example
|
|
@@smallbook
|
|
@end example
|
|
|
|
@noindent
|
|
(Since regular sized books are often about 7 by 9.25 inches, this
|
|
command might better have been called the @code{@@regularbooksize}
|
|
command, but it came to be called the @code{@@smallbook} command by
|
|
comparison to the 8.5 by 11 inch format.)@refill
|
|
|
|
If you write the @code{@@smallbook} command between the
|
|
start-of-header and end-of-header lines, the Texinfo mode @TeX{}
|
|
region formatting command, @code{texinfo-tex-region}, will format the
|
|
region in ``small'' book size (@pxref{Start of Header}).@refill
|
|
|
|
The Free Software Foundation distributes printed copies of @cite{The GNU
|
|
Emacs Manual} and other manuals in the ``small'' book size.
|
|
@xref{smallexample & smalllisp, , @code{@@smallexample} and
|
|
@code{@@smalllisp}}, for information about commands that make it easier
|
|
to produce examples for a smaller manual.@refill
|
|
|
|
@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section Printing on A4 Paper
|
|
@cindex A4 paper, printing on
|
|
@cindex Paper size, European A4
|
|
@cindex European A4 paper
|
|
@findex afourpaper
|
|
|
|
You can tell @TeX{} to typeset a document for printing on European size
|
|
A4 paper with the @code{@@afourpaper} command. Write the command on a
|
|
line by itself between @code{@@iftex} and @code{@@end iftex} lines near
|
|
the beginning of the Texinfo file, before the title page:@refill
|
|
|
|
For example, this is how you would write the header for this manual:@refill
|
|
|
|
@example
|
|
@group
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@@c %**start of header
|
|
@@setfilename texinfo
|
|
@@settitle Texinfo
|
|
@@syncodeindex vr fn
|
|
@@iftex
|
|
@@afourpaper
|
|
@@end iftex
|
|
@@c %**end of header
|
|
@end group
|
|
@end example
|
|
|
|
@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy
|
|
@comment node-name, next, previous, up
|
|
@section Cropmarks and Magnification
|
|
|
|
@findex cropmarks
|
|
@cindex Cropmarks for printing
|
|
@cindex Printing cropmarks
|
|
You can attempt to direct @TeX{} to print cropmarks at the corners of
|
|
pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
|
|
command on a line by itself between @code{@@iftex} and @code{@@end
|
|
iftex} lines near the beginning of the Texinfo file, before the title
|
|
page, like this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@iftex
|
|
@@cropmarks
|
|
@@end iftex
|
|
@end group
|
|
@end example
|
|
|
|
This command is mainly for printers that typeset several pages on one
|
|
sheet of film; but you can attempt to use it to mark the corners of a
|
|
book set to 7 by 9.25 inches with the @code{@@smallbook} command.
|
|
(Printers will not produce cropmarks for regular sized output that is
|
|
printed on regular sized paper.) Since different printing machines work
|
|
in different ways, you should explore the use of this command with a
|
|
spirit of adventure. You may have to redefine the command in the
|
|
@file{texinfo.tex} definitions file.@refill
|
|
|
|
@findex mag @r{(@TeX{} command)}
|
|
@cindex Magnified printing
|
|
@cindex Larger or smaller pages
|
|
You can attempt to direct @TeX{} to typeset pages larger or smaller than
|
|
usual with the @code{\mag} @TeX{} command. Everything that is typeset
|
|
is scaled proportionally larger or smaller. (@code{\mag} stands for
|
|
``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
|
|
Plain@TeX{} command that is prefixed with a backslash. You have to
|
|
write this command between @code{@@tex} and @code{@@end tex}
|
|
(@pxref{Using Ordinary TeX Commands, , Using Ordinary @TeX{}
|
|
Commands}).@refill
|
|
|
|
Follow the @code{\mag} command with an @samp{=} and then a number that
|
|
is 1000 times the magnification you desire. For example, to print pages
|
|
at 1.2 normal size, write the following near the beginning of the
|
|
Texinfo file, before the title page:@refill
|
|
|
|
@example
|
|
@group
|
|
@@tex
|
|
\mag=1200
|
|
@@end tex
|
|
@end group
|
|
@end example
|
|
|
|
With some printing technologies, you can print normal-sized copies that
|
|
look better than usual by using a larger-than-normal master.@refill
|
|
|
|
Depending on your system, @code{\mag} may not work or may work only at
|
|
certain magnifications. Be prepared to experiment.@refill
|
|
|
|
@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Creating an Info File
|
|
@cindex Creating an Info file
|
|
@cindex Info, creating an on-line file
|
|
@cindex Formatting a file for Info
|
|
|
|
@code{makeinfo} is a utility that converts a Texinfo file into an Info
|
|
file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
|
|
GNU Emacs functions that do the same.@refill
|
|
|
|
A Texinfo file must possess an @code{@@setfilename} line near its
|
|
beginning, otherwise the Info formatting commands will fail.@refill
|
|
|
|
For information on installing the Info file in the Info system, see
|
|
@ref{Install an Info File}.@refill
|
|
|
|
@menu
|
|
* makeinfo advantages:: @code{makeinfo} provides better error checking.
|
|
* Invoking makeinfo:: How to run @code{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 @code{makeinfo} from Emacs.
|
|
* texinfo-format commands:: Two Info formatting commands written
|
|
in Emacs Lisp are an alternative
|
|
to @code{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.
|
|
@end menu
|
|
|
|
@node makeinfo advantages, Invoking makeinfo, , Create an Info File
|
|
@ifinfo
|
|
@heading @code{makeinfo} Preferred
|
|
@end ifinfo
|
|
|
|
The @code{makeinfo} utility creates an Info file from a Texinfo source
|
|
file more quickly than either of the Emacs formatting commands and
|
|
provides better error messages. We recommend it. @code{makeinfo} is a
|
|
C program that is independent of Emacs. You do not need to run Emacs to
|
|
use @code{makeinfo}, which means you can use @code{makeinfo} on machines
|
|
that are too small to run Emacs. You can run @code{makeinfo} in
|
|
any one of three ways: from an operating system shell, from a shell
|
|
inside Emacs, or by typing a key command in Texinfo mode in Emacs.
|
|
@refill
|
|
|
|
The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
|
|
commands are useful if you cannot run @code{makeinfo}. Also, in some
|
|
circumstances, they format short regions or buffers more quickly than
|
|
@code{makeinfo}.@refill
|
|
|
|
@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File
|
|
@section Invoking @code{makeinfo} from a Shell
|
|
|
|
To create an Info file from a Texinfo file, type @code{makeinfo}
|
|
followed by the name of the Texinfo file. Thus, to create the Info
|
|
file for Bison, type the following at the shell prompt (where @samp{%}
|
|
is the prompt):@refill
|
|
|
|
@example
|
|
% makeinfo bison.texinfo
|
|
@end example
|
|
|
|
(You can run a shell inside Emacs by typing @kbd{M-x
|
|
shell}.)@refill
|
|
|
|
@ifinfo
|
|
Sometimes you will want to specify options. For example, if you wish
|
|
to discover which version of @code{makeinfo} you are using,
|
|
type:@refill
|
|
|
|
@example
|
|
% makeinfo --version
|
|
@end example
|
|
|
|
@xref{makeinfo options}, for more information.
|
|
@end ifinfo
|
|
|
|
@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File
|
|
@comment node-name, next, previous, up
|
|
@section Options for @code{makeinfo}
|
|
@cindex @code{makeinfo} options
|
|
@cindex Options for @code{makeinfo}
|
|
|
|
The @code{makeinfo} command takes a number of options. Most often,
|
|
options are used to set the value of the fill column and specify the
|
|
footnote style. Each command line option is a word preceded by
|
|
@samp{--}@footnote{@samp{--} has replaced @samp{+}, the old introductory
|
|
character, to maintain POSIX.2 compatibility without losing long-named
|
|
options.} or a letter preceded by @samp{-}. You can use abbreviations
|
|
for the option names as long as they are unique.@refill
|
|
|
|
For example, you could use the following command to create an Info
|
|
file for @file{bison.texinfo} in which each line is filled to only 68
|
|
columns (where @samp{%} is the prompt):@refill
|
|
|
|
@example
|
|
% makeinfo --fill-column=68 bison.texinfo
|
|
@end example
|
|
|
|
You can write two or more options in sequence, like this:@refill
|
|
|
|
@example
|
|
% makeinfo --no-split --fill-column=70 @dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
This would keep the Info file together as one possibly very long
|
|
file and would also set the fill column to 70.@refill
|
|
|
|
@iftex
|
|
If you wish to discover which version of @code{makeinfo}
|
|
you are using, type:@refill
|
|
|
|
@example
|
|
% makeinfo --version
|
|
@end example
|
|
@end iftex
|
|
|
|
The options are:@refill
|
|
|
|
@need 100
|
|
@table @code
|
|
@item -D @var{var}
|
|
Cause @var{var} to be defined. This is equivalent to
|
|
@code{@@set @var{var}} in the Texinfo file.
|
|
|
|
@need 150
|
|
@item --error-limit @var{limit}
|
|
Set the maximum number of errors that @code{makeinfo} will report
|
|
before exiting (on the assumption that continuing would be useless).
|
|
The default number of errors that can be reported before
|
|
@code{makeinfo} gives up is 100.@refill
|
|
|
|
@need 150
|
|
@item --fill-column @var{width}
|
|
Specify the maximum number of columns in a line; this is the right-hand
|
|
edge of a line. Paragraphs that are filled will be filled to this
|
|
width. (Filling is the process of breaking up and connecting lines so
|
|
that lines are the same length as or shorter than the number specified
|
|
as the fill column. Lines are broken between words.) The default value
|
|
for @code{fill-column} is 72.
|
|
@refill
|
|
|
|
@item --footnote-style @var{style}
|
|
Set the footnote style to @var{style}, either @samp{end} for the end
|
|
node style or @samp{separate} for the separate node style. The value
|
|
set by this option overrides the value set in a Texinfo file by an
|
|
@code{@@footnotestyle} command. When the footnote style is
|
|
@samp{separate}, @code{makeinfo} makes a new node containing the
|
|
footnotes found in the current node. When the footnote style is
|
|
@samp{end}, @code{makeinfo} places the footnote references at the end
|
|
of the current node.@refill
|
|
|
|
@need 150
|
|
@item -I @var{dir}
|
|
Add @code{dir} to the directory search list for finding files that are
|
|
included using the @code{@@include} command. By default,
|
|
@code{makeinfo} searches only the current directory.
|
|
|
|
@need 150
|
|
@item --no-headers
|
|
Do not include menus or node lines in the output. This results in an
|
|
@sc{ascii} file that you cannot read in Info since it does not contain
|
|
the requisite nodes or menus; but you can print such a file in a
|
|
single, typewriter-like font and produce acceptable output.
|
|
|
|
@need 150
|
|
@item --no-split
|
|
Suppress the splitting stage of @code{makeinfo}. Normally, large
|
|
output files (where the size is greater than 70k bytes) are split into
|
|
smaller subfiles, each one approximately 50k bytes. If you specify
|
|
@samp{--no-split}, @code{makeinfo} will not split up the output
|
|
file.@refill
|
|
|
|
@need 100
|
|
@item --no-pointer-validate
|
|
@item --no-validate
|
|
Suppress the pointer-validation phase of @code{makeinfo}. Normally,
|
|
after a Texinfo file is processed, some consistency checks are made to
|
|
ensure that cross references can be resolved, etc.
|
|
@xref{Pointer Validation}.@refill
|
|
|
|
@need 150
|
|
@item --no-warn
|
|
Suppress the output of warning messages. This does @emph{not}
|
|
suppress the output of error messages, only warnings. You might
|
|
want this if the file you are creating has examples of Texinfo cross
|
|
references within it, and the nodes that are referenced do not actually
|
|
exist.@refill
|
|
|
|
@item --no-number-footnotes
|
|
Supress automatic footnote numbering. By default, @code{makeinfo}
|
|
numbers each footnote sequentially in a single node, resetting the
|
|
current footnote number to 1 at the start of each node.
|
|
|
|
@need 150
|
|
@item --output @var{file}
|
|
@itemx -o @var{file}
|
|
Specify that the output should be directed to @var{file} and not to the
|
|
file name specified in the @code{@@setfilename} command found in the Texinfo
|
|
source. @var{file} can be the special token @samp{-}, which specifies
|
|
standard output.
|
|
|
|
@need 150
|
|
@item --paragraph-indent @var{indent}
|
|
Set the paragraph indentation style to @var{indent}. The value set by
|
|
this option overrides the value set in a Texinfo file by an
|
|
@code{@@paragraphindent} command. The value of @var{indent} is
|
|
interpreted as follows:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If the value of @var{indent} is @samp{asis}, do not change the
|
|
existing indentation at the starts of paragraphs.@refill
|
|
|
|
@item
|
|
If the value of @var{indent} is zero, delete any existing
|
|
indentation.@refill
|
|
|
|
@item
|
|
If the value of @var{indent} is greater than zero, indent each
|
|
paragraph by that number of spaces.@refill
|
|
@end itemize
|
|
|
|
@need 100
|
|
@item --reference-limit @var{limit}
|
|
Set the value of the number of references to a node that
|
|
@code{makeinfo} will make without reporting a warning. If a node has more
|
|
than this number of references in it, @code{makeinfo} will make the
|
|
references but also report a warning.@refill
|
|
|
|
@need 150
|
|
@item -U @var{var}
|
|
Cause @var{var} to be undefined. This is equivalent to
|
|
@code{@@clear @var{var}} in the Texinfo file.
|
|
|
|
@need 100
|
|
@item --verbose
|
|
Cause @code{makeinfo} to display messages saying what it is doing.
|
|
Normally, @code{makeinfo} only outputs messages if there are errors or
|
|
warnings.@refill
|
|
|
|
@need 100
|
|
@item --version
|
|
Report the version number of this copy of @code{makeinfo}.@refill
|
|
@end table
|
|
|
|
@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File
|
|
@section Pointer Validation
|
|
@cindex Pointer validation with @code{makeinfo}
|
|
@cindex Validation of pointers
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
@code{makeinfo} will check the validity of the final Info file unless
|
|
you suppress pointer-validation by using the
|
|
@samp{--no-pointer-validation} option. Mostly, this means ensuring
|
|
that nodes you have referenced really exist. Here is a complete list
|
|
of what is checked:@refill
|
|
|
|
@enumerate
|
|
@item
|
|
If a `Next', `Previous', or `Up' node reference is a reference to a
|
|
node in the current file and is not an external reference such as to
|
|
@file{(dir)}, then the referenced node must exist.@refill
|
|
|
|
@item
|
|
In every node, if the `Previous' node is different from the `Up' node,
|
|
then the `Previous' node must also be pointed to by a `Next' node.@refill
|
|
|
|
@item
|
|
Every node except the `Top' node must have an `Up' pointer.@refill
|
|
|
|
@item
|
|
The node referenced by an `Up' pointer must contain a reference to the
|
|
current node in some manner other than through a `Next' reference.
|
|
This includes menu entries and cross references.@refill
|
|
|
|
@item
|
|
If the `Next' reference of a node is not the same as the `Next' reference
|
|
of the `Up' reference, then the node referenced by the `Next' pointer
|
|
must have a `Previous' pointer that points back to the current node.
|
|
This rule allows the last node in a section to point to the first node
|
|
of the next chapter.@refill
|
|
@end enumerate
|
|
|
|
@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File
|
|
@section Running @code{makeinfo} inside Emacs
|
|
@cindex Running @code{makeinfo} in Emacs
|
|
@cindex @code{makeinfo} inside Emacs
|
|
@cindex Shell, running @code{makeinfo} in
|
|
|
|
You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
|
|
@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
|
|
Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
|
|
C-m C-b} by default.@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-m C-r
|
|
@itemx M-x makeinfo-region
|
|
Format the current region for Info.@refill
|
|
@findex makeinfo-region
|
|
|
|
@item C-c C-m C-b
|
|
@itemx M-x makeinfo-buffer
|
|
Format the current buffer for Info.@refill
|
|
@findex makeinfo-buffer
|
|
@end table
|
|
|
|
When you invoke either @code{makeinfo-region} or
|
|
@code{makeinfo-buffer}, Emacs prompts for a file name, offering the
|
|
name of the visited file as the default. You can edit the default
|
|
file name in the minibuffer if you wish, before typing @key{RET} to
|
|
start the @code{makeinfo} process.@refill
|
|
|
|
The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
|
|
run the @code{makeinfo} program in a temporary shell buffer. If
|
|
@code{makeinfo} finds any errors, Emacs displays the error messages in
|
|
the temporary buffer.@refill
|
|
|
|
@cindex Errors, parsing
|
|
@cindex Parsing errors
|
|
@findex next-error
|
|
You can parse the error messages by typing @kbd{C-x `}
|
|
(@code{next-error}). This causes Emacs to go to and position the
|
|
cursor on the line in the Texinfo source that @code{makeinfo} thinks
|
|
caused the error. @xref{Compilation, , Running @code{make} or
|
|
Compilers Generally, emacs, The GNU Emacs Manual}, for more
|
|
information about using the @code{next-error} command.@refill
|
|
|
|
In addition, you can kill the shell in which the @code{makeinfo}
|
|
command is running or make the shell buffer display its most recent
|
|
output.@refill
|
|
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
@table @kbd
|
|
@item C-c C-m C-k
|
|
@itemx M-x makeinfo-kill-job
|
|
@findex makeinfo-kill-job
|
|
Kill the currently running job created by
|
|
@code{makeinfo-region} or @code{makeinfo-buffer}.@refill
|
|
|
|
@item C-c C-m C-l
|
|
@itemx M-x makeinfo-recenter-output-buffer
|
|
@findex makeinfo-recenter-output-buffer
|
|
Redisplay the @code{makeinfo} shell buffer to display its most recent
|
|
output.@refill
|
|
@end table
|
|
|
|
@noindent
|
|
(Note that the parallel commands for killing and recentering a @TeX{}
|
|
job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
|
|
Printing}.)@refill
|
|
|
|
You can specify options for @code{makeinfo} by setting the
|
|
@code{makeinfo-options} variable with either the @kbd{M-x
|
|
edit-options} or the @kbd{M-x set-variable} command, or by setting the
|
|
variable in your @file{.emacs} initialization file.@refill
|
|
|
|
For example, you could write the following in your @file{.emacs} file:@refill
|
|
|
|
@example
|
|
@group
|
|
(setq makeinfo-options
|
|
"--paragraph-indent=0 --no-split
|
|
--fill-column=70 --verbose")
|
|
@end group
|
|
@end example
|
|
|
|
@c If you write these three cross references using xref, you see
|
|
@c three references to the same named manual, which looks strange.
|
|
@iftex
|
|
For more information, see @ref{makeinfo options, , Options for
|
|
@code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and
|
|
Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs
|
|
Manual}.
|
|
@end iftex
|
|
@noindent
|
|
@ifinfo
|
|
For more information, see@*
|
|
@ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
|
|
@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
|
|
@ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
|
|
@ref{makeinfo options, , Options for @code{makeinfo}}.
|
|
@end ifinfo
|
|
|
|
@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File
|
|
@comment node-name, next, previous, up
|
|
@section The @code{texinfo-format@dots{}} Commands
|
|
@findex texinfo-format-region
|
|
@findex texinfo-format-buffer
|
|
|
|
In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
|
|
file with the @code{texinfo-format-region} command. This formats the
|
|
current region and displays the formatted text in a temporary buffer
|
|
called @samp{*Info Region*}.@refill
|
|
|
|
Similarly, you can format a buffer with the
|
|
@code{texinfo-format-buffer} command. This command creates a new
|
|
buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
|
|
save the Info file under the name specified by the
|
|
@code{@@setfilename} line which must be near the beginning of the
|
|
Texinfo file.@refill
|
|
|
|
@table @kbd
|
|
@item C-c C-e C-r
|
|
@itemx @code{texinfo-format-region}
|
|
Format the current region for Info.
|
|
@findex texinfo-format-region
|
|
|
|
@item C-c C-e C-b
|
|
@itemx @code{texinfo-format-buffer}
|
|
Format the current buffer for Info.
|
|
@findex texinfo-format-buffer
|
|
@end table
|
|
|
|
The @code{texinfo-format-region} and @code{texinfo-format-buffer}
|
|
commands provide you with some error checking, and other functions can
|
|
provide you with further help in finding formatting errors. These
|
|
procedures are described in an appendix; see @ref{Catching Mistakes}.
|
|
However, the @code{makeinfo} program is often faster and
|
|
provides better error checking (@pxref{makeinfo in Emacs}).@refill
|
|
|
|
@node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File
|
|
@comment node-name, next, previous, up
|
|
@section Batch Formatting
|
|
@cindex Batch formatting for Info
|
|
@cindex Info batch formatting
|
|
|
|
You can format Texinfo files for Info using @code{batch-texinfo-format}
|
|
and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
|
|
including a shell inside of Emacs. (@xref{Command Switches, , Command
|
|
Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
|
|
|
|
Here is the command to format all the files that end in @file{.texinfo}
|
|
in the current directory (where @samp{%} is the shell prompt):@refill
|
|
|
|
@example
|
|
% emacs -batch -funcall batch-texinfo-format *.texinfo
|
|
@end example
|
|
|
|
@noindent
|
|
Emacs processes all the files listed on the command line, even if an
|
|
error occurs while attempting to format some of them.@refill
|
|
|
|
Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
|
|
it is not interactive. It kills the Batch mode Emacs on completion.@refill
|
|
|
|
@code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
|
|
and want to format several Texinfo files at once. When you use Batch
|
|
mode, you create a new Emacs process. This frees your current Emacs, so
|
|
you can continue working in it. (When you run
|
|
@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
|
|
use that Emacs for anything else until the command finishes.)@refill
|
|
|
|
@node Tag and Split Files, , Batch Formatting, Create an Info File
|
|
@comment node-name, next, previous, up
|
|
@section Tag Files and Split Files
|
|
@cindex Making a tag table automatically
|
|
@cindex Tag table, making automatically
|
|
|
|
If a Texinfo file has more than 30,000 bytes,
|
|
@code{texinfo-format-buffer} automatically creates a tag table
|
|
for its Info file; @code{makeinfo} always creates a tag table. With
|
|
a @dfn{tag table}, Info can jump to new nodes more quickly than it can
|
|
otherwise.@refill
|
|
|
|
@cindex Indirect subfiles
|
|
In addition, if the Texinfo file contains more than about 70,000
|
|
bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
|
|
large Info file into shorter @dfn{indirect} subfiles of about 50,000
|
|
bytes each. Big files are split into smaller files so that Emacs does
|
|
not need to make a large buffer to hold the whole of a large Info
|
|
file; instead, Emacs allocates just enough memory for the small, split
|
|
off file that is needed at the time. This way, Emacs avoids wasting
|
|
memory when you run Info. (Before splitting was implemented, Info
|
|
files were always kept short and @dfn{include files} were designed as
|
|
a way to create a single, large printed manual out of the smaller Info
|
|
files. @xref{Include Files}, for more information. Include files are
|
|
still used for very large documents, such as @cite{The Emacs Lisp
|
|
Reference Manual}, in which each chapter is a separate file.)@refill
|
|
|
|
When a file is split, Info itself makes use of a shortened version of
|
|
the original file that contains just the tag table and references to
|
|
the files that were split off. The split off files are called
|
|
@dfn{indirect} files.@refill
|
|
|
|
The split off files have names that are created by appending @w{@samp{-1}},
|
|
@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
|
|
@code{@@setfilename} command. The shortened version of the original file
|
|
continues to have the name specified by @code{@@setfilename}.@refill
|
|
|
|
At one stage in writing this document, for example, the Info file was saved
|
|
as @file{test-texinfo} and that file looked like this:@refill
|
|
|
|
@example
|
|
@group
|
|
Info file: test-texinfo, -*-Text-*-
|
|
produced by texinfo-format-buffer
|
|
from file: new-texinfo-manual.texinfo
|
|
|
|
^_
|
|
Indirect:
|
|
test-texinfo-1: 102
|
|
test-texinfo-2: 50422
|
|
test-texinfo-3: 101300
|
|
^_^L
|
|
Tag table:
|
|
(Indirect)
|
|
Node: overview^?104
|
|
Node: info file^?1271
|
|
Node: printed manual^?4853
|
|
Node: conventions^?6855
|
|
@dots{}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(But @file{test-texinfo} had far more nodes than are shown here.) Each of
|
|
the split off, indirect files, @file{test-texinfo-1},
|
|
@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
|
|
after the line that says @samp{Indirect:}. The tag table is listed after
|
|
the line that says @samp{Tag table:}. @refill
|
|
|
|
In the list of indirect files, the number following the file name
|
|
records the cumulative number of bytes in the preceding indirect files,
|
|
not counting the file list itself, the tag table, or the permissions
|
|
text in each file. In the tag table, the number following the node name
|
|
records the location of the beginning of the node, in bytes from the
|
|
beginning.@refill
|
|
|
|
If you are using @code{texinfo-format-buffer} to create Info files,
|
|
you may want to run the @code{Info-validate} command. (The
|
|
@code{makeinfo} command does such a good job on its own, you do not
|
|
need @code{Info-validate}.) However, you cannot run the @kbd{M-x
|
|
Info-validate} node-checking command on indirect files. For
|
|
information on how to prevent files from being split and how to
|
|
validate the structure of the nodes, see @ref{Using
|
|
Info-validate}.@refill
|
|
|
|
@node Install an Info File, Command List, Create an Info File, Top
|
|
@comment node-name, next, previous, up
|
|
@chapter Installing an Info File
|
|
@cindex Installing an Info file
|
|
@cindex Info file installation
|
|
@cindex @file{dir} directory for Info installation
|
|
|
|
Info files are usually kept in the @file{info}
|
|
directory. (You can find the location of this directory within Emacs
|
|
by typing @kbd{C-h i} to enter Info and then typing @kbd{C-x C-f} to
|
|
see the full pathname to the @file{info} directory.)
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Directory file, New Info File, , Install an Info File
|
|
@ifinfo
|
|
@heading The @file{dir} File
|
|
@end ifinfo
|
|
|
|
For Info to work, the @file{info} directory must contain a file that
|
|
serves as a top level directory for the Info system. By convention,
|
|
this file is called @file{dir}. The @file{dir} file is itself an Info
|
|
file. It contains the top level menu for all the Info files in the
|
|
system. The menu looks like this:@refill
|
|
|
|
@example
|
|
* Menu:
|
|
|
|
* Info: (info). Documentation browsing system.
|
|
* Emacs: (emacs). The extensible, self-documenting
|
|
text editor.
|
|
* Texinfo: (texinfo). With one source file, make
|
|
either a printed manual using
|
|
TeX or an Info file.
|
|
@dots{}
|
|
@end example
|
|
|
|
Each of these menu entries points to the `Top' node of the Info file
|
|
that is named in parentheses. (The menu entry does not need to
|
|
specify the `Top' node, since Info goes to the `Top' node if no node
|
|
name is mentioned. @xref{Other Info Files, , Nodes in Other Info
|
|
Files}.)@refill
|
|
|
|
Thus, the @samp{Info} entry points to the `Top' node of the
|
|
@file{info} file and the @samp{Emacs} entry points to the `Top' node
|
|
of the @file{emacs} file.@refill
|
|
|
|
In each of the Info files, the `Up' pointer of the `Top' node refers
|
|
back to the @code{dir} file. For example, the line for the `Top'
|
|
node of the Emacs manual looks like this in Info:@refill
|
|
|
|
@example
|
|
File: emacs Node: Top, Up: (DIR), Next: Distrib
|
|
@end example
|
|
|
|
@noindent
|
|
(Note that in this case, the @file{dir} file name is written in upper
|
|
case letters---it can be written in either upper or lower case. Info
|
|
has a feature that it will change the case of the file name to lower
|
|
case if it cannot find the name as written.)@refill
|
|
|
|
@c !!! Can any file name be written in upper or lower case,
|
|
@c or is dir a special case?
|
|
@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92
|
|
@c
|
|
@node New Info File, Other Info Directories, Directory file, Install an Info File
|
|
@section Listing a New Info File
|
|
@cindex Adding a new info file
|
|
@cindex Listing a new info file
|
|
@cindex New info file, listing it in @file{dir} file
|
|
@cindex Info file, listing new one
|
|
@cindex @file{dir} file listing
|
|
|
|
To add a new Info file to your system, write a menu entry for it in the
|
|
menu in the @file{dir} file in the @file{info} directory. Also, move
|
|
the new Info file itself to the @file{info} directory. For example, if
|
|
you were adding documentation for GDB, you would write the following new
|
|
entry:@refill
|
|
|
|
@example
|
|
* GDB: (gdb). The source-level C debugger.
|
|
@end example
|
|
|
|
@noindent
|
|
The first part of the menu entry is the menu entry name, followed by a
|
|
colon. The second part is the name of the Info file, in parentheses,
|
|
followed by a period. The third part is the description.@refill
|
|
|
|
Conventionally, the name of an Info file has a @file{.info} extension.
|
|
Thus, you might list the name of the file like this:
|
|
|
|
@example
|
|
* GDB: (gdb.info). The source-level C debugger.
|
|
@end example
|
|
|
|
@noindent
|
|
However, Info will look for a file with a @file{.info} extension if it
|
|
does not find the file under the name given in the menu. This means
|
|
that you can refer to the file @file{gdb.info} as @file{gdb}, as shown
|
|
in the first example. This looks better.
|
|
|
|
@node Other Info Directories, , New Info File, Install an Info File
|
|
@comment node-name, next, previous, up
|
|
@section Info Files in Other Directories
|
|
@cindex Installing Info in another directory
|
|
@cindex Info installed in another directory
|
|
@cindex Another Info directory
|
|
|
|
If an Info file is not in the @file{info} directory, there are two
|
|
ways to specify its location:@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Write the pathname as the menu's second part, or;@refill
|
|
|
|
@item
|
|
Specify the @file{info} directory name in an environment variable in
|
|
your @file{.profile} or @file{.cshrc} initialization file. (Only you
|
|
and others with the same environment variable will be able to find Info
|
|
files whose location is specified this way.)@refill
|
|
@end itemize
|
|
|
|
For example, to reach a test file in the @file{~bob/manuals}
|
|
directory, you could add an entry like this to the menu in the
|
|
@file{dir} file:@refill
|
|
|
|
@example
|
|
* Test: (~bob/manuals/info-test). Bob's own test file.
|
|
@end example
|
|
|
|
@noindent
|
|
In this case, the absolute file name of the @file{info-test} file is
|
|
written as the second part of the menu entry.@refill
|
|
|
|
@vindex INFOPATH
|
|
Alternatively, you can tell Info where to look by setting the
|
|
@code{INFOPATH} environment variable in your @file{.cshrc} or
|
|
@file{.profile} file.@refill
|
|
|
|
If you use @code{sh} or @code{bash} for your shell command interpreter,
|
|
you must set the @code{INFOPATH} environment variable in the
|
|
@file{.profile} initialization file; but if you use @code{csh}, you must
|
|
set the variable in the @file{.cshrc} initialization file. The two
|
|
files require slightly different command formats.@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
In a @file{.cshrc} file, you could set the @code{INFOPATH}
|
|
variable as follows:@refill
|
|
|
|
@smallexample
|
|
setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info
|
|
@end smallexample
|
|
|
|
@item
|
|
In a @file{.profile} file, you would achieve the same effect by
|
|
writing:@refill
|
|
|
|
@smallexample
|
|
INFOPATH=.:~bob/manuals:/usr/local/emacs/info
|
|
export INFOPATH
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@noindent
|
|
Either form would cause Info to look first in the current directory,
|
|
indicated by the @samp{.}, then in the @file{~bob/manuals} directory,
|
|
and finally in the @file{/usr/local/emacs/info} directory (which is
|
|
a common location for the standard Info directory).@refill
|
|
|
|
@c ================ Appendix starts here ================
|
|
|
|
@node Command List, Tips, Install an Info File, Top
|
|
@appendix @@-Command List
|
|
@cindex Alphabetical @@-command list
|
|
@cindex List of @@-commands
|
|
@cindex @@-command list
|
|
|
|
Here is an alphabetical list of the @@-commands in Texinfo. Square
|
|
brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
|
|
@samp{@dots{}}, indicates repeated text.@refill
|
|
|
|
@sp 1
|
|
@table @code
|
|
@item @@*
|
|
Force a line break. Do not end a paragraph that uses @code{@@*} with
|
|
an @code{@@refill} command. @xref{Line Breaks}.@refill
|
|
|
|
@item @@.
|
|
Stands for a period that really does end a sentence (usually after an
|
|
end-of-sentence capital letter). @xref{Controlling Spacing}.@refill
|
|
|
|
@item @@:
|
|
Indicate to @TeX{} that an immediately preceding period, question
|
|
mark, exclamation mark, or colon does not end a sentence. Prevent
|
|
@TeX{} from inserting extra whitespace as it does at the end of a
|
|
sentence. The command has no effect on the Info file output.
|
|
@xref{Controlling Spacing}.@refill
|
|
|
|
@item @@@@
|
|
Stands for @samp{@@}. @xref{Braces Atsigns Periods, , Inserting
|
|
@samp{@@}}.@refill
|
|
|
|
@item @@@{
|
|
Stands for a left-hand brace, @samp{@{}.
|
|
@xref{Braces Atsigns Periods, , Inserting @@ braces and periods}.@refill
|
|
|
|
@item @@@}
|
|
Stands for a right-hand brace, @samp{@}}.
|
|
@xref{Braces Atsigns Periods, , Inserting @@ braces and periods}.@refill
|
|
|
|
@item @@appendix @var{title}
|
|
Begin an appendix. The title appears in the table
|
|
of contents of a printed manual. In Info, the title is
|
|
underlined with asterisks. @xref{unnumbered & appendix, , The
|
|
@code{@@unnumbered} and @code{@@appendix} Commands}.@refill
|
|
|
|
@item @@appendixsec @var{title}
|
|
@itemx @@appendixsection @var{title}
|
|
Begin an appendix section within an appendix. The section title appears
|
|
in the table of contents of a printed manual. In Info, the title is
|
|
underlined with equal signs. @code{@@appendixsection} is a longer
|
|
spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
|
|
appendixsec heading, , Section Commands}.@refill
|
|
|
|
@item @@appendixsubsec @var{title}
|
|
Begin an appendix subsection within an appendix. The title appears
|
|
in the table of contents of a printed manual. In Info, the title is
|
|
underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
|
|
subheading, , Subsection Commands}.@refill
|
|
|
|
@item @@appendixsubsubsec @var{title}
|
|
Begin an appendix subsubsection within a subappendix. The title
|
|
appears in the table of contents of a printed manual. In Info, the
|
|
title is underlined with periods. @xref{subsubsection,, The `subsub'
|
|
Commands}.@refill
|
|
|
|
@item @@asis
|
|
Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
|
|
print the table's first column without highlighting (``as is'').
|
|
@xref{Two-column Tables, , Making a Two-column Table}.@refill
|
|
|
|
@item @@author @var{author}
|
|
Typeset @var{author} flushleft and underline it. @xref{title
|
|
subtitle author, , The @code{@@title} and @code{@@author}
|
|
Commands}.@refill
|
|
|
|
@item @@b@{@var{text}@}
|
|
Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill
|
|
|
|
@ignore
|
|
@item @@br
|
|
Force a paragraph break. If used within a line, follow @code{@@br}
|
|
with braces. @xref{br, , @code{@@br}}.@refill
|
|
@end ignore
|
|
|
|
@item @@bullet@{@}
|
|
Generate a large round dot, or the closest possible
|
|
thing to one. @xref{bullet, , @code{@@bullet}}.@refill
|
|
|
|
@item @@bye
|
|
Stop formatting a file. The formatters do not see the contents of a
|
|
file following an @code{@@bye} command. @xref{Ending a File}.@refill
|
|
|
|
@item @@c @var{comment}
|
|
Begin a comment in Texinfo. The rest of the line does not appear in
|
|
either the Info file or the printed manual. A synonym for
|
|
@code{@@comment}. @xref{Conventions, , General Syntactic
|
|
Conventions}.@refill
|
|
|
|
@item @@cartouche
|
|
Highlight an example or quotation by drawing a box with rounded
|
|
corners around it. Pair with @code{@@end cartouche}. No effect in
|
|
Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
|
|
|
|
@item @@center @var{line-of-text}
|
|
Center the line of text following the command.
|
|
@xref{titlefont center sp, , @code{@@center}}.@refill
|
|
|
|
@item @@chapheading @var{title}
|
|
Print a chapter-like heading in the text, but not in the table of
|
|
contents of a printed manual. In Info, the title is underlined with
|
|
asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
|
|
and @code{@@chapheading}}.@refill
|
|
|
|
@item @@chapter @var{title}
|
|
Begin a chapter. The chapter title appears in the table of
|
|
contents of a printed manual. In Info, the title is underlined with
|
|
asterisks. @xref{chapter, , @code{@@chapter}}.@refill
|
|
|
|
@item @@cindex @var{entry}
|
|
Add @var{entry} to the index of concepts. @xref{Index Entries, ,
|
|
Defining the Entries of an Index}.@refill
|
|
|
|
@item @@cite@{@var{reference}@}
|
|
Highlight the name of a book or other reference that lacks a
|
|
companion Info file. @xref{cite, , @code{@@cite}}.@refill
|
|
|
|
@item @@clear @var{flag}
|
|
Unset @var{flag}, preventing the Texinfo formatting commands from
|
|
formatting text between subsequent pairs of @code{@@ifset @var{flag}}
|
|
and @code{@@end ifset} commands, and preventing
|
|
@code{@@value@{@var{flag}@}} from expanding to the value to which
|
|
@var{flag} is set.
|
|
@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
|
|
|
|
@item @@code@{@var{sample-code}@}
|
|
Highlight text that is an expression, a syntactically complete token
|
|
of a program, or a program name. @xref{code, , @code{@@code}}.@refill
|
|
|
|
@item @@comment @var{comment}
|
|
Begin a comment in Texinfo. The rest of the line does not appear in
|
|
either the Info file or the printed manual. A synonym for @code{@@c}.
|
|
@xref{Conventions, , General Syntactic Conventions}.@refill
|
|
|
|
@item @@contents
|
|
Print a complete table of contents. Has no effect in Info, which uses
|
|
menus instead. @xref{Contents, , Generating a Table of
|
|
Contents}.@refill
|
|
|
|
@item @@copyright@{@}
|
|
Generate a copyright symbol. @xref{copyright symbol, ,
|
|
@code{@@copyright}}.@refill
|
|
|
|
@ignore
|
|
@item @@ctrl@{@var{ctrl-char}@}
|
|
Describe an @sc{ascii} control character. Insert actual control character
|
|
into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
|
|
@end ignore
|
|
|
|
@item @@defcodeindex @var{index-name}
|
|
Define a new index and its indexing command. Print entries in an
|
|
@code{@@code} font. @xref{New Indices, , Defining New
|
|
Indices}.@refill
|
|
|
|
@item @@defcv @var{category} @var{class} @var{name}
|
|
Format a description for a variable associated with a class in
|
|
object-oriented programming. Takes three arguments: the category of
|
|
thing being defined, the class to which it belongs, and its name.
|
|
@xref{Definition Commands}.@refill
|
|
|
|
@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
|
|
Format a description for a function, interactive command, or similar
|
|
entity that may take arguments. @code{@@deffn} takes as arguments the
|
|
category of entity being described, the name of this particular
|
|
entity, and its arguments, if any. @xref{Definition Commands}.@refill
|
|
|
|
@item @@defindex @var{index-name}
|
|
Define a new index and its indexing command. Print entries in a roman
|
|
font. @xref{New Indices, , Defining New Indices}.@refill
|
|
|
|
@item @@defivar @var{class} @var{instance-variable-name}
|
|
Format a description for an instance variable in object-oriented
|
|
programming. The command is equivalent to @samp{@@defcv @{Instance
|
|
Variable@} @dots{}}. @xref{Definition Commands}.@refill
|
|
|
|
@item @@defmac @var{macro-name} @var{arguments}@dots{}
|
|
Format a description for a macro. The command is equivalent to
|
|
@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}.@refill
|
|
|
|
@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
|
|
Format a description for a method in object-oriented programming. The
|
|
command is equivalent to @samp{@@defop Method @dots{}}. Takes as
|
|
arguments the name of the class of the method, the name of the
|
|
method, and its arguments, if any. @xref{Definition Commands}.@refill
|
|
|
|
@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
|
|
Format a description for an operation in object-oriented programming.
|
|
@code{@@defop} takes as arguments the overall name of the category of
|
|
operation, the name of the class of the operation, the name of the
|
|
operation, and its arguments, if any. @xref{Definition
|
|
Commands}.@refill
|
|
|
|
@need 100
|
|
@item @@defopt @var{option-name}
|
|
Format a description for a user option. The command is equivalent to
|
|
@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}.@refill
|
|
|
|
@need 100
|
|
@item @@defspec @var{special-form-name} @var{arguments}@dots{}
|
|
Format a description for a special form. The command is equivalent to
|
|
@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}.@refill
|
|
|
|
@need 200
|
|
@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
|
|
Format a description for a data type. @code{@@deftp} takes as
|
|
arguments the category, the name of the type (which is a word like
|
|
@samp{int} or @samp{float}), and then the names of attributes of
|
|
objects of that
|
|
type. @xref{Definition Commands}.@refill
|
|
|
|
@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
|
|
Format a description for a function or similar entity that may take
|
|
arguments and that is typed. @code{@@deftypefn} takes as arguments
|
|
the classification of entity being described, the type, the name of
|
|
the entity, and its arguments, if any. @xref{Definition
|
|
Commands}.@refill
|
|
|
|
@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
|
|
Format a description for a function in a typed language.
|
|
The command is equivalent to @samp{@@deftypefn Function @dots{}}.
|
|
@xref{Definition Commands}.@refill
|
|
|
|
@item @@deftypevr @var{classification} @var{data-type} @var{name}
|
|
Format a description for something like a variable in a typed
|
|
language---an entity that records a value. Takes as arguments the
|
|
classification of entity being described, the type, and the name of
|
|
the entity. @xref{Definition Commands}.@refill
|
|
|
|
@item @@deftypevar @var{data-type} @var{variable-name}
|
|
Format a description for a variable in a typed language. The command is
|
|
equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
|
|
Commands}.@refill
|
|
|
|
@item @@defun @var{function-name} @var{arguments}@dots{}
|
|
Format a description for functions. The command is equivalent to
|
|
@samp{@@deffn Function @dots{}}. @xref{Definition Commands}.@refill
|
|
|
|
@item @@defvar @var{variable-name}
|
|
Format a description for variables. The command is equivalent to
|
|
@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}.@refill
|
|
|
|
@item @@defvr @var{category} @var{name}
|
|
Format a description for any kind of variable. @code{@@defvr} takes
|
|
as arguments the category of the entity and the name of the entity.
|
|
@xref{Definition Commands}.@refill
|
|
|
|
@item @@dfn@{@var{term}@}
|
|
Highlight the introductory or defining use of a term.
|
|
@xref{dfn, , @code{@@dfn}}.@refill
|
|
|
|
@need 100
|
|
@item @@display
|
|
Begin a kind of example. Indent text, do not fill, do not select a
|
|
new font. Pair with @code{@@end display}. @xref{display, ,
|
|
@code{@@display}}.@refill
|
|
|
|
@need 100
|
|
@item @@dmn@{@var{dimension}@}
|
|
Format a dimension. Cause @TeX{} to insert a narrow space before
|
|
@var{dimension}. No effect in Info. Use for writing a number
|
|
followed by an abbreviation of a dimension name, such as
|
|
@samp{12@dmn{pt}}, written as @samp{12@@dmn@{pt@}}, with no space
|
|
between the number and the @code{@@dmn} command. @xref{dmn, ,
|
|
@code{@@dmn}}.@refill
|
|
|
|
@need 100
|
|
@item @@dots@{@}
|
|
Insert an ellipsis: @samp{@dots{}}.
|
|
@xref{dots, , @code{@@dots}}.@refill
|
|
|
|
@need 100
|
|
@item @@emph@{@var{text}@}
|
|
Highlight @var{text}; text is displayed in @emph{italics} in printed
|
|
output, and surrounded by asterisks in Info. @xref{Emphasis, , Emphasizing Text}.@refill
|
|
|
|
@need 100
|
|
@item @@enumerate [@var{number-or-letter}]
|
|
Begin a numbered list, using @code{@@item} for each entry.
|
|
Optionally, start list with @var{number-or-letter}. Pair with
|
|
@code{@@end enumerate}. @xref{enumerate, ,
|
|
@code{@@enumerate}}.@refill
|
|
|
|
@need 100
|
|
@item @@equiv@{@}
|
|
Indicate to the reader the exact equivalence of two forms with a
|
|
glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
|
|
|
|
@item @@error@{@}
|
|
Indicate to the reader with a glyph that the following text is
|
|
an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
|
|
|
|
@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
|
|
Specify page footings for even-numbered (left-hand) pages. Not relevant to
|
|
Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
|
|
Specify page headings for even-numbered (left-hand) pages. Not relevant to
|
|
Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
|
|
Specify page footings for every page. Not relevant to Info. @xref{Custom
|
|
Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
|
|
Specify page headings for every page. Not relevant to Info. @xref{Custom
|
|
Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@example
|
|
Begin an example. Indent text, do not fill, and select fixed-width font.
|
|
Pair with @code{@@end example}. @xref{example, ,
|
|
@code{@@example}}.@refill
|
|
|
|
@item @@exdent @var{line-of-text}
|
|
Remove any indentation a line might have. @xref{exdent, ,
|
|
Undoing the Indentation of a Line}.@refill
|
|
|
|
@item @@expansion@{@}
|
|
Indicate the result of a macro expansion to the reader with a special
|
|
glyph: @samp{@expansion{}}.
|
|
@xref{expansion, , @expansion{} Indicating an Expansion}.@refill
|
|
|
|
@item @@file@{@var{filename}@}
|
|
Highlight the name of a file, buffer, node, or directory. @xref{file, ,
|
|
@code{@@file}}.@refill
|
|
|
|
@item @@finalout
|
|
Prevent @TeX{} from printing large black warning rectangles beside
|
|
over-wide lines. @xref{Overfull hboxes}.@refill
|
|
|
|
@need 100
|
|
@item @@findex @var{entry}
|
|
Add @var{entry} to the index of functions. @xref{Index Entries, ,
|
|
Defining the Entries of an Index}.@refill
|
|
|
|
@need 200
|
|
@item @@flushleft
|
|
Left justify every line but leave the right end ragged.
|
|
Leave font as is. Pair with @code{@@end flushleft}.
|
|
@xref{flushleft & flushright, , @code{@@flushleft} and
|
|
@code{@@flushright}}.@refill
|
|
|
|
@need 200
|
|
@item @@flushright
|
|
Right justify every line but leave the left end ragged.
|
|
Leave font as is. Pair with @code{@@end flushright}.
|
|
@xref{flushleft & flushright, , @code{@@flushleft} and
|
|
@code{@@flushright}}.@refill
|
|
|
|
@need 200
|
|
@item @@footnote@{@var{text-of-footnote}@}
|
|
Enter a footnote. Footnote text is printed at the bottom of the page
|
|
by @TeX{}; Info may format in either `End' node or `Separate' node style.
|
|
@xref{Footnotes}.@refill
|
|
|
|
@item @@footnotestyle @var{style}
|
|
Specify an Info file's footnote style, either @samp{end} for the end
|
|
node style or @samp{separate} for the separate node style.
|
|
@xref{Footnotes}.@refill
|
|
|
|
@item @@format
|
|
Begin a kind of example. Like @code{@@example} or @code{@@display},
|
|
but do not narrow the margins and do not select the fixed-width font.
|
|
Pair with @code{@@end format}. @xref{example, ,
|
|
@code{@@example}}.@refill
|
|
|
|
@item @@ftable @var{formatting-command}
|
|
Begin a two-column table, using @code{@@item} for each entry.
|
|
Automatically enter each of the items in the first column into the
|
|
index of functions. Pair with @code{@@end ftable}. The same as
|
|
@code{@@table}, except for indexing. @xref{ftable vtable, ,
|
|
@code{@@ftable} and @code{@@vtable}}.@refill
|
|
|
|
@item @@group
|
|
Hold text together that must appear on one printed page. Pair with
|
|
@code{@@end group}. Not relevant to Info. @xref{group, ,
|
|
@code{@@group}}.@refill
|
|
|
|
@item @@heading @var{title}
|
|
Print an unnumbered section-like heading in the text, but not in the
|
|
table of contents of a printed manual. In Info, the title is
|
|
underlined with equal signs. @xref{unnumberedsec appendixsec heading,
|
|
, Section Commands}.@refill
|
|
|
|
@item @@headings @var{on-off-single-double}
|
|
Turn page headings on or off, or specify single-sided or double-sided
|
|
page headings for printing. @code{@@headings on} is synonymous with
|
|
@code{@@headings double}. @xref{headings on off, , The
|
|
@code{@@headings} Command}.@refill
|
|
|
|
@item @@i@{@var{text}@}
|
|
Print @var{text} in @i{italic} font. No effect in Info.
|
|
@xref{Fonts}.@refill
|
|
|
|
@item @@ifclear @var{flag}
|
|
If @var{flag} is cleared, the Texinfo formatting commands format text
|
|
between @code{@@ifclear @var{flag}} and the following @code{@@end
|
|
ifclear} command.
|
|
@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
|
|
|
|
@item @@ifinfo
|
|
Begin a stretch of text that will be ignored by @TeX{} when it
|
|
typesets the printed manual. The text appears only in the Info file.
|
|
Pair with @code{@@end ifinfo}. @xref{Conditionals, , Conditionally
|
|
Visible Text}.@refill
|
|
|
|
@item @@ifset @var{flag}
|
|
If @var{flag} is set, the Texinfo formatting commands format text
|
|
between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
|
|
command.
|
|
@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
|
|
|
|
@item @@iftex
|
|
Begin a stretch of text that will not appear in the Info file, but
|
|
will be processed only by @TeX{}. Pair with @code{@@end iftex}.
|
|
@xref{Conditionals, , Conditionally Visible Text}.@refill
|
|
|
|
@item @@ignore
|
|
Begin a stretch of text that will not appear in either the Info file
|
|
or the printed output. Pair with @code{@@end ignore}.
|
|
@xref{Comments, , Comments and Ignored Text}.@refill
|
|
|
|
@item @@include @var{filename}
|
|
Incorporate the contents of the file @var{filename} into the Info file
|
|
or printed document. @xref{Include Files}.@refill
|
|
|
|
@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
|
|
Make a cross reference to an Info file for which there is no printed
|
|
manual. @xref{inforef, , Cross references using
|
|
@code{@@inforef}}.@refill
|
|
|
|
@item \input @var{macro-definitions-file}
|
|
Use the specified macro definitions file. This command is used only
|
|
in the first line of a Texinfo file to cause @TeX{} to make use of the
|
|
@file{texinfo} macro definitions file. The backslash in @code{\input}
|
|
is used instead of an @code{@@} because @TeX{} does not properly
|
|
recognize @code{@@} until after it has read the definitions file.
|
|
@xref{Header, , The Texinfo File Header}.@refill
|
|
|
|
@item @@item
|
|
Indicate the beginning of a marked paragraph for @code{@@itemize} and
|
|
@code{@@enumerate}; indicate the beginning of the text of a first column
|
|
entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
|
|
@xref{Lists and Tables}.@refill
|
|
|
|
@item @@itemize @var{mark-generating-character-or-command}
|
|
Produce a sequence of indented paragraphs, with a mark inside the left
|
|
margin at the beginning of each paragraph. Pair with @code{@@end
|
|
itemize}. @xref{itemize, , @code{@@itemize}}.@refill
|
|
|
|
@item @@itemx
|
|
Like @code{@@item} but do not generate extra vertical space above the
|
|
item text. @xref{itemx, , @code{@@itemx}}.@refill
|
|
|
|
@item @@kbd@{@var{keyboard-characters}@}
|
|
Indicate text that consists of characters of input to be typed by
|
|
users. @xref{kbd, , @code{@@kbd}}.@refill
|
|
|
|
@item @@key@{@var{key-name}@}
|
|
Highlight @var{key-name}, a conventional name for a key on a keyboard.
|
|
@xref{key, , @code{@@key}}.@refill
|
|
|
|
@item @@kindex @var{entry}
|
|
Add @var{entry} to the index of keys. @xref{Index Entries, , Defining the
|
|
Entries of an Index}.@refill
|
|
|
|
@item @@lisp
|
|
Begin an example of Lisp code. Indent text, do not fill, and select
|
|
fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, ,
|
|
@code{@@lisp}}.@refill
|
|
|
|
@item @@majorheading @var{title}
|
|
Print a chapter-like heading in the text, but not in the table of
|
|
contents of a printed manual. Generate more vertical whitespace before
|
|
the heading than the @code{@@chapheading} command. In Info, the chapter
|
|
heading line is underlined with asterisks. @xref{majorheading &
|
|
chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
|
|
|
|
@item @@menu
|
|
Mark the beginning of a menu of nodes in Info. No effect in a printed
|
|
manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
|
|
|
|
@item @@minus@{@}
|
|
Generate a minus sign. @xref{minus, , @code{@@minus}}.@refill
|
|
|
|
@item @@need @var{n}
|
|
Start a new page in a printed manual if fewer than @var{n} mils
|
|
(thousandths of an inch) remain on the current page. @xref{need, ,
|
|
@code{@@need}}.@refill
|
|
|
|
@item @@node @var{name, next, previous, up}
|
|
Define the beginning of a new node in Info, and serve as a locator for
|
|
references for @TeX{}. @xref{node, , @code{@@node}}.@refill
|
|
|
|
@need 200
|
|
@item @@noindent
|
|
Prevent text from being indented as if it were a new paragraph.
|
|
@xref{noindent, , @code{@@noindent}}.@refill
|
|
|
|
@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
|
|
Specify page footings for odd-numbered (right-hand) pages. Not relevant to
|
|
Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
|
|
Specify page headings for odd-numbered (right-hand) pages. Not relevant to
|
|
Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@page
|
|
Start a new page in a printed manual. No effect in Info.
|
|
@xref{page, , @code{@@page}}.@refill
|
|
|
|
@item @@paragraphindent @var{indent}
|
|
Indent paragraphs by @var{indent} number of spaces; delete indentation
|
|
if the value of @var{indent} is 0; and do not change indentation if
|
|
@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph
|
|
Indenting}.@refill
|
|
|
|
@item @@pindex @var{entry}
|
|
Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
|
|
the Entries of an Index}.@refill
|
|
|
|
@item @@point@{@}
|
|
Indicate the position of point in a buffer to the reader with a
|
|
glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
|
|
Point in a Buffer}.@refill
|
|
|
|
@item @@print@{@}
|
|
Indicate printed output to the reader with a glyph:
|
|
@samp{@print{}}. @xref{Print Glyph}.@refill
|
|
|
|
@item @@printindex @var{index-name}
|
|
Print an alphabetized two-column index in a printed manual or generate
|
|
an alphabetized menu of index entries for Info. @xref{Printing
|
|
Indices & Menus}.@refill
|
|
|
|
@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
|
|
Make a reference that starts with a lower case `see' in a printed
|
|
manual. Use within parentheses only. Do not follow command with a
|
|
punctuation mark. The Info formatting commands automatically insert
|
|
terminating punctuation as needed, which is why you do not need to
|
|
insert punctuation. Only the first argument is mandatory.
|
|
@xref{pxref, , @code{@@pxref}}.@refill
|
|
|
|
@item @@quotation
|
|
Narrow the margins to indicate text that is quoted from another real
|
|
or imaginary work. Write command on a line of its own. Pair with
|
|
@code{@@end quotation}. @xref{quotation, ,
|
|
@code{@@quotation}}.@refill
|
|
|
|
@need 100
|
|
@item @@r@{@var{text}@}
|
|
Print @var{text} in @r{roman} font. No effect in Info.
|
|
@xref{Fonts}.@refill
|
|
|
|
@need 300
|
|
@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
|
|
Make a reference. In a printed manual, the reference does not start
|
|
with a `See'. Follow command with a punctuation mark. Only the first
|
|
argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
|
|
|
|
@need 300
|
|
@item @@refill
|
|
In Info, refill and indent the paragraph after all the other processing
|
|
has been done. No effect on @TeX{}, which always refills. This command
|
|
is no longer needed, since all formatters now automatically refill.
|
|
@xref{Refilling Paragraphs}.@refill
|
|
|
|
@need 300
|
|
@item @@result@{@}
|
|
Indicate the result of an expression to the reader with a special
|
|
glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
|
|
|
|
@item @@samp@{@var{text}@}
|
|
Highlight @var{text} that is a literal example of a sequence of
|
|
characters. Used for single characters, for statements, and often for
|
|
entire shell commands. @xref{samp, , @code{@@samp}}.@refill
|
|
|
|
@item @@sc@{@var{text}@}
|
|
Set @var{text} in a printed output in @sc{the small caps font} and
|
|
set text in the Info file in uppercase letters.
|
|
@xref{Smallcaps}.@refill
|
|
|
|
@item @@section @var{title}
|
|
Begin a section within a chapter. In a printed manual, the section
|
|
title is numbered and appears in the table of contents. In Info, the
|
|
title is underlined with equal signs. @xref{section, ,
|
|
@code{@@section}}.@refill
|
|
|
|
@item @@set @var{flag} [@var{string}]
|
|
Make @var{flag} active, causing the Texinfo formatting commands to
|
|
format text between subsequent pairs of @code{@@ifset @var{flag}} and
|
|
@code{@@end ifset} commands. Optionally, set value of @var{flag} to
|
|
@var{string}.
|
|
@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
|
|
|
|
@item @@setchapternewpage @var{on-off-odd}
|
|
Specify whether chapters start on new pages, and if so, whether on
|
|
odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
|
|
@code{@@setchapternewpage}}.@refill
|
|
|
|
@item @@setfilename @var{info-file-name}
|
|
Provide a name for the Info file. @xref{Conventions, , General
|
|
Syntactic Conventions}.@refill
|
|
|
|
@item @@settitle @var{title}
|
|
Provide a title for page headers in a printed manual.
|
|
@xref{Conventions, , General Syntactic Conventions}.@refill
|
|
|
|
@item @@shortcontents
|
|
Print a short table of contents. Not relevant to Info, which uses
|
|
menus rather than tables of contents. A synonym for
|
|
@code{@@summarycontents}. @xref{Contents, , Generating a Table of
|
|
Contents}.@refill
|
|
|
|
@need 400
|
|
@item @@smallbook
|
|
Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
|
|
rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
|
|
Printing Small Books}. Also, see @ref{smallexample & smalllisp, ,
|
|
@code{@@smallexample} and @code{@@smalllisp}}.@refill
|
|
|
|
@need 400
|
|
@item @@smallexample
|
|
Indent text to indicate an example. Do not fill, select fixed-width
|
|
font. In @code{@@smallbook} format, print text in a smaller font than
|
|
with @code{@@example}. Pair with @code{@@end smallexample}.
|
|
@xref{smallexample & smalllisp, , @code{@@smallexample} and
|
|
@code{@@smalllisp}}.@refill
|
|
|
|
@need 400
|
|
@item @@smalllisp
|
|
Begin an example of Lisp code. Indent text, do not fill, select
|
|
fixed-width font. In @code{@@smallbook} format, print text in a
|
|
smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample &
|
|
smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill
|
|
|
|
@need 700
|
|
@item @@sp @var{n}
|
|
Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
|
|
|
|
@need 700
|
|
@item @@strong @var{text}
|
|
Emphasize @var{text} by typesetting it in a @strong{bold} font for the
|
|
printed manual and by surrounding it with asterisks for Info.
|
|
@xref{emph & strong, , Emphasizing Text}.@refill
|
|
|
|
@item @@subheading @var{title}
|
|
Print an unnumbered subsection-like heading in the text, but not in
|
|
the table of contents of a printed manual. In Info, the title is
|
|
underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
|
|
subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
|
|
@code{@@subheading}}.@refill
|
|
|
|
@item @@subsection @var{title}
|
|
Begin a subsection within a section. In a printed manual, the
|
|
subsection title is numbered and appears in the table of contents. In
|
|
Info, the title is underlined with hyphens. @xref{subsection, ,
|
|
@code{@@subsection}}.@refill
|
|
|
|
@item @@subsubheading @var{title}
|
|
Print an unnumbered subsubsection-like heading in the text, but not in
|
|
the table of contents of a printed manual. In Info, the title is
|
|
underlined with periods. @xref{subsubsection, , The `subsub'
|
|
Commands}.@refill
|
|
|
|
@item @@subsubsection @var{title}
|
|
Begin a subsubsection within a subsection. In a printed manual,
|
|
the subsubsection title is numbered and appears in the table of
|
|
contents. In Info, the title is underlined with periods.
|
|
@xref{subsubsection, , The `subsub' Commands}.@refill
|
|
|
|
@item @@subtitle @var{title}
|
|
In a printed manual, set a subtitle in a normal sized font flush to
|
|
the right-hand side of the page. Not relevant to Info, which does not
|
|
have title pages. @xref{title subtitle author, , @code{@@title}
|
|
@code{@@subtitle} and @code{@@author} Commands}.@refill
|
|
|
|
@item @@summarycontents
|
|
Print a short table of contents. Not relevant to Info, which uses
|
|
menus rather than tables of contents. A synonym for
|
|
@code{@@shortcontents}. @xref{Contents, , Generating a Table of
|
|
Contents}.@refill
|
|
|
|
@need 300
|
|
@item @@syncodeindex @var{from-index} @var{into-index}
|
|
Merge the index named in the first argument into the index named in
|
|
the second argument, printing the entries from the first index in
|
|
@code{@@code} font. @xref{Combining Indices}.@refill
|
|
|
|
@need 300
|
|
@item @@synindex @var{from-index} @var{into-index}
|
|
Merge the index named in the first argument into the index named in
|
|
the second argument. Do not change the font of @var{from-index}
|
|
entries. @xref{Combining Indices}.@refill
|
|
|
|
@need 100
|
|
@item @@t@{@var{text}@}
|
|
Print @var{text} in a @t{fixed-width}, typewriter-like font.
|
|
No effect in Info. @xref{Fonts}.@refill
|
|
|
|
@need 400
|
|
@item @@table @var{formatting-command}
|
|
Begin a two-column table, using @code{@@item} for each entry. Write
|
|
each first column entry on the same line as @code{@@item}. First
|
|
column entries are printed in the font resulting from
|
|
@var{formatting-command}. Pair with @code{@@end table}.
|
|
@xref{Two-column Tables, , Making a Two-column Table}.
|
|
Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
|
|
and @ref{itemx, , @code{@@itemx}}.@refill
|
|
|
|
@item @@TeX@{@}
|
|
Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
|
|
and @copyright{}}.@refill
|
|
|
|
@item @@tex
|
|
Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Using
|
|
Ordinary TeX Commands, , Using Ordinary @TeX{} Commands}.@refill
|
|
|
|
@item @@thischapter
|
|
In a heading or footing, stands for the number and name of the current
|
|
chapter, in the format `Chapter 1: Title'. @xref{Custom
|
|
Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@thischaptername
|
|
In a heading or footing, stands for the name of the current chapter.
|
|
@xref{Custom Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@thisfile
|
|
In a heading or footing, stands for the name of the current
|
|
@code{@@include} file. Does not insert anything if not within an
|
|
@code{@@include} file. @xref{Custom Headings, , How to Make Your Own
|
|
Headings}.@refill
|
|
|
|
@item @@thispage
|
|
In a heading or footing, stands for the current page number.
|
|
@xref{Custom Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@ignore
|
|
@item @@thissection
|
|
In a heading or footing, stands for the title of the current section.
|
|
@xref{Custom Headings, , How to Make Your Own Headings}.@refill
|
|
@end ignore
|
|
|
|
@item @@thistitle
|
|
In a heading or footing, stands for the name of the document, as specified
|
|
by the @code{@@settitle} command. @xref{Custom Headings, , How to
|
|
Make Your Own Headings}.@refill
|
|
|
|
@item @@tindex @var{entry}
|
|
Add @var{entry} to the index of data types. @xref{Index Entries, ,
|
|
Defining the Entries of an Index}.@refill
|
|
|
|
@item @@title @var{title}
|
|
In a printed manual, set a title flush to the left-hand side of the
|
|
page in a larger than normal font and underline it with a black rule.
|
|
Not relevant to Info, which does not have title pages. @xref{title
|
|
subtitle author, , The @code{@@title} @code{@@subtitle} and
|
|
@code{@@author} Commands}.@refill
|
|
|
|
@need 400
|
|
@item @@titlefont@{@var{text}@}
|
|
In a printed manual, print @var{text} in a larger than normal font.
|
|
Not relevant to Info, which does not have title pages.
|
|
@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
|
|
and @code{@@sp} Commands}.@refill
|
|
|
|
@need 300
|
|
@item @@titlepage
|
|
Indicate to Texinfo the beginning of the title page. Write command on
|
|
a line of its own. Pair with @code{@@end titlepage}. Nothing between
|
|
@code{@@titlepage} and @code{@@end titlepage} appears in Info.
|
|
@xref{titlepage, , @code{@@titlepage}}.@refill
|
|
|
|
@need 150
|
|
@item @@today@{@}
|
|
Insert the current date, in `1 Jan 1900' style. @xref{Custom
|
|
Headings, , How to Make Your Own Headings}.@refill
|
|
|
|
@item @@top @var{title}
|
|
In a Texinfo file to be formatted with @code{makeinfo}, identify the
|
|
topmost @code{@@node} line in the file, which must be written on the line
|
|
immediately preceding the @code{@@top} command. Used for
|
|
@code{makeinfo}'s node pointer insertion feature. The title is
|
|
underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
|
|
line normally should be enclosed by @code{@@ifinfo} and @code{@@end
|
|
ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
|
|
command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
|
|
Pointer Creation, , Creating Pointers with @code{makeinfo}}.
|
|
|
|
@item @@unnumbered @var{title}
|
|
In a printed manual, begin a chapter that appears without chapter
|
|
numbers of any kind. The title appears in the table of contents of a
|
|
printed manual. In Info, the title is underlined with asterisks.
|
|
@xref{unnumbered & appendix, , @code{@@unnumbered} and
|
|
@code{@@appendix}}.@refill
|
|
|
|
@item @@unnumberedsec @var{title}
|
|
In a printed manual, begin a section that appears without section
|
|
numbers of any kind. The title appears in the table of contents of a
|
|
printed manual. In Info, the title is underlined with equal signs.
|
|
@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
|
|
|
|
@item @@unnumberedsubsec @var{title}
|
|
In a printed manual, begin an unnumbered subsection within a
|
|
chapter. The title appears in the table of contents of a printed
|
|
manual. In Info, the title is underlined with hyphens.
|
|
@xref{unnumberedsubsec appendixsubsec subheading, ,
|
|
@code{@@unnumberedsubsec} @code{@@appendixsubsec}
|
|
@code{@@subheading}}.@refill
|
|
|
|
@item @@unnumberedsubsubsec @var{title}
|
|
In a printed manual, begin an unnumbered subsubsection within a
|
|
chapter. The title appears in the table of contents of a printed
|
|
manual. In Info, the title is underlined with periods.
|
|
@xref{subsubsection, , The `subsub' Commands}.@refill
|
|
|
|
@item @@value@{@var{flag}@}
|
|
Replace @var{flag} with the value to which it is set by @code{@@set
|
|
@var{flag}}.
|
|
@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
|
|
|
|
@item @@var@{@var{metasyntactic-variable}@}
|
|
Highlight a metasyntactic variable, which is something that stands for
|
|
another piece of text. @xref{var, , Indicating Metasyntactic
|
|
Variables}.@refill
|
|
|
|
@need 400
|
|
@item @@vindex @var{entry}
|
|
Add @var{entry} to the index of variables. @xref{Index Entries, ,
|
|
Defining the Entries of an Index}.@refill
|
|
|
|
@need 400
|
|
@item @@vskip @var{amount}
|
|
In a printed manual, insert whitespace so as to push text on the
|
|
remainder of the page towards the bottom of the page. Used in
|
|
formatting the copyright page with the argument @samp{0pt plus
|
|
1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
|
|
only in contexts ignored for Info. @xref{Copyright & Permissions, ,
|
|
The Copyright Page and Printed Permissions}.@refill
|
|
|
|
@need 400
|
|
@item @@vtable @var{formatting-command}
|
|
Begin a two-column table, using @code{@@item} for each entry.
|
|
Automatically enter each of the items in the first column into the
|
|
index of variables. Pair with @code{@@end vtable}. The same as
|
|
@code{@@table}, except for indexing. @xref{ftable vtable, ,
|
|
@code{@@ftable} and @code{@@vtable}}.@refill
|
|
|
|
@need 400
|
|
@item @@w@{@var{text}@}
|
|
Prevent @var{text} from being split across two lines. Do not end a
|
|
paragraph that uses @code{@@w} with an @code{@@refill} command.
|
|
In the Texinfo file, keep @var{text} on one line.
|
|
@xref{w, , @code{@@w}}.@refill
|
|
|
|
@need 400
|
|
@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
|
|
Make a reference that starts with `See' in a printed manual. Follow
|
|
command with a punctuation mark. Only the first argument is
|
|
mandatory. @xref{xref, , @code{@@xref}}.@refill
|
|
@end table
|
|
|
|
@node Tips, Sample Texinfo File, Command List, Top
|
|
@comment node-name, next, previous, up
|
|
@appendix Tips and Hints
|
|
|
|
Here are some tips for writing Texinfo documentation:@refill
|
|
|
|
@cindex Tips
|
|
@cindex Usage tips
|
|
@cindex Hints
|
|
@itemize @bullet
|
|
@item
|
|
Write in the present tense, not in the past or the future.
|
|
|
|
@item
|
|
Write actively! For example, write ``We recommend that @dots{}'' rather
|
|
than ``It is recommended that @dots{}''.
|
|
|
|
@item
|
|
Use 70 or 72 as your fill column. Longer lines are hard to read.
|
|
|
|
@item
|
|
Include a copyright notice and copying permissions.
|
|
@end itemize
|
|
|
|
@subsubheading Index, index, index!
|
|
|
|
Write many index entries, in different ways.
|
|
Readers like indices; they are helpful and convenient.
|
|
|
|
Although it is easiest to write index entries as you write the body of
|
|
the text, some people prefer to write entries afterwards. In either
|
|
case, write an entry before the paragraph to which it applies. This
|
|
way, an index entry points to the first page of a paragraph that is
|
|
split across pages.
|
|
|
|
Here are more hints we have found valuable:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Write each index entry differently, so each entry refers to a different
|
|
place in the document. The index of an Info file lists only one
|
|
location for each entry.
|
|
|
|
@item
|
|
Write index entries only where a topic is discussed significantly. For
|
|
example, it is not useful to index ``debugging information'' in a
|
|
chapter on reporting bugs. Someone who wants to know about debugging
|
|
information will certainly not find it in that chapter.
|
|
|
|
@item
|
|
Consistently capitalize the first word of every index entry, or else use
|
|
lower case. According to convention, you should capitalize the first
|
|
word of an index entry. However, this practice may make an index look
|
|
crowded. Some writers prefer lower case. Regardless of which you
|
|
prefer, choose one style and stick to it. Mixing the two styles looks
|
|
bad.
|
|
|
|
@item
|
|
Always capitalize or use upper case for those words in an index for
|
|
which this is proper, such as names of countries or acronyms.
|
|
|
|
@item
|
|
Write the indexing commands that refer to a whole section immediately
|
|
after the section command, and write the indexing commands that refer to
|
|
the paragraph before the paragraph.
|
|
|
|
@need 1000
|
|
In the example that follows, a blank line comes after the index
|
|
entry for ``Leaping'':
|
|
|
|
@example
|
|
@group
|
|
@@section The Dog and the Fox
|
|
@@cindex Jumping, in general
|
|
@@cindex Leaping
|
|
|
|
@@cindex Dog, lazy, jumped over
|
|
@@cindex Lazy dog jumped over
|
|
@@cindex Fox, jumps over dog
|
|
@@cindex Quick fox jumps over dog
|
|
The quick brown fox jumps over the lazy dog.
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
(Note that the example shows entries for the same concept that are
|
|
written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
|
|
readers can look up the concept in different ways.)
|
|
@end itemize
|
|
|
|
@subsubheading Blank lines
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Insert a blank line between a sectioning command and the first following
|
|
sentence or paragraph, or between the indexing commands associated with
|
|
the sectioning command and the first following sentence or paragraph, as
|
|
shown in the tip on indexing. Otherwise, a formatter may fold title and
|
|
paragraph together.
|
|
|
|
@item
|
|
Always insert a blank line before an @code{@@table} command and after an
|
|
@code{@@end table} command; but never insert a blank line after an
|
|
@code{@@table} command or before an @code{@@end table} command.
|
|
|
|
@need 1000
|
|
For example,
|
|
|
|
@example
|
|
@group
|
|
Types of fox:
|
|
|
|
@@table @@samp
|
|
@@item Quick
|
|
Jump over lazy dogs.
|
|
@end group
|
|
|
|
@group
|
|
@@item Brown
|
|
Also jump over lazy dogs.
|
|
@@end table
|
|
|
|
@end group
|
|
@group
|
|
@@noindent
|
|
On the other hand, @dots{}
|
|
@end group
|
|
@end example
|
|
|
|
Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
|
|
itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
|
|
same way.
|
|
@end itemize
|
|
|
|
@subsubheading Complete phrases
|
|
|
|
Complete phrases are easier to read than @dots{}
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Write entries in an itemized list as complete sentences; or at least, as
|
|
complete phrases. Incomplete expressions @dots{} awkward @dots{} like
|
|
this.
|
|
|
|
@item
|
|
Write the prefatory sentence or phrase for a multi-item list or table as
|
|
a complete expression. Do not write ``You can set:''; instead, write
|
|
``You can set these variables:''. The former expression sounds cut off.
|
|
@end itemize
|
|
|
|
@subsubheading Editions, dates and versions
|
|
|
|
Write the edition and version numbers and date in three places in every
|
|
manual:
|
|
|
|
@enumerate
|
|
@item
|
|
In the first @code{@@ifinfo} section, for people reading the Texinfo file.
|
|
|
|
@item
|
|
In the @code{@@titlepage} section, for people reading the printed manual.
|
|
|
|
@item
|
|
In the `Top' node, for people reading the Info file.
|
|
@end enumerate
|
|
|
|
@noindent
|
|
Also, it helps to write a note before the first @code{@@ifinfo}
|
|
section to explain what you are doing.
|
|
|
|
@need 800
|
|
@noindent
|
|
For example:
|
|
|
|
@example
|
|
@group
|
|
@@c ===> NOTE! <==
|
|
@@c Specify the edition and version numbers and date
|
|
@@c in *three* places:
|
|
@@c 1. First ifinfo section 2. title page 3. top node
|
|
@@c To find the locations, search for !!set
|
|
@end group
|
|
|
|
@group
|
|
@@ifinfo
|
|
@@c !!set edition, date, version
|
|
This is Edition 4.03, January 1992,
|
|
of the @@cite@{GDB Manual@} for GDB Version 4.3.
|
|
@dots{}
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
---or use @code{@@set} and @code{@@value}
|
|
(@pxref{value Example, , @code{@@value} Example}).
|
|
|
|
@subsubheading Definition Commands
|
|
|
|
Definition commands are @code{@@deffn}, @code{@@defun},
|
|
@code{@@defmac}, and the like, and enable you to write descriptions in
|
|
a uniform format.@refill
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Write just one definition command for each entity you define with a
|
|
definition command. The automatic indexing feature creates an index
|
|
entry that leads the reader to the definition.
|
|
|
|
@item
|
|
Use @code{@@table} @dots{} @code{@@end table} in an appendix that
|
|
contains a summary of functions, not @code{@@deffn} or other definition
|
|
commands.
|
|
@end itemize
|
|
|
|
@subsubheading Capitalization
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Capitalize @samp{Texinfo}; it is a name. Do not write the @samp{x} or
|
|
@samp{i} in upper case.
|
|
|
|
@item
|
|
Capitalize @samp{Info}; it is a name.
|
|
|
|
@item
|
|
Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
|
|
@samp{T} and @samp{X}. This command causes the formatters to
|
|
typeset the name according to the wishes of Donald Knuth, who wrote
|
|
@TeX{}.
|
|
@end itemize
|
|
|
|
@subsubheading Spaces
|
|
|
|
Do not use spaces to format a Texinfo file, except inside of
|
|
@code{@@example} @dots{} @code{@@end example} and similar commands.
|
|
|
|
@need 700
|
|
For example, @TeX{} fills the following:
|
|
|
|
@example
|
|
@group
|
|
@@kbd@{C-x v@}
|
|
@@kbd@{M-x vc-next-action@}
|
|
Perform the next logical operation
|
|
on the version-controlled file
|
|
corresponding to the current buffer.
|
|
@end group
|
|
@end example
|
|
|
|
@need 950
|
|
@noindent
|
|
so it looks like this:
|
|
|
|
@iftex
|
|
@quotation
|
|
@kbd{C-x v}
|
|
@kbd{M-x vc-next-action}
|
|
Perform the next logical operation on the version-controlled file
|
|
corresponding to the current buffer.
|
|
@end quotation
|
|
@end iftex
|
|
@ifinfo
|
|
@quotation
|
|
`C-x v' `M-x vc-next-action' Perform the next logical operation on the
|
|
version-controlled file corresponding to the current buffer.
|
|
@end quotation
|
|
@end ifinfo
|
|
|
|
@noindent
|
|
In this case, the text should be formatted with
|
|
@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
|
|
|
|
@subsubheading @@code, @@samp, @@var, and @samp{---}
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Use @code{@@code} around Lisp symbols, including command names.
|
|
For example,
|
|
|
|
@example
|
|
The main function is @@code@{vc-next-action@}, @dots{}
|
|
@end example
|
|
|
|
@item
|
|
Avoid putting letters such as @samp{s} immediately after an
|
|
@samp{@@code}. Such letters look bad.
|
|
|
|
@item
|
|
Use @code{@@var} around meta-variables. Do not write angle brackets
|
|
around them.
|
|
|
|
@item
|
|
Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
|
|
typesets these as a long dash and the Info formatters reduce three
|
|
hyphens to two.
|
|
@end itemize
|
|
|
|
@subsubheading Periods Outside of Quotes
|
|
|
|
Place periods and other punctuation marks @emph{outside} of quotations,
|
|
unless the punctuation is part of the quotation. This practice goes against
|
|
convention, but enables the reader to distinguish between the contents
|
|
of the quotation and the whole passage.
|
|
|
|
For example, you should write the following sentence with the period
|
|
outside the end quotation marks:
|
|
|
|
@example
|
|
Evidently, @samp{au} is an abbreviation for ``author''.
|
|
@end example
|
|
|
|
@noindent
|
|
since @samp{au} does @emph{not} serve as an abbreviation for
|
|
@samp{author.} (with a period following the word).
|
|
|
|
@subsubheading Introducing New Terms
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Introduce new terms so that a user who does not know them can understand
|
|
them from context; or write a definition for the term.
|
|
|
|
For example, in the following, the terms ``check in'', ``register'' and
|
|
``delta'' are all appearing for the first time; the example sentence should be
|
|
rewritten so they are understandable.
|
|
|
|
@quotation
|
|
The major function assists you in checking in a file to your
|
|
version control system and registering successive sets of changes to
|
|
it as deltas.
|
|
@end quotation
|
|
|
|
@item
|
|
Use the @code{@@dfn} command around a word being introduced, to indicate
|
|
that the user should not expect to know the meaning already, and should
|
|
expect to learn the meaning from this passage.
|
|
@end itemize
|
|
|
|
@subsubheading @@pxref
|
|
|
|
@c !!! maybe include this in the tips on pxref
|
|
@ignore
|
|
By the way, it is okay to use pxref with something else in front of
|
|
it within the parens, as long as the pxref is followed by the close
|
|
paren, and the material inside the parents is not part of a larger
|
|
sentence. Also, you can use xref inside parens as part of a complete
|
|
sentence so long as you terminate the cross reference with punctuation.
|
|
@end ignore
|
|
Absolutely never use @code{@@pxref} except in the special context for
|
|
which it is designed: inside parentheses, with the closing parenthesis
|
|
following immediately after the closing brace. One formatter
|
|
automatically inserts closing punctuation and the other does not. This
|
|
means that the output looks right both in printed output and in an Info
|
|
file, but only when the command is used inside parentheses.
|
|
|
|
@subsubheading Invoking from a Shell
|
|
|
|
You can invoke programs such as Emacs, GCC, and GAWK from a shell.
|
|
The documentation for each program should contain a section that
|
|
describes this. Unfortunately, if the node names and titles for these
|
|
sections are all different, readers find it hard to search for the
|
|
section.@refill
|
|
|
|
Name such sections with a phrase beginning with the word
|
|
@w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way
|
|
users can find the section easily.
|
|
|
|
@subsubheading @sc{ansi c} Syntax
|
|
|
|
When you use @code{@@example} to describe a C function's calling
|
|
conventions, use the @sc{ansi c} syntax, like this:@refill
|
|
|
|
@example
|
|
void dld_init (char *@@var@{path@});
|
|
@end example
|
|
|
|
@noindent
|
|
And in the subsequent discussion, refer to the argument values by
|
|
writing the same argument names, again highlighted with
|
|
@code{@@var}.@refill
|
|
|
|
@need 800
|
|
Avoid the obsolete style that looks like this:@refill
|
|
|
|
@example
|
|
#include <dld.h>
|
|
|
|
dld_init (path)
|
|
char *path;
|
|
@end example
|
|
|
|
Also, it is best to avoid writing @code{#include} above the
|
|
declaration just to indicate that the function is declared in a
|
|
header file. The practice may give the misimpression that the
|
|
@code{#include} belongs near the declaration of the function. Either
|
|
state explicitly which header file holds the declaration or, better
|
|
yet, name the header file used for a group of functions at the
|
|
beginning of the section that describes the functions.@refill
|
|
|
|
@subsubheading Bad Examples
|
|
|
|
Here are several examples of bad writing to avoid:
|
|
|
|
In this example, say, `` @dots{} you must @code{@@dfn}@{check
|
|
in@} the new version.'' That flows better.
|
|
|
|
@quotation
|
|
When you are done editing the file, you must perform a
|
|
@code{@@dfn}@{check in@}.
|
|
@end quotation
|
|
|
|
In the following example, say, ``@dots{} makes a unified interface such as VC
|
|
mode possible.''
|
|
|
|
@quotation
|
|
SCCS, RCS and other version-control systems all perform similar
|
|
functions in broadly similar ways (it is this resemblance which makes
|
|
a unified control mode like this possible).
|
|
@end quotation
|
|
|
|
And in this example, you should specify what `it' refers to:
|
|
|
|
@quotation
|
|
If you are working with other people, it assists in coordinating
|
|
everyone's changes so they do not step on each other.
|
|
@end quotation
|
|
|
|
@subsubheading And Finally @dots{}
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
|
|
sound in the name `Bach'. But pronounce Texinfo as in `speck':
|
|
@samp{teckinfo}.
|
|
|
|
@item
|
|
Write notes for yourself at the very end of a Texinfo file after the
|
|
@code{@@bye}. None of the formatters process text after the
|
|
@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
|
|
@code{@@end ignore}.
|
|
@end itemize
|
|
|
|
@node Sample Texinfo File, Sample Permissions, Tips, Top
|
|
@comment node-name, next, previous, up
|
|
@appendix A Sample Texinfo File
|
|
@cindex Sample Texinfo file, no comments
|
|
|
|
Here is a complete, short sample Texinfo file, without any commentary.
|
|
You can see this file, with comments, in the first chapter.
|
|
@xref{Short Sample, , A Short Sample Texinfo File}.
|
|
|
|
@sp 1
|
|
@example
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@@c %**start of header
|
|
@@setfilename sample.info
|
|
@@settitle Sample Document
|
|
@@c %**end of header
|
|
|
|
@@setchapternewpage odd
|
|
|
|
@@ifinfo
|
|
This is a short example of a complete Texinfo file.
|
|
|
|
Copyright 1990 Free Software Foundation, Inc.
|
|
@@end ifinfo
|
|
|
|
@@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
|
|
|
|
@@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
|
|
|
|
@@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.
|
|
|
|
@@node Concept Index, , First Chapter, Top
|
|
@@comment node-name, next, previous, up
|
|
@@unnumbered Concept Index
|
|
|
|
@@printindex cp
|
|
|
|
@@contents
|
|
@@bye
|
|
@end example
|
|
|
|
@node Sample Permissions, Include Files, Sample Texinfo File, Top
|
|
@appendix Sample Permissions
|
|
@cindex Permissions
|
|
@cindex Copying permissions
|
|
|
|
Texinfo files should contain sections that tell the readers that they
|
|
have the right to copy and distribute the Texinfo file, the Info file,
|
|
and the printed manual.@refill
|
|
|
|
Also, if you are writing a manual about software, you should explain
|
|
that the software is free and either include the GNU General Public
|
|
License (GPL) or provide a reference to it. @xref{Distrib, ,
|
|
Distribution, emacs, The GNU Emacs Manual}, for an example of the text
|
|
that could be used in the software ``Distribution'', ``General Public
|
|
License'', and ``NO WARRANTY'' sections of a document. @xref{Copying,
|
|
, Texinfo Copying Conditions}, for an example of a brief explanation
|
|
of how the copying conditions provide you with rights. @refill
|
|
|
|
@menu
|
|
* Inserting Permissions:: How to put permissions in your document.
|
|
* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions.
|
|
* Titlepage Permissions:: Sample Titlepage copying permissions.
|
|
@end menu
|
|
|
|
@node Inserting Permissions, ifinfo Permissions, , Sample Permissions
|
|
@ifinfo
|
|
@appendixsec Inserting Permissions
|
|
@end ifinfo
|
|
|
|
In a Texinfo file, the first @code{@@ifinfo} section usually begins
|
|
with a line that says what the file documents. This is what a person
|
|
reading the unprocessed Texinfo file or using the advanced Info
|
|
command @kbd{g *} sees first. @inforef{Expert, Advanced Info
|
|
commands, info}, for more information. (A reader using the regular
|
|
Info commands usually starts reading at the first node and skips
|
|
this first section, which is not in a node.)@refill
|
|
|
|
In the @code{@@ifinfo} section, the summary sentence is followed by a
|
|
copyright notice and then by the copying permission notice. One of
|
|
the copying permission paragraphs is enclosed in @code{@@ignore} and
|
|
@code{@@end ignore} commands. This paragraph states that the Texinfo
|
|
file can be processed through @TeX{} and printed, provided the printed
|
|
manual carries the proper copying permission notice. This paragraph
|
|
is not made part of the Info file since it is not relevant to the Info
|
|
file; but it is a mandatory part of the Texinfo file since it permits
|
|
people to process the Texinfo file in @TeX{} and print the
|
|
results.@refill
|
|
|
|
In the printed manual, the Free Software Foundation copying permission
|
|
notice follows the copyright notice and publishing information and is
|
|
located within the region delineated by the @code{@@titlepage} and
|
|
@code{@@end titlepage} commands. The copying permission notice is exactly
|
|
the same as the notice in the @code{@@ifinfo} section except that the
|
|
paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
|
|
not part of the notice.@refill
|
|
|
|
To make it simple to insert a permission notice into each section of
|
|
the Texinfo file, sample permission notices for each section are
|
|
reproduced in full below.@refill
|
|
|
|
Note that you may need to specify the correct name of a section
|
|
mentioned in the permission notice. For example, in @cite{The GDB
|
|
Manual}, the name of the section referring to the General Public
|
|
License is called the ``GDB General Public License'', but in the
|
|
sample shown below, that section is referred to generically as the
|
|
``GNU General Public License''. If the Texinfo file does not carry a
|
|
copy of the General Public License, leave out the reference to it, but
|
|
be sure to include the rest of the sentence.@refill
|
|
|
|
@node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions
|
|
@comment node-name, next, previous, up
|
|
@appendixsec @samp{ifinfo} Copying Permissions
|
|
@cindex @samp{ifinfo} permissions
|
|
|
|
In the @code{@@ifinfo} section of a Texinfo file, the standard Free
|
|
Software Foundation permission notice reads as follows:@refill
|
|
|
|
@example
|
|
This file documents @dots{}
|
|
|
|
Copyright 1992 Free Software Foundation, Inc.
|
|
|
|
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.
|
|
|
|
@@ignore
|
|
Permission is granted to process this file through TeX
|
|
and print the results, provided the printed document
|
|
carries a copying permission notice identical to this
|
|
one except for the removal of this paragraph (this
|
|
paragraph not being relevant to the printed manual).
|
|
|
|
@@end ignore
|
|
Permission is granted to copy and distribute modified
|
|
versions of this manual under the conditions for
|
|
verbatim copying, provided also that the sections
|
|
entitled ``Copying'' and ``GNU General Public License''
|
|
are included exactly as in the original, and 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.
|
|
@end example
|
|
|
|
@node Titlepage Permissions, , ifinfo Permissions, Sample Permissions
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Titlepage Copying Permissions
|
|
@cindex Titlepage permissions
|
|
|
|
In the @code{@@titlepage} section of a Texinfo file, the standard Free
|
|
Software Foundation copying permission notice follows the copyright
|
|
notice and publishing information. The standard phrasing is as
|
|
follows:@refill
|
|
|
|
@example
|
|
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 also that the sections
|
|
entitled ``Copying'' and ``GNU General Public License''
|
|
are included exactly as in the original, and 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.
|
|
@end example
|
|
|
|
@node Include Files, Headings, Sample Permissions, Top
|
|
@comment node-name, next, previous, up
|
|
@appendix Include Files
|
|
@cindex Include files
|
|
|
|
When @TeX{} or an Info formatting command sees an @code{@@include}
|
|
command in a Texinfo file, it processes the contents of the file named
|
|
by the command and incorporates them into the @sc{dvi} or Info file being
|
|
created. Index entries from the included file are incorporated into
|
|
the indices of the output file.@refill
|
|
|
|
Include files let you keep a single large document as a collection of
|
|
conveniently small parts.@refill
|
|
|
|
@menu
|
|
* Using Include Files:: How to use the @code{@@include} command.
|
|
* texinfo-multiple-files-update:: How to create and update nodes and
|
|
menus when using included files.
|
|
* Include File Requirements:: What @code{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 @code{@@include} command
|
|
has changed over time.
|
|
@end menu
|
|
|
|
@node Using Include Files, texinfo-multiple-files-update, , Include Files
|
|
@appendixsec How to Use Include Files
|
|
@findex include
|
|
|
|
To include another file within a Texinfo file, write the
|
|
@code{@@include} command at the beginning of a line and follow it on
|
|
the same line by the name of a file to be included. For
|
|
example:@refill
|
|
|
|
@example
|
|
@@include buffers.texi
|
|
@end example
|
|
|
|
An included file should simply be a segment of text that you expect to
|
|
be included as is into the overall or @dfn{outer} Texinfo file; it
|
|
should not contain the standard beginning and end parts of a Texinfo
|
|
file. In particular, you should not start an included file with a
|
|
line saying @samp{\input texinfo}; if you do, that phrase is inserted
|
|
into the output file as is. Likewise, you should not end an included
|
|
file with an @code{@@bye} command; nothing after @code{@@bye} is
|
|
formatted.@refill
|
|
|
|
In the past, you were required to write an @code{@@setfilename} line at the
|
|
beginning of an included file, but no longer. Now, it does not matter
|
|
whether you write such a line. If an @code{@@setfilename} line exists
|
|
in an included file, it is ignored.@refill
|
|
|
|
Conventionally, an included file begins with an @code{@@node} line that
|
|
is followed by an @code{@@chapter} line. Each included file is one
|
|
chapter. This makes it easy to use the regular node and menu creating
|
|
and updating commands to create the node pointers and menus within the
|
|
included file. However, the simple Emacs node and menu creating and
|
|
updating commands do not work with multiple Texinfo files. Thus you
|
|
cannot use these commands to fill in the `Next', `Previous', and `Up'
|
|
pointers of the @code{@@node} line that begins the included file. Also,
|
|
you cannot use the regular commands to create a master menu for the
|
|
whole file. Either you must insert the menus and the `Next',
|
|
`Previous', and `Up' pointers by hand, or you must use the GNU Emacs
|
|
Texinfo mode command, @code{texinfo-multiple-files-update}, that is
|
|
designed for @code{@@include} files.@refill
|
|
|
|
@node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
|
|
@appendixsec @code{texinfo-multiple-files-update}
|
|
@findex texinfo-multiple-files-update
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
GNU Emacs Texinfo mode provides a command to handle included files
|
|
called @code{texinfo-multiple-files-update}. This command creates or
|
|
updates `Next', `Previous', and `Up' pointers of included files as
|
|
well as those in the outer or overall Texinfo file, and it creates or
|
|
updates a main menu in the outer file. Depending whether you call it
|
|
with optional arguments, the command updates only the pointers in the
|
|
first @code{@@node} line of the included files or all of them:@refill
|
|
|
|
@table @kbd
|
|
@item M-x texinfo-multiple-files-update
|
|
Called without any arguments:@refill
|
|
|
|
@itemize @minus
|
|
@item
|
|
Create or update the `Next', `Previous', and `Up' pointers of the
|
|
first @code{@@node} line in each file included in an outer or overall
|
|
Texinfo file.@refill
|
|
|
|
@item
|
|
Create or update the `Top' level node pointers of the outer or
|
|
overall file.@refill
|
|
|
|
@item
|
|
Create or update a main menu in the outer file.@refill
|
|
@end itemize
|
|
|
|
@item C-u M-x texinfo-multiple-files-update
|
|
Called with @kbd{C-u} as a prefix argument:
|
|
|
|
@itemize @minus{}
|
|
@item
|
|
Create or update pointers in the first @code{@@node} line in each
|
|
included file.
|
|
|
|
@item
|
|
Create or update the `Top' level node pointers of the outer file.
|
|
|
|
@item
|
|
Create and insert a master menu in the outer file. The master menu
|
|
is made from all the menus in all the included files.@refill
|
|
@end itemize
|
|
|
|
@item C-u 8 M-x texinfo-multiple-files-update
|
|
Called with a numeric prefix argument, such as @kbd{C-u 8}:
|
|
|
|
@itemize @minus
|
|
@item
|
|
Create or update @strong{all} the `Next', `Previous', and `Up' pointers
|
|
of all the included files.@refill
|
|
|
|
@item
|
|
Create or update @strong{all} the menus of all the included
|
|
files.@refill
|
|
|
|
@item
|
|
Create or update the `Top' level node pointers of the outer or
|
|
overall file.@refill
|
|
|
|
@item
|
|
And then create a master menu in the outer file. This is similar to
|
|
invoking @code{texinfo-master-menu} with an argument when you are
|
|
working with just one file.@refill
|
|
@end itemize
|
|
@end table
|
|
|
|
Note the use of the prefix argument in interactive use: with a regular
|
|
prefix argument, just @w{@kbd{C-u}}, the
|
|
@code{texinfo-multiple-files-update} command inserts a master menu;
|
|
with a numeric prefix argument, such as @kbd{C-u 8}, the command
|
|
updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
|
|
master menu.@refill
|
|
|
|
@node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files
|
|
@appendixsec Include File Requirements
|
|
@cindex Include file requirements
|
|
@cindex Requirements for include files
|
|
|
|
If you plan to use the @code{texinfo-multiple-files-update} command,
|
|
the outer Texinfo file that lists included files within it should
|
|
contain nothing but the beginning and end parts of a Texinfo file, and
|
|
a number of @code{@@include} commands listing the included files. It
|
|
should not even include indices, which should be listed in an included
|
|
file of their own.@refill
|
|
|
|
Moreover, each of the included files must contain exactly one highest
|
|
level node (conventionally, @code{@@chapter} or equivalent),
|
|
and this node must be the first node in the included file.
|
|
Furthermore, each of these highest level nodes in each included file
|
|
must be at the same hierarchical level in the file structure.
|
|
Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
|
|
@code{@@unnumbered} node. Thus, normally, each included file contains
|
|
one, and only one, chapter or equivalent-level node.@refill
|
|
|
|
The outer file should contain only @emph{one} node, the `Top' node. It
|
|
should @emph{not} contain any nodes besides the single `Top' node. The
|
|
@code{texinfo-multiple-files-update} command will not process
|
|
them.@refill
|
|
|
|
@node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
|
|
@appendixsec Sample File with @code{@@include}
|
|
@cindex Sample @code{@@include} file
|
|
@cindex Include file sample
|
|
@cindex @code{@@include} file sample
|
|
|
|
Here is an example of a complete outer Texinfo file with @code{@@include} files
|
|
within it before running @code{texinfo-multiple-files-update}, which
|
|
would insert a main or master menu:@refill
|
|
|
|
@example
|
|
@group
|
|
\input texinfo @@c -*-texinfo-*-
|
|
@c %**start of header
|
|
@@setfilename include-example.info
|
|
@@settitle Include Example
|
|
@c %**end of header
|
|
@end group
|
|
|
|
@group
|
|
@@setchapternewpage odd
|
|
@@titlepage
|
|
@@sp 12
|
|
@@center @@titlefont@{Include Example@}
|
|
@@sp 2
|
|
@@center by Whom Ever
|
|
@end group
|
|
|
|
@group
|
|
@@page
|
|
@@vskip 0pt plus 1filll
|
|
Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
|
|
@@end titlepage
|
|
@end group
|
|
|
|
@group
|
|
@@ifinfo
|
|
@@node Top, First, (dir), (dir)
|
|
@@top Master Menu
|
|
@@end ifinfo
|
|
@end group
|
|
|
|
@group
|
|
@@include foo.texinfo
|
|
@@include bar.texinfo
|
|
@@include concept-index.texinfo
|
|
@end group
|
|
|
|
@group
|
|
@@summarycontents
|
|
@@contents
|
|
|
|
@@bye
|
|
@end group
|
|
@end example
|
|
|
|
An included file, such as @file{foo.texinfo}, might look like
|
|
this:@refill
|
|
|
|
@example
|
|
@group
|
|
@@node First, Second, , Top
|
|
@@chapter First Chapter
|
|
|
|
Contents of first chapter @dots{}
|
|
@end group
|
|
@end example
|
|
|
|
The full contents of @file{concept-index.texinfo} might be as simple as this:
|
|
|
|
@example
|
|
@group
|
|
@@node Concept Index, , Second, Top
|
|
@@unnumbered Concept Index
|
|
|
|
@@printindex cp
|
|
@end group
|
|
@end example
|
|
|
|
The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
|
|
Manual} is named @file{elisp.texi}. This outer file contains a master
|
|
menu with 417 entries and a list of 41 @code{@@include}
|
|
files.@refill
|
|
|
|
@node Include Files Evolution, , Sample Include File, Include Files
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Evolution of Include Files
|
|
|
|
When Info was first created, it was customary to create many small
|
|
Info files on one subject. Each Info file was formatted from its own
|
|
Texinfo source file. This custom meant that Emacs did not need to
|
|
make a large buffer to hold the whole of a large Info file when
|
|
someone wanted information; instead, Emacs allocated just enough
|
|
memory for the small Info file that contained the particular
|
|
information sought. This way, Emacs could avoid wasting memory.@refill
|
|
|
|
References from one file to another were made by referring to the file
|
|
name as well as the node name. (@xref{Other Info Files, , Referring to
|
|
Other Info Files}. Also, see @ref{Four and Five Arguments, ,
|
|
@code{@@xref} with Four and Five Arguments}.)@refill
|
|
|
|
Include files were designed primarily as a way to create a single,
|
|
large printed manual out of several smaller Info files. In a printed
|
|
manual, all the references were within the same document, so @TeX{}
|
|
could automatically determine the references' page numbers. The Info
|
|
formatting commands used include files only for creating joint
|
|
indices; each of the individual Texinfo files had to be formatted for
|
|
Info individually. (Each, therefore, required its own
|
|
@code{@@setfilename} line.)@refill
|
|
|
|
However, because large Info files are now split automatically, it is
|
|
no longer necessary to keep them small.@refill
|
|
|
|
Nowadays, multiple Texinfo files are used mostly for large documents,
|
|
such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
|
|
in which several different people write different sections of a
|
|
document simultaneously.@refill
|
|
|
|
In addition, the Info formatting commands have been extended to work
|
|
with the @code{@@include} command so as to create a single large Info
|
|
file that is split into smaller files if necessary. This means that
|
|
you can write menus and cross references without naming the different
|
|
Texinfo files.@refill
|
|
|
|
@node Headings, Catching Mistakes, Include Files, Top
|
|
@comment node-name, next, previous, up
|
|
@appendix Page Headings
|
|
@cindex Headings
|
|
@cindex Footings
|
|
@cindex Page numbering
|
|
@cindex Page headings
|
|
@cindex Formatting headings and footings
|
|
|
|
Most printed manuals contain headings along the top of every page
|
|
except the title and copyright pages. Some manuals also contain
|
|
footings. (Headings and footings have no meaning to Info, which is
|
|
not paginated.)@refill
|
|
|
|
@menu
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Headings Introduced, Heading Format, , Headings
|
|
@ifinfo
|
|
@heading Headings Introduced
|
|
@end ifinfo
|
|
|
|
Texinfo provides standard page heading formats for manuals that are printed
|
|
on one side of each sheet of paper and for manuals that are printed on
|
|
both sides of the paper. Usually, you will use one or other of these
|
|
formats, but you can specify your own format, if you wish.@refill
|
|
|
|
In addition, you can specify whether chapters should begin on a new
|
|
page, or merely continue the same page as the previous chapter; and if
|
|
chapters begin on new pages, you can specify whether they must be
|
|
odd-numbered pages.@refill
|
|
|
|
By convention, a book is printed on both sides of each sheet of paper.
|
|
When you open a book, the right-hand page is odd-numbered, and
|
|
chapters begin on right-hand pages---a preceding left-hand page is
|
|
left blank if necessary. Reports, however, are often printed on just
|
|
one side of paper, and chapters begin on a fresh page immediately
|
|
following the end of the preceding chapter. In short or informal
|
|
reports, chapters often do not begin on a new page at all, but are
|
|
separated from the preceding text by a small amount of whitespace.@refill
|
|
|
|
The @code{@@setchapternewpage} command controls whether chapters begin
|
|
on new pages, and whether one of the standard heading formats is used.
|
|
In addition, Texinfo has several heading and footing commands that you
|
|
can use to generate your own heading and footing formats.@refill
|
|
|
|
In Texinfo, headings and footings are single lines at the tops and
|
|
bottoms of pages; you cannot create multiline headings or footings.
|
|
Each header or footer line is divided into three parts: a left part, a
|
|
middle part, and a right part. Any part, or a whole line, may be left
|
|
blank. Text for the left part of a header or footer line is set
|
|
flushleft; text for the middle part is centered; and, text for the
|
|
right part is set flushright.@refill
|
|
|
|
@node Heading Format, Heading Choice, Headings Introduced, Headings
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Standard Heading Formats
|
|
|
|
Texinfo provides two standard heading formats, one for manuals printed
|
|
on one side of each sheet of paper, and the other for manuals printed
|
|
on both sides of the paper.
|
|
|
|
By default, nothing is specified for the footing of a Texinfo file,
|
|
so the footing remains blank.@refill
|
|
|
|
The standard format for single-sided printing consists of a header
|
|
line in which the left-hand part contains the name of the chapter, the
|
|
central part is blank, and the right-hand part contains the page
|
|
number.@refill
|
|
|
|
@need 950
|
|
A single-sided page looks like this:
|
|
|
|
@example
|
|
@group
|
|
_______________________
|
|
| |
|
|
| chapter page number |
|
|
| |
|
|
| Start of text ... |
|
|
| ... |
|
|
| |
|
|
|
|
@end group
|
|
@end example
|
|
|
|
The standard format for two-sided printing depends on whether the page
|
|
number is even or odd. By convention, even-numbered pages are on the
|
|
left- and odd-numbered pages are on the right. (@TeX{} will adjust the
|
|
widths of the left- and right-hand margins. Usually, widths are
|
|
correct, but during double-sided printing, it is wise to check that
|
|
pages will bind properly---sometimes a printer will produce output in
|
|
which the even-numbered pages have a larger right-hand margin than the
|
|
odd-numbered pages.)@refill
|
|
|
|
In the standard double-sided format, the left part of the left-hand
|
|
(even-numbered) page contains the page number, the central part is
|
|
blank, and the right part contains the title (specified by the
|
|
@code{@@settitle} command). The left part of the right-hand
|
|
(odd-numbered) page contains the name of the chapter, the central part
|
|
is blank, and the right part contains the page number.@refill
|
|
|
|
@need 750
|
|
Two pages, side by side as in an open book, look like this:@refill
|
|
|
|
@example
|
|
@group
|
|
_______________________ _______________________
|
|
| | | |
|
|
| page number title | | chapter page number |
|
|
| | | |
|
|
| Start of text ... | | More text ... |
|
|
| ... | | ... |
|
|
| | | |
|
|
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
The chapter name is preceded by the word @samp{Chapter}, the chapter
|
|
number and a colon. This makes it easier to keep track of where you
|
|
are in the manual.@refill
|
|
|
|
@node Heading Choice, Custom Headings, Heading Format, Headings
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Specifying the Type of Heading
|
|
|
|
@TeX{} does not begin to generate page headings for a standard Texinfo
|
|
file until it reaches the @code{@@end titlepage} command. Thus, the
|
|
title and copyright pages are not numbered. The @code{@@end
|
|
titlepage} command causes @TeX{} to begin to generate page headings
|
|
according to a standard format specified by the
|
|
@code{@@setchapternewpage} command that precedes the
|
|
@code{@@titlepage} section.@refill
|
|
|
|
@need 1000
|
|
There are four possibilities:@refill
|
|
|
|
@table @asis
|
|
@item No @code{@@setchapternewpage} command
|
|
Cause @TeX{} to specify the single-sided heading format, with chapters
|
|
on new pages. This is the same as @code{@@setchapternewpage on}.@refill
|
|
|
|
@item @code{@@setchapternewpage on}
|
|
Specify the single-sided heading format, with chapters on new pages.@refill
|
|
|
|
@item @code{@@setchapternewpage off}
|
|
Cause @TeX{} to start a new chapter on the same page as the last page of
|
|
the preceding chapter, after skipping some vertical whitespace. Also
|
|
cause @TeX{} to typeset for single-sided printing. (You can override
|
|
the headers format with the @code{@@headings double} command; see
|
|
@ref{headings on off, , The @code{@@headings} Command}.)@refill
|
|
|
|
@item @code{@@setchapternewpage odd}
|
|
Specify the double-sided heading format, with chapters on new pages.@refill
|
|
@end table
|
|
|
|
@noindent
|
|
Texinfo lacks an @code{@@setchapternewpage even} command.@refill
|
|
|
|
@node Custom Headings, , Heading Choice, Headings
|
|
@comment node-name, next, previous, up
|
|
@appendixsec How to Make Your Own Headings
|
|
|
|
You can use the standard headings provided with Texinfo or specify
|
|
your own.@refill
|
|
|
|
@c Following paragraph is verbose to prevent overfull hboxes.
|
|
Texinfo provides six commands for specifying headings and
|
|
footings. The @code{@@everyheading} command and
|
|
@code{@@everyfooting} command generate page headers and footers
|
|
that are the same for both even- and odd-numbered pages.
|
|
The @code{@@evenheading} command and @code{@@evenfooting}
|
|
command generate headers and footers for even-numbered
|
|
(left-hand) pages; and the @code{@@oddheading} command and
|
|
@code{@@oddfooting} command generate headers and footers for
|
|
odd-numbered (right-hand) pages.@refill
|
|
|
|
Write custom heading specifications in the Texinfo file immediately
|
|
after the @code{@@end titlepage} command. Enclose your specifications
|
|
between @code{@@iftex} and @code{@@end iftex} commands since the
|
|
@code{texinfo-format-buffer} command may not recognize them. Also,
|
|
you must cancel the predefined heading commands with the
|
|
@code{@@headings off} command before defining your own
|
|
specifications.@refill
|
|
|
|
@need 1000
|
|
Here is how to tell @TeX{} to place the chapter name at the left, the
|
|
page number in the center, and the date at the right of every header
|
|
for both even- and odd-numbered pages:@refill
|
|
|
|
@example
|
|
@group
|
|
@@iftex
|
|
@@headings off
|
|
@@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
|
|
@@end iftex
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
You need to divide the left part from the central part and the central
|
|
part from the right had part by inserting @samp{@@|} between parts.
|
|
Otherwise, the specification command will not be able to tell where
|
|
the text for one part ends and the next part begins.@refill
|
|
|
|
Each part can contain text or @@-commands. The text
|
|
is printed as if the part were within an ordinary paragraph in the
|
|
body of the page. The @@-commands replace
|
|
themselves with the page number, date, chapter name, or
|
|
whatever.@refill
|
|
|
|
@need 950
|
|
Here are the six heading and footing commands:@refill
|
|
|
|
@findex everyheading
|
|
@findex everyfooting
|
|
@table @code
|
|
@item @@everyheading @var{left} @@| @var{center} @@| @var{right}
|
|
@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
|
|
|
|
The `every' commands specify the format for both even- and odd-numbered
|
|
pages. These commands are for documents that are printed on one side
|
|
of each sheet of paper, or for documents in which you want symmetrical
|
|
headers or footers.@refill
|
|
|
|
@findex evenheading
|
|
@findex evenfooting
|
|
@findex oddheading
|
|
@findex oddfooting
|
|
@item @@evenheading @var{left} @@| @var{center} @@| @var{right}
|
|
@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
|
|
|
|
@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
|
|
@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
|
|
|
|
The `even' and `odd' commands specify the format for even-numbered
|
|
pages and odd-numbered pages. These commands are for books and
|
|
manuals that are printed on both sides of each sheet of paper.@refill
|
|
@end table
|
|
|
|
Use the @samp{@@this@dots{}} series of @@-commands to
|
|
provide the names of chapters
|
|
and sections and the page number. You can use the
|
|
@samp{@@this@dots{}} commands in the left, center, or right portions
|
|
of headers and footers, or anywhere else in a Texinfo file so long as
|
|
they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
|
|
|
|
@need 1000
|
|
Here are the @samp{@@this@dots{}} commands:@refill
|
|
|
|
@table @code
|
|
@findex thispage
|
|
@item @@thispage
|
|
Expands to the current page number.@refill
|
|
@c !!! Karl Berry says that `thissection' fails on page breaks.
|
|
@ignore
|
|
@item @@thissection
|
|
Expands to the name of the current section.@refill
|
|
@end ignore
|
|
|
|
@findex thischaptername
|
|
@item @@thischaptername
|
|
Expands to the name of the current chapter.@refill
|
|
|
|
@findex thischapter
|
|
@item @@thischapter
|
|
Expands to the number and name of the current
|
|
chapter, in the format `Chapter 1: Title'.@refill
|
|
|
|
@findex thistitle
|
|
@item @@thistitle
|
|
Expands to the name of the document, as specified by the
|
|
@code{@@settitle} command.@refill
|
|
|
|
@findex thisfile
|
|
@item @@thisfile
|
|
For @code{@@include} files only: expands to the name of the current
|
|
@code{@@include} file. If the current Texinfo source file is not an
|
|
@code{@@include} file, this command has no effect. This command does
|
|
@emph{not} provide the name of the current Texinfo source file unless
|
|
it is an @code{@@include} file. (@xref{Include Files}, for more
|
|
information about @code{@@include} files.)@refill
|
|
@end table
|
|
|
|
@noindent
|
|
You can also use the @code{@@today@{@}} command, which expands to the
|
|
current date, in `1 Jan 1900' format.@refill
|
|
@findex today
|
|
|
|
Other @@-commands and text are printed in a header or footer just as
|
|
if they were in the body of a page. It is useful to incorporate text,
|
|
particularly when you are writing drafts:@refill
|
|
|
|
@example
|
|
@group
|
|
@@iftex
|
|
@@headings off
|
|
@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
|
|
@@everyfooting @@| @@| Version: 0.27: @@today@{@}
|
|
@@end iftex
|
|
@end group
|
|
@end example
|
|
|
|
Beware of overlong titles: they may overlap another part of the
|
|
header or footer and blot it out.@refill
|
|
|
|
@node Catching Mistakes, Refilling Paragraphs, Headings, Top
|
|
@comment node-name, next, previous, up
|
|
@appendix Formatting Mistakes
|
|
@cindex Structure, catching mistakes in
|
|
@cindex Nodes, catching mistakes
|
|
@cindex Catching mistakes
|
|
@cindex Correcting mistakes
|
|
@cindex Mistakes, catching
|
|
@cindex Problems, catching
|
|
@cindex Debugging the Texinfo structure
|
|
|
|
Besides mistakes in the content of your documentation, there
|
|
are two kinds of mistake you can make with Texinfo: you can make mistakes
|
|
with @@-commands, and you can make mistakes with the structure of the
|
|
nodes and chapters.@refill
|
|
|
|
Emacs has two tools for catching the @@-command mistakes and two for
|
|
catching structuring mistakes.@refill
|
|
|
|
For finding problems with @@-commands, you can run @TeX{} or a region
|
|
formatting command on the region that has a problem; indeed, you can
|
|
run these commands on each region as you write it.@refill
|
|
|
|
For finding problems with the structure of nodes and chapters, you can use
|
|
@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
|
|
command and you can use the @kbd{M-x Info-validate} command.@refill
|
|
|
|
@menu
|
|
* makeinfo preferred:: @code{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 @code{texinfo-show-structure}.
|
|
* Using occur:: How to list all lines containing a pattern.
|
|
* Running Info-Validate:: How to find badly referenced nodes.
|
|
@end menu
|
|
|
|
@node makeinfo preferred, Debugging with Info, , Catching Mistakes
|
|
@ifinfo
|
|
@heading @code{makeinfo} Find Errors
|
|
@end ifinfo
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
The @code{makeinfo} program does an excellent job of catching errors
|
|
and reporting them---far better than either the
|
|
@code{texinfo-format-region} or the @code{texinfo-format-buffer}
|
|
command. In addition, the various functions for automatically
|
|
creating and updating node pointers and menus remove many
|
|
opportunities for human error.@refill
|
|
|
|
If you can, use the updating commands to create and insert pointers
|
|
and menus. These prevent many errors. Then use @code{makeinfo} (or
|
|
its Texinfo mode manifestations, @code{makeinfo-region} and
|
|
@code{makeinfo-buffer}) to format your file and check for other
|
|
errors. This is the best way to work with Texinfo. But if you
|
|
cannot use @code{makeinfo}, or your problem is very puzzling, then you
|
|
may want to use the tools described in this appendix.@refill
|
|
|
|
@node Debugging with Info, Debugging with TeX, makeinfo preferred, Catching Mistakes
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Catching Errors with Info Formatting
|
|
@cindex Catching errors with Info formatting
|
|
@cindex Debugging with Info formatting
|
|
|
|
After you have written part of a Texinfo file, you can use the
|
|
@code{texinfo-format-region} or the @code{makeinfo-region} command to
|
|
see whether the region formats properly.@refill
|
|
|
|
Most likely, however, you are reading this section because for some
|
|
reason you cannot use the @code{makeinfo-region} command; therefore, the
|
|
rest of this section presumes that you are using
|
|
@code{texinfo-format-region}.@refill
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
If you make a mistake with an @@-command,
|
|
@code{texinfo-format-region} will stop processing at or after the
|
|
error and display an error message. To see where in the buffer the
|
|
error occurred, switch to the @samp{*Info Region*} buffer; the cursor
|
|
will be in a position that is after the location of the error. Also,
|
|
the text will not be formatted after the place where the error
|
|
occurred (or more precisely, where it was detected).@refill
|
|
|
|
For example, if you accidentally end a menu with the command @code{@@end
|
|
menus} with an `s' on the end, instead of with @code{@@end menu}, you
|
|
will see an error message that says:@refill
|
|
|
|
@example
|
|
@@end menus is not handled by texinfo
|
|
@end example
|
|
|
|
@noindent
|
|
The cursor will stop at the point in the buffer where the error
|
|
occurs, or not long after it. The buffer will look like this:@refill
|
|
|
|
@example
|
|
@group
|
|
---------- Buffer: *Info Region* ----------
|
|
* Menu:
|
|
|
|
* Using texinfo-show-structure:: How to use
|
|
`texinfo-show-structure'
|
|
to catch mistakes.
|
|
* Running Info-Validate:: How to check for
|
|
unreferenced nodes.
|
|
@@end menus
|
|
@point{}
|
|
---------- Buffer: *Info Region* ----------
|
|
@end group
|
|
@end example
|
|
|
|
The @code{texinfo-format-region} command sometimes provides slightly
|
|
odd error messages. For example, the following cross reference fails to format:@refill
|
|
|
|
@example
|
|
(@@xref@{Catching Mistakes, for more info.)
|
|
@end example
|
|
|
|
@noindent
|
|
In this case, @code{texinfo-format-region} detects the missing closing
|
|
brace but displays a message that says @samp{Unbalanced parentheses}
|
|
rather than @samp{Unbalanced braces}. This is because the formatting
|
|
command looks for mismatches between braces as if they were
|
|
parentheses.@refill
|
|
|
|
Sometimes @code{texinfo-format-region} fails to detect mistakes. For
|
|
example, in the following, the closing brace is swapped with the
|
|
closing parenthesis:@refill
|
|
|
|
@example
|
|
(@@xref@{Catching Mistakes), for more info.@}
|
|
@end example
|
|
|
|
@noindent
|
|
Formatting produces:
|
|
@example
|
|
(*Note for more info.: Catching Mistakes)
|
|
@end example
|
|
|
|
The only way for you to detect this error is to realize that the
|
|
reference should have looked like this:@refill
|
|
|
|
@example
|
|
(*Note Catching Mistakes::, for more info.)
|
|
@end example
|
|
|
|
Incidentally, if you are reading this node in Info and type @kbd{f
|
|
@key{RET}} (@code{Info-follow-reference}), you will generate an error
|
|
message that says:
|
|
|
|
@example
|
|
No such node: "Catching Mistakes) The only way @dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
This is because Info perceives the example of the error as the first
|
|
cross reference in this node and if you type a @key{RET} immediately
|
|
after typing the Info @kbd{f} command, Info will attempt to go to the
|
|
referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
|
|
will complete the node name of the correctly written example and take
|
|
you to the `Catching Mistakes' node. (If you try this, you can return
|
|
from the `Catching Mistakes' node by typing @kbd{l}
|
|
(@code{Info-last}).)
|
|
|
|
@c !!! section on using Elisp debugger ignored.
|
|
@ignore
|
|
Sometimes @code{texinfo-format-region} will stop long after the
|
|
original error; this is because it does not discover the problem until
|
|
then. In this case, you will need to backtrack.@refill
|
|
|
|
@c menu
|
|
@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
|
|
@c end menu
|
|
|
|
@c node Using the Emacs Lisp Debugger
|
|
@c appendixsubsec Using the Emacs Lisp Debugger
|
|
@c index Using the Emacs Lisp debugger
|
|
@c index Emacs Lisp debugger
|
|
@c index Debugger, using the Emacs Lisp
|
|
|
|
If an error is especially elusive, you can turn on the Emacs Lisp
|
|
debugger and look at the backtrace; this tells you where in the
|
|
@code{texinfo-format-region} function the problem occurred. You can
|
|
turn on the debugger with the command:@refill
|
|
|
|
@example
|
|
M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
|
|
@end example
|
|
|
|
@noindent
|
|
and turn it off with
|
|
|
|
@example
|
|
M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
|
|
@end example
|
|
|
|
Often, when you are using the debugger, it is easier to follow what is
|
|
going on if you use the Emacs Lisp files that are not byte-compiled.
|
|
The byte-compiled sources send octal numbers to the debugger that may
|
|
look mysterious. To use the uncompiled source files, load
|
|
@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
|
|
command.@refill
|
|
|
|
The debugger will not catch an error if @code{texinfo-format-region}
|
|
does not detect one. In the example shown above,
|
|
@code{texinfo-format-region} did not find the error when the whole
|
|
list was formatted, but only when part of the list was formatted.
|
|
When @code{texinfo-format-region} did not find an error, the debugger
|
|
did not find one either. @refill
|
|
|
|
However, when @code{texinfo-format-region} did report an error, it
|
|
invoked the debugger. This is the backtrace it produced:@refill
|
|
|
|
@example
|
|
---------- Buffer: *Backtrace* ----------
|
|
Signalling: (search-failed "[@},]")
|
|
re-search-forward("[@},]")
|
|
(while ...)
|
|
(let ...)
|
|
texinfo-format-parse-args()
|
|
(let ...)
|
|
texinfo-format-xref()
|
|
funcall(texinfo-format-xref)
|
|
(if ...)
|
|
(let ...)
|
|
(if ...)
|
|
(while ...)
|
|
texinfo-format-scan()
|
|
(save-excursion ...)
|
|
(let ...)
|
|
texinfo-format-region(103370 103631)
|
|
* call-interactively(texinfo-format-region)
|
|
---------- Buffer: *Backtrace* ----------
|
|
@end example
|
|
|
|
The backtrace is read from the bottom up.
|
|
@code{texinfo-format-region} was called interactively; and it, in
|
|
turn, called various functions, including @code{texinfo-format-scan},
|
|
@code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
|
|
Inside the function @code{texinfo-format-parse-args}, the function
|
|
@code{re-search-forward} was called; it was this function that could
|
|
not find the missing right-hand brace.@refill
|
|
|
|
@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs
|
|
Manual}, for more information.@refill
|
|
@end ignore
|
|
|
|
@node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Catching Errors with @TeX{} Formatting
|
|
@cindex Catching errors with @TeX{} formatting
|
|
@cindex Debugging with @TeX{} formatting
|
|
|
|
You can also catch mistakes when you format a file with @TeX{}.@refill
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
Usually, you do this after you have run
|
|
@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
|
|
the same file, because @code{texinfo-format-buffer} sometimes displays
|
|
error messages that make more sense than @TeX{}. (@xref{Debugging
|
|
with Info}, for more information.)@refill
|
|
|
|
For example, @TeX{} was run on a Texinfo file, part of which is shown
|
|
here:@refill
|
|
|
|
@example
|
|
---------- Buffer: texinfo.texi ----------
|
|
name of the texinfo file as an extension. The
|
|
@@samp@{??@} are `wildcards' that cause the shell to
|
|
substitute all the raw index files. (@@xref@{sorting
|
|
indices, for more information about sorting
|
|
indices.)@@refill
|
|
---------- Buffer: texinfo.texi ----------
|
|
@end example
|
|
|
|
@noindent
|
|
(The cross reference lacks a closing brace.)
|
|
@TeX{} produced the following output, after which it stopped:@refill
|
|
|
|
@example
|
|
---------- Buffer: *texinfo-tex-shell* ----------
|
|
Runaway argument?
|
|
@{sorting indices, for more information about sorting
|
|
indices.) @@refill @@ETC.
|
|
! Paragraph ended before @@xref was complete.
|
|
<to be read again>
|
|
@@par
|
|
l.27
|
|
|
|
?
|
|
---------- Buffer: *texinfo-tex-shell* ----------
|
|
@end example
|
|
|
|
In this case, @TeX{} produced an accurate and
|
|
understandable error message:
|
|
|
|
@example
|
|
Paragraph ended before @@xref was complete.
|
|
@end example
|
|
|
|
@noindent
|
|
@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
|
|
@samp{l.27} means that @TeX{} detected the problem on line 27 of the
|
|
Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
|
|
circumstance.@refill
|
|
|
|
Unfortunately, @TeX{} is not always so helpful, and sometimes you must
|
|
truly be a Sherlock Holmes to discover what went wrong.@refill
|
|
|
|
In any case, if you run into a problem like this, you can do one of three
|
|
things.@refill
|
|
|
|
@enumerate
|
|
@item
|
|
You can tell @TeX{} to continue running and ignore just this error by
|
|
typing @key{RET} at the @samp{?} prompt.@refill
|
|
|
|
@item
|
|
You can tell @TeX{} to continue running and to ignore all errors as best
|
|
it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
|
|
|
|
This is often the best thing to do. However, beware: the one error
|
|
may produce a cascade of additional error messages as its consequences
|
|
are felt through the rest of the file. (To stop @TeX{} when it is
|
|
producing such an avalanche of error messages, type @kbd{C-d} (or
|
|
@kbd{C-c C-d}, if you are running a shell inside Emacs Version 18.))@refill
|
|
|
|
@item
|
|
You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
|
|
at the @samp{?} prompt.@refill
|
|
@end enumerate
|
|
|
|
Please note that if you are running @TeX{} inside Emacs, you need to
|
|
switch to the shell buffer and line at which @TeX{} offers the @samp{?}
|
|
prompt.@refill
|
|
|
|
Sometimes @TeX{} will format a file without producing error messages even
|
|
though there is a problem. This usually occurs if a command is not ended
|
|
but @TeX{} is able to continue processing anyhow. For example, if you fail
|
|
to end an itemized list with the @code{@@end itemize} command, @TeX{} will
|
|
write a @sc{dvi} file that you can print out. The only error message that
|
|
@TeX{} will give you is the somewhat mysterious comment that@refill
|
|
|
|
@example
|
|
(@@end occurred inside a group at level 1)
|
|
@end example
|
|
|
|
@noindent
|
|
However, if you print the @sc{dvi} file, you will find that the text
|
|
of the file that follows the itemized list is entirely indented as if
|
|
it were part of the last item in the itemized list. The error message
|
|
is the way @TeX{} says that it expected to find an @code{@@end}
|
|
command somewhere in the file; but that it could not determine where
|
|
it was needed.@refill
|
|
|
|
Another source of notoriously hard-to-find errors is a missing
|
|
@code{@@end group} command. If you ever are stumped by
|
|
incomprehensible errors, look for a missing @code{@@end group} command
|
|
first.@refill
|
|
|
|
If the Texinfo file lacks header lines,
|
|
@TeX{} may stop in the
|
|
beginning of its run and display output that looks like the following.
|
|
The @samp{*} indicates that @TeX{} is waiting for input.@refill
|
|
|
|
@example
|
|
This is TeX, Version 2.0 for Berkeley UNIX
|
|
(preloaded format=plain-cm 87.10.25)
|
|
(test.texinfo [1])
|
|
*
|
|
@end example
|
|
|
|
@noindent
|
|
In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
|
|
write the header lines in the Texinfo file and run the @TeX{} command
|
|
again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
|
|
instead of @samp{@@}; and in this circumstance, you are working
|
|
directly with @TeX{}, not with Texinfo.)@refill
|
|
|
|
@node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Using @code{texinfo-show-structure}
|
|
@cindex Showing the structure of a file
|
|
@findex texinfo-show-structure
|
|
|
|
It is not always easy to keep track of the nodes, chapters, sections, and
|
|
subsections of a Texinfo file. This is especially true if you are revising
|
|
or adding to a Texinfo file that someone else has written.@refill
|
|
|
|
In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
|
|
command lists all the lines that begin with the @@-commands that
|
|
specify the structure: @code{@@chapter}, @code{@@section},
|
|
@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
|
|
as prefix argument, if interactive),
|
|
the command also shows the @code{@@node} lines. The
|
|
@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
|
|
Texinfo mode, by default.@refill
|
|
|
|
The lines are displayed in a buffer called the @samp{*Occur*} buffer.
|
|
For example, when @code{texinfo-show-structure} was run on an earlier
|
|
version of this appendix, it produced the following:@refill
|
|
|
|
@smallexample
|
|
Lines matching "^@@\\(chapter \\|sect\\|sub\\|unnum\\|major\\|
|
|
heading \\|appendix\\)" in buffer texinfo.texi.
|
|
4:@@appendix Formatting Mistakes
|
|
52:@@appendixsec Catching Errors with Info Formatting
|
|
222:@@appendixsec Catching Errors with @@TeX@{@} Formatting
|
|
338:@@appendixsec Using @@code@{texinfo-show-structure@}
|
|
407:@@appendixsubsec Using @@code@{occur@}
|
|
444:@@appendixsec Finding Badly Referenced Nodes
|
|
513:@@appendixsubsec Running @@code@{Info-validate@}
|
|
573:@@appendixsubsec Splitting a File Manually
|
|
@end smallexample
|
|
|
|
This says that lines 4, 52, and 222 of @file{texinfo.texi} begin with
|
|
the @code{@@appendix}, @code{@@appendixsec}, and @code{@@appendixsec}
|
|
commands respectively. If you move your cursor into the @samp{*Occur*}
|
|
window, you can position the cursor over one of the lines and use the
|
|
@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
|
|
the corresponding spot in the Texinfo file. @xref{Other Repeating
|
|
Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
|
|
information about @code{occur-mode-goto-occurrence}.@refill
|
|
|
|
The first line in the @samp{*Occur*} window describes the @dfn{regular
|
|
expression} specified by @var{texinfo-heading-pattern}. This regular
|
|
expression is the pattern that @code{texinfo-show-structure} looks for.
|
|
@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
|
|
for more information.@refill
|
|
|
|
When you invoke the @code{texinfo-show-structure} command, Emacs will
|
|
display the structure of the whole buffer. If you want to see the
|
|
structure of just a part of the buffer, of one chapter, for example,
|
|
use the @kbd{C-x n} (@code{narrow-to-region}) command to mark the
|
|
region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
|
|
how the example used above was generated. (To see the whole buffer
|
|
again, use @kbd{C-x w} (@code{widen}).)@refill
|
|
|
|
If you call @code{texinfo-show-structure} with a prefix argument by
|
|
typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
|
|
@code{@@node} as well as the lines beginning with the @@-sign commands
|
|
for @code{@@chapter}, @code{@@section}, and the like.@refill
|
|
|
|
You can remind yourself of the structure of a Texinfo file by looking at
|
|
the list in the @samp{*Occur*} window; and if you have mis-named a node
|
|
or left out a section, you can correct the mistake.@refill
|
|
|
|
@node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Using @code{occur}
|
|
@cindex Occurrences, listing with @code{@@occur}
|
|
@findex occur
|
|
|
|
Sometimes the @code{texinfo-show-structure} command produces too much
|
|
information. Perhaps you want to remind yourself of the overall structure
|
|
of a Texinfo file, and are overwhelmed by the detailed list produced by
|
|
@code{texinfo-show-structure}. In this case, you can use the @code{occur}
|
|
command directly. To do this, type@refill
|
|
|
|
@example
|
|
@kbd{M-x occur}
|
|
@end example
|
|
|
|
@noindent
|
|
and then, when prompted, type a @dfn{regexp}, a regular expression for
|
|
the pattern you want to match. (@xref{Regexps, , Regular Expressions,
|
|
emacs, The GNU Emacs Manual}.) The @code{occur} command works from
|
|
the current location of the cursor in the buffer to the end of the
|
|
buffer. If you want to run @code{occur} on the whole buffer, place
|
|
the cursor at the beginning of the buffer.@refill
|
|
|
|
For example, to see all the lines that contain the word
|
|
@samp{@@chapter} in them, just type @samp{@@chapter}. This will
|
|
produce a list of the chapters. It will also list all the sentences
|
|
with @samp{@@chapter} in the middle of the line.@refill
|
|
|
|
If you want to see only those lines that start with the word
|
|
@samp{@@chapter}, type @samp{^@@chapter} when prompted by
|
|
@code{occur}. If you want to see all the lines that end with a word
|
|
or phrase, end the last word with a @samp{$}; for example,
|
|
@samp{catching mistakes$}. This can be helpful when you want to see
|
|
all the nodes that are part of the same chapter or section and
|
|
therefore have the same `Up' pointer.@refill
|
|
|
|
@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
|
|
for more information.@refill
|
|
|
|
@node Running Info-Validate, , Using occur, Catching Mistakes
|
|
@comment node-name, next, previous, up
|
|
@appendixsec Finding Badly Referenced Nodes
|
|
@findex Info-validate
|
|
@cindex Nodes, checking for badly referenced
|
|
@cindex Checking for badly referenced nodes
|
|
@cindex Looking for badly referenced nodes
|
|
@cindex Finding badly referenced nodes
|
|
@cindex Badly referenced nodes
|
|
|
|
You can use the @code{Info-validate} command to check whether any of
|
|
the `Next', `Previous', `Up' or other node pointers fail to point to a
|
|
node. This command checks that every node pointer points to an
|
|
existing node. The @code{Info-validate} command works only on Info
|
|
files, not on Texinfo files.@refill
|
|
|
|
The @code{makeinfo} program validates pointers automatically, so you
|
|
do not need to use the @code{Info-validate} command if you are using
|
|
@code{makeinfo}. You only may need to use @code{Info-validate} if you
|
|
are unable to run @code{makeinfo} and instead must create an Info file
|
|
using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
|
|
if you write an Info file from scratch.@refill
|
|
|
|
@menu
|
|
* Using Info-validate:: How to run @code{Info-validate}.
|
|
* Unsplit:: How to create an unsplit file.
|
|
* Tagifying:: How to tagify a file.
|
|
* Splitting:: How to split a file manually.
|
|
@end menu
|
|
|
|
@node Using Info-validate, Unsplit, , Running Info-Validate
|
|
@appendixsubsec Running @code{Info-validate}
|
|
@cindex Running @code{Info-validate}
|
|
@cindex Info validating a large file
|
|
@cindex Validating a large file
|
|
|
|
To use @code{Info-validate}, visit the Info file you wish to check and
|
|
type:@refill
|
|
|
|
@example
|
|
M-x Info-validate
|
|
@end example
|
|
|
|
@noindent
|
|
(Note that the @code{Info-validate} command requires an upper case
|
|
`I'. You may also need to create a tag table before running
|
|
@code{Info-validate}. @xref{Tagifying}.)@refill
|
|
|
|
If your file is valid, you will receive a message that says ``File appears
|
|
valid''. However, if you have a pointer that does not point to a node,
|
|
error messages will be displayed in a buffer called @samp{*problems in
|
|
info file*}.@refill
|
|
|
|
For example, @code{Info-validate} was run on a test file that contained
|
|
only the first node of this manual. One of the messages said:@refill
|
|
|
|
@example
|
|
In node "Overview", invalid Next: Texinfo Mode
|
|
@end example
|
|
|
|
@noindent
|
|
This meant that the node called @samp{Overview} had a `Next' pointer that
|
|
did not point to anything (which was true in this case, since the test file
|
|
had only one node in it).@refill
|
|
|
|
Now suppose we add a node named @samp{Texinfo Mode} to our test case
|
|
but we do not specify a `Previous' for this node. Then we will get
|
|
the following error message:@refill
|
|
|
|
@example
|
|
In node "Texinfo Mode", should have Previous: Overview
|
|
@end example
|
|
|
|
@noindent
|
|
This is because every `Next' pointer should be matched by a
|
|
`Previous' (in the node where the `Next' points) which points back.@refill
|
|
|
|
@code{Info-validate} also checks that all menu entries and cross references
|
|
point to actual nodes.@refill
|
|
|
|
Note that @code{Info-validate} requires a tag table and does not work
|
|
with files that have been split. (The @code{texinfo-format-buffer}
|
|
command automatically splits large files.) In order to use
|
|
@code{Info-validate} on a large file, you must run
|
|
@code{texinfo-format-buffer} with an argument so that it does not split
|
|
the Info file; and you must create a tag table for the unsplit
|
|
file.@refill
|
|
|
|
@node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
|
|
@comment node-name, next, previous, up
|
|
@appendixsubsec Creating an Unsplit File
|
|
@cindex Creating an unsplit file
|
|
@cindex Unsplit file creation
|
|
|
|
You can run @code{Info-validate} only on a single Info file that has a
|
|
tag table. The command will not work on the indirect subfiles that
|
|
are generated when a master file is split. If you have a large file
|
|
(longer than 70,000 bytes or so), you need to run the
|
|
@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
|
|
a way that it does not create indirect subfiles. You will also need
|
|
to create a tag table for the Info file. After you have done this,
|
|
you can run @code{Info-validate} and look for badly referenced
|
|
nodes.@refill
|
|
|
|
@c !!! broke into two paragraphs to prevent overfull hbox --bob 26 Mar 93
|
|
The first step is to create an unsplit Info file.
|
|
|
|
To prevent @code{texinfo-format-buffer} from splitting a Texinfo file
|
|
into smaller Info files, give a prefix to the @kbd{M-x
|
|
texinfo-format-buffer} command:@refill
|
|
|
|
@example
|
|
C-u M-x texinfo-format-buffer
|
|
@end example
|
|
|
|
@noindent
|
|
or else
|
|
|
|
@example
|
|
C-u C-c C-e C-b
|
|
@end example
|
|
|
|
@noindent
|
|
When you do this, Texinfo will not split the file and will not create
|
|
a tag table for it. @refill
|
|
@cindex Making a tag table manually
|
|
@cindex Tag table, making manually
|
|
|
|
@node Tagifying, Splitting, Unsplit, Running Info-Validate
|
|
@appendixsubsec Tagifying a File
|
|
|
|
After creating an unsplit Info file, you must create a tag table for
|
|
it. Visit the Info file you wish to tagify and type:@refill
|
|
|
|
@example
|
|
M-x Info-tagify
|
|
@end example
|
|
|
|
@noindent
|
|
(Note the upper case @key{I} in @code{Info-tagify}.) This creates an
|
|
Info file with a tag table that you can validate.@refill
|
|
|
|
The third step is to validate the Info file:@refill
|
|
|
|
@example
|
|
M-x Info-validate
|
|
@end example
|
|
|
|
@noindent
|
|
(Note the upper case @key{I} in @code{Info-validate}.)
|
|
In brief, the steps are:@refill
|
|
|
|
@example
|
|
@group
|
|
C-u M-x texinfo-format-buffer
|
|
M-x Info-tagify
|
|
M-x Info-validate
|
|
@end group
|
|
@end example
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
After you have validated the node structure, you will be able to rerun
|
|
@code{texinfo-format-buffer} in the normal way so it will construct a
|
|
tag table and split the file automatically, or you can make the tag
|
|
table and split the file manually.@refill
|
|
|
|
@node Splitting, , Tagifying, Running Info-Validate
|
|
@comment node-name, next, previous, up
|
|
@appendixsubsec Splitting a File Manually
|
|
@cindex Splitting an Info file manually
|
|
@cindex Info file, splitting manually
|
|
|
|
You should split a large file or else let the
|
|
@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
|
|
for you automatically. (Generally you will let one of the formatting
|
|
commands do this job for you. @xref{Create an Info File}.)@refill
|
|
|
|
The split-off files are called the indirect subfiles.@refill
|
|
|
|
Info files are split to save memory. With smaller files, Emacs does not
|
|
have make such a large buffer to hold the information.@refill
|
|
|
|
If an Info file has more than 30 nodes, you should also make a tag
|
|
table for it. @xref{Using Info-validate}, for information
|
|
about creating a tag table. (Again, tag tables are usually created
|
|
automatically by the formatting command; you only need to create a tag
|
|
table yourself if you are doing the job manually. Most likely, you
|
|
will do this for a large, unsplit file on which you have run
|
|
@code{Info-validate}.)@refill
|
|
|
|
@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
|
|
@ignore
|
|
Before running @code{Info-split}, you need to load the @code{info} library
|
|
into Emacs by giving the command @kbd{M-x load-library @key{RET} info
|
|
@key{RET}}.
|
|
@end ignore
|
|
|
|
Visit the Info file you wish to tagify and split and type the two
|
|
commands:@refill
|
|
|
|
@example
|
|
M-x Info-tagify
|
|
M-x Info-split
|
|
@end example
|
|
|
|
@noindent
|
|
(Note that the @samp{I} in @samp{Info} is upper case.)@refill
|
|
|
|
When you use the @code{Info-split} command, the buffer is modified into a
|
|
(small) Info file which lists the indirect subfiles. This file should be
|
|
saved in place of the original visited file. The indirect subfiles are
|
|
written in the same directory the original file is in, with names generated
|
|
by appending @samp{-} and a number to the original file name.@refill
|
|
|
|
The primary file still functions as an Info file, but it contains just
|
|
the tag table and a directory of subfiles.@refill
|
|
|
|
@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top
|
|
@comment node-name, next, previous, up
|
|
@appendix Refilling Paragraphs
|
|
@cindex Refilling paragraphs
|
|
@cindex Filling paragraphs
|
|
@findex refill
|
|
|
|
The @code{@@refill} command refills and, optionally, indents the first
|
|
line of a paragraph.@footnote{Perhaps the command should have been
|
|
called the @code{@@refillandindent} command, but @code{@@refill} is
|
|
shorter and the name was chosen before indenting was possible.} The
|
|
@code{@@refill} command is no longer important, but we describe it here
|
|
because you once needed it. You will see it in many old Texinfo
|
|
files.@refill
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
Without refilling, paragraphs containing long @@-constructs may look
|
|
bad after formatting because the formatter removes @@-commands and
|
|
shortens some lines more than others. In the past, neither
|
|
@code{texinfo-format-region} nor
|
|
@code{texinfo-format-buffer} refilled paragraphs
|
|
automatically. The @code{@@refill} command had to be written at the
|
|
end of every paragraph to cause these formatters to fill them. (Both
|
|
@TeX{} and @code{makeinfo} have always refilled paragraphs
|
|
automatically.) Now, all the Info formatters automatically fill and
|
|
indent those paragraphs that need to be filled and indented.@refill
|
|
|
|
@c !!! changed wording to prevent overfull hbox --bob 26 Mar 93
|
|
The @code{@@refill} command causes both the @code{texinfo-format-region}
|
|
command and the
|
|
@code{texinfo-format-buffer} command to refill a paragraph in the Info file
|
|
@emph{after} all the other processing has been done. For this reason,
|
|
you can not use @code{@@refill} with a paragraph containing either
|
|
@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
|
|
override those two commands.@refill
|
|
|
|
The @code{texinfo-format-region} and @code{texinfo-format-buffer}
|
|
commands now automatically append @code{@@refill} to the end of each
|
|
paragraph that should be filled. They do not append @code{@@refill} to
|
|
the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
|
|
and therefore do not refill or indent them.@refill
|
|
|
|
@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top
|
|
@comment node-name, next, previous, up
|
|
@appendix @@-Command Syntax
|
|
@cindex @@-command syntax
|
|
|
|
The character @samp{@@} is used to start special Texinfo commands.
|
|
(It has the same meaning that @samp{\} has in Plain@TeX{}.) Texinfo
|
|
has four types of @@-command:@refill
|
|
|
|
@table @asis
|
|
@item 1. Non-alphabetic commands.
|
|
These commands consist of an @@ followed by a punctuation mark or other
|
|
character that is not part of the alphabet. Non-alphabetic commands
|
|
are almost always part of the text within a paragraph, and never take
|
|
any argument. The two characters (@@ and the other one) are complete
|
|
in themselves; none is followed by braces. The non-alphabetic
|
|
commands are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@@},
|
|
@code{@@@{}, and @code{@@@}}.@refill
|
|
|
|
@item 2. Alphabetic commands that do not require arguments.
|
|
These commands start with @@ followed by a word followed by left- and
|
|
right-hand braces. These commands insert special symbols in the
|
|
document; they do not require arguments. For example,
|
|
@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
|
|
@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
|
|
and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
|
|
|
|
@item 3. Alphabetic commands that require arguments within braces.
|
|
These commands start with @@ followed by a letter or a word, followed by an
|
|
argument within braces. For example, the command @code{@@dfn} indicates
|
|
the introductory or defining use of a term; it is used as follows: @samp{In
|
|
Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
|
|
|
|
@item 4. Alphabetic commands that occupy an entire line.
|
|
These commands occupy an entire line. The line starts with @@,
|
|
followed by the name of the command (a word); for example, @code{@@center}
|
|
or @code{@@cindex}. If no argument is needed, the word is followed by
|
|
the end of the line. If there is an argument, it is separated from
|
|
the command name by a space. Braces are not used.@refill
|
|
@end table
|
|
|
|
@cindex Braces and argument syntax
|
|
Thus, the alphabetic commands fall into classes that have
|
|
different argument syntaxes. You cannot tell to which class a command
|
|
belongs by the appearance of its name, but you can tell by the
|
|
command's meaning: if the command stands for a glyph, it is in
|
|
class 2 and does not require an argument; if it makes sense to use the
|
|
command together with other text as part of a paragraph, the command
|
|
is in class 3 and must be followed by an argument in braces;
|
|
otherwise, it is in class 4 and uses the rest of the line as its
|
|
argument.@refill
|
|
|
|
The purpose of having a different syntax for commands of classes 3 and
|
|
4 is to make Texinfo files easier to read, and also to help the GNU
|
|
Emacs paragraph and filling commands work properly. There is only one
|
|
exception to this rule: the command @code{@@refill}, which is always
|
|
used at the end of a paragraph immediately following the final period
|
|
or other punctuation character. @code{@@refill} takes no argument and
|
|
does @emph{not} require braces. @code{@@refill} never confuses the
|
|
Emacs paragraph commands because it cannot appear at the beginning of
|
|
a line.@refill
|
|
|
|
@node Obtaining TeX, New Features, Command Syntax, Top
|
|
@appendix How to Obtain @TeX{}
|
|
@cindex Obtaining @TeX{}
|
|
@cindex @TeX{}, how to obtain
|
|
|
|
@c !!! Here is information about obtaining TeX. Update it whenever.
|
|
@c Last updated by RJC on 6 October 1992
|
|
@c based on message from elisabet@@.u.washington.edu
|
|
@TeX{} is freely redistributable. You can obtain @TeX{} for Unix
|
|
systems from the University of Washington for a distribution
|
|
fee.@refill
|
|
|
|
To order a full distribution, send $200.00 for a 1/2-inch 9-track 1600
|
|
bpi (@code{tar} or @code{cpio}) tape reel, or $210.00 for a 1/4-inch
|
|
4-track QIC-24 (@code{tar} or @code{cpio}) cartridge, to:@refill
|
|
|
|
@display
|
|
Northwest Computing Support Center
|
|
DR-10, Thomson Hall 35
|
|
University of Washington
|
|
Seattle, Washington 98195
|
|
@end display
|
|
|
|
@noindent
|
|
Please make checks payable to the University of Washington.@refill
|
|
|
|
Prepaid orders are preferred but purchase orders are acceptable;
|
|
however, purchase orders carry an extra charge of $10.00, to pay for
|
|
processing.@refill
|
|
|
|
Overseas sites: please add to the base cost $20.00 for shipment via
|
|
air parcel post, or $30.00 for shipment via courier.@refill
|
|
|
|
Please check with the Northwest Computing Support Center at the
|
|
University of Washington for current prices and formats:@refill
|
|
|
|
@example
|
|
@group
|
|
@r{telephone:} (206) 543-6259
|
|
@r{email:} elisabet@@u.washington.edu
|
|
@end group
|
|
@end example
|
|
|
|
@node New Features, Command and Variable Index, Obtaining TeX, Top
|
|
@appendix Second Edition Features
|
|
|
|
@tex
|
|
% Widen the space for the first column so three control-character
|
|
% strings fit in the first column. Switched back to default .8in
|
|
% value at end of chapter.
|
|
\global\tableindent=1.0in
|
|
@end tex
|
|
|
|
The second edition of the Texinfo manual describes more than 20 new
|
|
Texinfo mode commands and more than 50 previously undocumented Texinfo
|
|
@@-commands. This edition is more than twice the length of the first
|
|
edition.@refill
|
|
|
|
Here is a brief description of the new commands.@refill
|
|
|
|
@menu
|
|
* New Texinfo Mode Commands:: The updating commands are especially useful.
|
|
* New Commands:: Many newly described @@-commands.
|
|
@end menu
|
|
|
|
@node New Texinfo Mode Commands, New Commands, , New Features
|
|
@appendixsec New Texinfo Mode Commands
|
|
|
|
Texinfo mode provides commands and features especially designed for
|
|
working with Texinfo files. More than 20 new commands have been
|
|
added, including commands for automatically creating and updating
|
|
both nodes and menus. This is a tedious task when done by hand.@refill
|
|
|
|
The keybindings are intended to be somewhat mnemonic.@refill
|
|
|
|
@subheading Update all nodes and menus
|
|
|
|
The @code{texinfo-master-menu} command is the primary command:
|
|
|
|
@table @kbd
|
|
@item C-c C-u m
|
|
@itemx M-x texinfo-master-menu
|
|
Create or update a master menu.
|
|
With @kbd{C-u} as a prefix argument,
|
|
first create or update all nodes
|
|
and regular menus.
|
|
@end table
|
|
|
|
@subheading Update Pointers
|
|
|
|
@noindent
|
|
Create or update `Next', `Previous', and `Up' node pointers.@refill
|
|
|
|
@noindent
|
|
@xref{Updating Nodes and Menus}.
|
|
|
|
@table @kbd
|
|
@item C-c C-u C-n
|
|
@itemx M-x texinfo-update-node
|
|
Update a node.
|
|
|
|
@item C-c C-u C-e
|
|
@itemx M-x texinfo-every-node-update
|
|
Update every node in the buffer.
|
|
@end table
|
|
|
|
@subheading Update Menus
|
|
|
|
@noindent
|
|
Create or update menus.@refill
|
|
|
|
@noindent
|
|
@xref{Updating Nodes and Menus}.
|
|
|
|
@table @kbd
|
|
@item C-c C-u C-m
|
|
@itemx M-x texinfo-make-menu
|
|
Make or update a menu.
|
|
|
|
@item C-c C-u C-a
|
|
@itemx M-x texinfo-all-menus-update
|
|
Make or update all the menus in a buffer.
|
|
With @kbd{C-u} as a prefix argument,
|
|
first update all the nodes.
|
|
@end table
|
|
|
|
@subheading Insert Title as Description
|
|
|
|
@noindent
|
|
Insert a node's chapter or section title in the space for the
|
|
description in a menu entry line; position point so you can edit the
|
|
insert. (This command works somewhat differently than the other
|
|
insertion commands, which insert only a predefined string.)@refill
|
|
|
|
@noindent
|
|
@xref{Inserting, Inserting Frequently Used Commands}.
|
|
|
|
@table @kbd
|
|
@item C-c C-c C-d
|
|
Insert title.
|
|
@end table
|
|
|
|
@subheading Format for Info
|
|
|
|
@noindent
|
|
Provide keybindings both for the Info formatting commands that are
|
|
written in Emacs Lisp and for @code{makeinfo} that is written in
|
|
C.@refill
|
|
|
|
@noindent
|
|
@xref{Info Formatting}.
|
|
|
|
@noindent
|
|
Use the Emacs lisp @code{texinfo-format@dots{}} commands:
|
|
|
|
@table @kbd
|
|
@item C-c C-e C-r
|
|
Format the region.
|
|
|
|
@item C-c C-e C-b
|
|
Format the buffer.
|
|
@end table
|
|
|
|
@noindent
|
|
Use @code{makeinfo}:
|
|
|
|
@table @kbd
|
|
@item C-c C-m C-r
|
|
Format the region.
|
|
|
|
@item C-c C-m C-b
|
|
Format the buffer.
|
|
|
|
@item C-c C-m C-l
|
|
Recenter the @code{makeinfo} output buffer.
|
|
|
|
@item C-c C-m C-k
|
|
Kill the @code{makeinfo} formatting job.
|
|
@end table
|
|
|
|
@subheading Typeset and Print
|
|
|
|
@noindent
|
|
Typeset and print Texinfo documents from within Emacs.@refill
|
|
|
|
@ifinfo
|
|
@noindent
|
|
@xref{Printing}.
|
|
@end ifinfo
|
|
@iftex
|
|
@noindent
|
|
@xref{Printing, , Formatting and Printing}.
|
|
@end iftex
|
|
|
|
@table @kbd
|
|
@item C-c C-t C-r
|
|
Run @TeX{} on the region.
|
|
|
|
@item C-c C-t C-b
|
|
Run @TeX{} on the buffer.
|
|
|
|
@item C-c C-t C-i
|
|
Run @code{texindex}.
|
|
|
|
@item C-c C-t C-p
|
|
Print the @sc{dvi} file.
|
|
|
|
@item C-c C-t C-q
|
|
Show the print queue.
|
|
|
|
@item C-c C-t C-d
|
|
Delete a job from the print queue.
|
|
|
|
@item C-c C-t C-k
|
|
Kill the current @TeX{} formatting job.
|
|
|
|
@item C-c C-t C-x
|
|
Quit a currently stopped @TeX{} formatting job.
|
|
|
|
@item C-c C-t C-l
|
|
Recenter the output buffer.
|
|
@end table
|
|
|
|
@subheading Other Updating Commands
|
|
|
|
@noindent
|
|
The ``other updating commands'' do not have standard keybindings because
|
|
they are used less frequently.@refill
|
|
|
|
@noindent
|
|
@xref{Other Updating Commands}.
|
|
|
|
@table @kbd
|
|
@item M-x texinfo-insert-node-lines
|
|
Insert missing @code{@@node} lines using
|
|
section titles as node names.
|
|
|
|
@item M-x texinfo-multiple-files-update
|
|
Update a multi-file document.
|
|
With a numeric prefix, such as @kbd{C-u 8},
|
|
update @strong{every} pointer and
|
|
menu in @strong{all} the files and
|
|
then insert a master menu.
|
|
|
|
@item M-x texinfo-indent-menu-description
|
|
Indent descriptions in menus.
|
|
|
|
@item M-x texinfo-sequential-node-update
|
|
Insert node pointers in strict sequence.
|
|
@end table
|
|
|
|
@node New Commands, , New Texinfo Mode Commands, New Features
|
|
@appendixsec New Texinfo @@-Commands
|
|
|
|
The second edition of the Texinfo manual describes more than 50
|
|
commands that were not described in the first edition. A third or so
|
|
of these commands existed in Texinfo but were not documented in the
|
|
manual; the others are new. Here is a listing, with brief
|
|
descriptions of them:@refill
|
|
|
|
@subheading Indexing
|
|
|
|
@noindent
|
|
Create your own index, and merge indices.@refill
|
|
|
|
@noindent
|
|
@xref{Indices}.
|
|
|
|
@table @kbd
|
|
@item @@defindex @var{index-name}
|
|
Define a new index and its indexing command.
|
|
See also the @code{@@defcodeindex} command.
|
|
|
|
@c written verbosely to avoid overful hbox
|
|
@item @@synindex @var{from-index} @var{into-index}
|
|
Merge the @var{from-index} index into the @var{into-index} index.
|
|
See also the @code{@@syncodeindex} command.
|
|
@end table
|
|
|
|
@subheading Definitions
|
|
|
|
@noindent
|
|
Describe functions, variables, macros,
|
|
commands, user options, special forms, and other such artifacts in a
|
|
uniform format.@refill
|
|
|
|
@noindent
|
|
@xref{Definition Commands}.
|
|
|
|
@table @kbd
|
|
@item @@deffn @var{category} @var{name} @var{arguments}@dots{}
|
|
Format a description for functions, interactive
|
|
commands, and similar entities.
|
|
|
|
@item @@defvr, @@defop, @dots{}
|
|
15 other related commands.
|
|
@end table
|
|
|
|
@subheading Glyphs
|
|
|
|
@noindent
|
|
Indicate the results of evaluation, expansion,
|
|
printed output, an error message, equivalence of expressions, and the
|
|
location of point.@refill
|
|
|
|
@noindent
|
|
@xref{Glyphs}.
|
|
|
|
@table @kbd
|
|
@item @@equiv@{@}
|
|
@itemx @equiv{}
|
|
Equivalence:
|
|
|
|
@item @@error@{@}
|
|
@itemx @error{}
|
|
Error message
|
|
|
|
@item @@expansion@{@}
|
|
@itemx @expansion{}
|
|
Macro expansion
|
|
|
|
@item @@point@{@}
|
|
@itemx @point{}
|
|
Position of point
|
|
|
|
@item @@print@{@}
|
|
@itemx @print{}
|
|
Printed output
|
|
|
|
@item @@result@{@}
|
|
@itemx @result{}
|
|
Result of an expression
|
|
@end table
|
|
|
|
@subheading Page Headings
|
|
|
|
@noindent
|
|
Customize page headings.
|
|
|
|
@noindent
|
|
@xref{Headings}.
|
|
|
|
@table @kbd
|
|
@item @@headings @var{on-off-single-double}
|
|
Headings on or off, single, or double-sided.
|
|
|
|
@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
|
|
Footings for even-numbered (left-hand) pages.
|
|
|
|
@item @@evenheading, @@everyheading, @@oddheading, @dots{}
|
|
Five other related commands.
|
|
|
|
@item @@thischapter
|
|
Insert name of chapter and chapter number.
|
|
|
|
@item @@thischaptername, @@thisfile, @@thistitle, @@thispage
|
|
Related commands.
|
|
@end table
|
|
|
|
@subheading Formatting
|
|
|
|
@noindent
|
|
Format blocks of text.
|
|
|
|
@noindent
|
|
@xref{Quotations and Examples}, and@*
|
|
@ref{Lists and Tables, , Making Lists and Tables}.
|
|
|
|
@table @kbd
|
|
@item @@cartouche
|
|
Draw rounded box surrounding text (not in Info).
|
|
|
|
@item @@enumerate @var{optional-arg}
|
|
Enumerate a list with letters or numbers.
|
|
|
|
@item @@exdent @var{line-of-text}
|
|
Remove indentation.
|
|
|
|
@item @@flushleft
|
|
Left justify.
|
|
|
|
@item @@flushright
|
|
Right justify.
|
|
|
|
@item @@format
|
|
Do not narrow nor change font.
|
|
|
|
@item @@ftable @var{formatting-command}
|
|
@itemx @@vtable @var{formatting-command}
|
|
Two-column table with indexing.
|
|
|
|
@item @@lisp
|
|
For an example of Lisp code.
|
|
|
|
@item @@smallexample
|
|
@itemx @@smalllisp
|
|
Like @@table and @@lisp @r{but for} @@smallbook.
|
|
@end table
|
|
|
|
@subheading Conditionals
|
|
|
|
@noindent
|
|
Conditionally format text.
|
|
|
|
@noindent
|
|
@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
|
|
|
|
@table @kbd
|
|
@item @@set @var{flag} [@var{string}]
|
|
Set a flag. Optionally, set value
|
|
of @var{flag} to @var{string}.
|
|
|
|
@item @@clear @var{flag}
|
|
Clear a flag.
|
|
|
|
@item @@value@{@var{flag}@}
|
|
Replace with value to which @var{flag} is set.
|
|
|
|
@item @@ifset @var{flag}
|
|
Format, if @var{flag} is set.
|
|
|
|
@item @@ifclear @var{flag}
|
|
Ignore, if @var{flag} is set.
|
|
@end table
|
|
|
|
@subheading @@heading series for Titles
|
|
|
|
@noindent
|
|
Produce unnumbered headings that do not appear in a table of contents.
|
|
|
|
@noindent
|
|
@xref{Structuring}.
|
|
|
|
@table @kbd
|
|
@item @@heading @var{title}
|
|
Unnumbered section-like heading not listed
|
|
in the table of contents of a printed manual.
|
|
|
|
@item @@chapheading, @@majorheading, @@subheading, @@subsubheading
|
|
Related commands.
|
|
@end table
|
|
|
|
@need 1000
|
|
@subheading Font commands
|
|
|
|
@need 1000
|
|
@noindent
|
|
@xref{Smallcaps}, and @*
|
|
@ref{Fonts}.
|
|
|
|
@table @kbd
|
|
@item @@r@{@var{text}@}
|
|
Print in roman font.
|
|
|
|
@item @@sc@{@var{text}@}
|
|
Print in @sc{small caps} font.
|
|
@end table
|
|
|
|
@subheading Miscellaneous
|
|
|
|
@noindent
|
|
See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
|
|
see @ref{Overfull hboxes},@*
|
|
see @ref{Footnotes},@*
|
|
see @ref{dmn, , Format a Dimension},@*
|
|
see @ref{minus, , Inserting a Minus Sign},@*
|
|
see @ref{paragraphindent, , Paragraph Indenting},@*
|
|
see @ref{Cross Reference Commands},@*
|
|
see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
|
|
see @ref{Custom Headings, , How to Make Your Own Headings}.
|
|
|
|
@need 700
|
|
@table @kbd
|
|
@item @@author @var{author}
|
|
Typeset author's name.
|
|
|
|
@item @@finalout
|
|
Produce cleaner printed output.
|
|
|
|
@item @@footnotestyle
|
|
Specify footnote style.
|
|
|
|
@item @@dmn@{@var{dimension}@}
|
|
Format a dimension.
|
|
|
|
@item @@minus@{@}
|
|
Generate a minus sign.
|
|
|
|
@item @@paragraphindent
|
|
Specify paragraph indentation.
|
|
|
|
@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
|
|
Make a reference. In the printed manual, the
|
|
reference does not start with the word `see'.
|
|
|
|
@item @@title @var{title}
|
|
Typeset @var{title} in the alternative
|
|
title page format.
|
|
|
|
@item @@subtitle @var{subtitle}
|
|
Typeset @var{subtitle} in the alternative
|
|
title page format.
|
|
|
|
@item @@today@{@}
|
|
Insert the current date.
|
|
@end table
|
|
@tex
|
|
% Switch width of first column of tables back to default value
|
|
\global\tableindent=.8in
|
|
@end tex
|
|
|
|
@node Command and Variable Index, Concept Index, New Features, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Command and Variable Index
|
|
|
|
This is an alphabetical list of all the @@-commands and several
|
|
variables. To make the list easier to use, the commands are listed
|
|
without their preceding @samp{@@}.@refill
|
|
|
|
@printindex fn
|
|
|
|
@node Concept Index, , Command and Variable Index, Top
|
|
@comment node-name, next, previous, up
|
|
@unnumbered Concept Index
|
|
|
|
@printindex cp
|
|
|
|
@summarycontents
|
|
@contents
|
|
@bye
|