1106 lines
41 KiB
Text
1106 lines
41 KiB
Text
\input texinfo.tex @c -*-texinfo-*-
|
|
@comment %**start of header
|
|
@setfilename texinfo
|
|
@settitle Texinfo @value{edition}
|
|
@syncodeindex vr fn
|
|
@footnotestyle separate
|
|
@paragraphindent 2
|
|
@smallbook
|
|
@comment %**end of header
|
|
|
|
@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.
|
|
@set smallbook
|
|
@c @@clear smallbook
|
|
|
|
@ignore
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* Texinfo: (texinfo). The documentation format for the GNU Project.
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
@end ignore
|
|
|
|
@set edition 2.21
|
|
@set update-date 7 June 1995
|
|
@set update-month June 1995
|
|
|
|
@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 command, 5 December 1993:
|
|
@c
|
|
@c nwnode (Same as node, but no warnings; for `makeinfo'.)
|
|
|
|
@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-2016 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
|
|
|
|
@shorttitlepage Texinfo
|
|
|
|
@titlepage
|
|
@c use the new format for titles
|
|
@title Texinfo
|
|
@subtitle The GNU Documentation Format
|
|
@subtitle Edition @value{edition}, for Texinfo Version Three
|
|
@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, 1995, 2010, 2011
|
|
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 @*
|
|
59 Temple Place Suite 330, @*
|
|
Boston, MA 02111-1307 USA @*
|
|
Printed copies are available for $15 each.@*
|
|
ISBN 1-882114-63-9
|
|
@c ISBN number 1-882114-63-9 is for edition 2.20 of 28 February 1995
|
|
|
|
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 Three.
|
|
@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.
|
|
* Raise/lower sections:: How to change commands' hierarchical level.
|
|
|
|
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.
|
|
* Customized Highlighting:: How to define highlighting commands.
|
|
|
|
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.
|
|
* math:: How to format a mathematical expression.
|
|
|
|
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.
|
|
|
|
Footnotes
|
|
|
|
* Footnote Commands:: How to write a footnote in Texinfo.
|
|
* Footnote Styles:: Controlling how footnotes appear in Info.
|
|
|
|
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.
|
|
* Format with tex/texindex:: How to format in a shell.
|
|
* Format with texi2dvi:: A simpler way to use the shell.
|
|
* Print with lpr:: How to print.
|
|
* 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
|
|
|
|
@c ************************************************************************
|
|
|
|
|
|
|
|
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename psim.info
|
|
@settitle PSIM
|
|
@setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
|
|
|
|
@ifinfo
|
|
This file documents the program PSIM.
|
|
|
|
Copyright (C) 1994-1996, Andrew Cagney.
|
|
|
|
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, subject to the terms
|
|
of the GNU General Public License, which includes the provision 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.
|
|
@end ifinfo
|
|
|
|
|
|
@titlepage
|
|
@title PSIM
|
|
@subtitle Model of the PowerPC Environments
|
|
@author Andrew Cagney
|
|
|
|
@page
|
|
@vskip Opt plus ifill
|
|
Copyright @copyright{} 1994-1996, Andrew Cagney
|
|
|
|
This is the first edition of the PSIM manual and is consistent with PSIM
|
|
version 1.0.
|
|
|
|
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, subject to the terms
|
|
of the GNU General Public License, which includes the provision 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.
|
|
@end titlepage
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Copying:: Your rights and freedoms.
|
|
* First Chappeter:: Getting started ....
|
|
* Second Chapter:: Getting finished ....
|
|
|
|
|
|
@end menu
|
|
|
|
|
|
PSIM is a program written in extended ANSI-C that implements an
|
|
instruction level simulation of the PowerPC environment. It is freely
|
|
available in source code form under the terms of the GNU General
|
|
Public License (version 3 or later).
|
|
|
|
The PowerPC Architecture is described as having three levels of
|
|
compliance:
|
|
|
|
UEA - User Environment Architecture
|
|
VEA - Virtual Environment Architecture
|
|
OEA - Operating Environment Architecture
|
|
|
|
PSIM both implements all three levels of the PowerPC and includes (for
|
|
each level) a corresponding simulated run-time environment.
|
|
|
|
In addition, PSIM, to the execution unit level, models the performance
|
|
of most of the current PowerPC implementations (contributed by Michael
|
|
Meissner). This detailed performance monitoring (unlike many other
|
|
simulators) resulting in only a relatively marginal reduction in the
|
|
simulators performance.
|
|
|
|
|
|
A description of how to build PSIM is contained in the file:
|
|
|
|
ftp://ftp.ci.com.au/pub/psim/INSTALL
|
|
or ftp://cambridge.cygnus.com/pub/psim/INSTALL
|
|
|
|
while an overview of how to use PSIM is in:
|
|
|
|
ftp://ftp.ci.com.au/pub/psim/RUN
|
|
or ftp://cambridge.cygnus.com/pub/psim/RUN
|
|
|
|
This file is found in:
|
|
|
|
ftp://ftp.ci.com.au/pub/psim/README
|
|
or ftp://cambridge.cygnus.com/pub/psim/README
|
|
|
|
|
|
Thanks goes firstly to:
|
|
|
|
Corinthian Engineering Pty Ltd
|
|
Cygnus Support
|
|
Highland Logic Pty Ltd
|
|
|
|
who provided the resources needed for making this software available
|
|
on the Internet.
|
|
|
|
More importantly I'd like to thank the following individuals who each
|
|
contributed in their own unique way:
|
|
|
|
Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam,
|
|
Michael Meissner, Bob Mercier, Richard Perini, Dale Rahn,
|
|
Richard Stallman, Mitchele Walker
|
|
|
|
|
|
Andrew Cagney
|
|
Feb, 1995
|
|
|
|
|
|
----------------------------------------------------------------------
|
|
|
|
|
|
What features does PSIM include?
|
|
|
|
Monitoring and modeling
|
|
|
|
PSIM includes (thanks to Michael Meissner)
|
|
a detailed model of most of the PowerPC
|
|
implementations to the functional unit level.
|
|
|
|
|
|
SMP
|
|
|
|
The PowerPC ISA defines SMP synchronizing instructions.
|
|
This simulator implements a limited, but functional,
|
|
subset of the PowerPC synchronization instructions
|
|
behaviour. Programs that restrict their synchronization
|
|
primitives to those that work with this functional
|
|
sub-set (eg P() and V()) are able to run on the SMP
|
|
version of PSIM.
|
|
|
|
People intending to use this system should study
|
|
the code implementing the lwarx instruction.
|
|
|
|
ENDIAN SUPPORT
|
|
|
|
PSIM implements the PowerPC's big and little (xor
|
|
endian) modes and correctly simulates code that
|
|
switches between these two modes.
|
|
|
|
In addition, psim can model a true little-endian
|
|
machine.
|
|
|
|
ISA (Instruction Set Architecture) models
|
|
|
|
PSIM includes a model of the UEA, VEA and OEA. This
|
|
includes the time base registers (VEA) and HTAB
|
|
and BATS (OEA).
|
|
|
|
In addition, a preliminary model of the 64 bit
|
|
PowerPC architecture is implemented.
|
|
|
|
IO Hardware
|
|
|
|
PSIM's internals are based around the concept
|
|
of a Device Tree. This tree intentionally
|
|
resembles that of the Device Tree found in
|
|
OpenBoot firmware. PSIM is flexible enough
|
|
to allow the user to fully configure this device
|
|
tree (and consequently the hardware model) at
|
|
run time.
|
|
|
|
Run-time environments:
|
|
|
|
PSIM's UEA model includes emulation for BSD
|
|
based UNIX system calls.
|
|
|
|
PSIM's OEA model includes emulation of either:
|
|
|
|
o OpenBoot client interface
|
|
|
|
o MOTO's BUG interface.
|
|
|
|
|
|
Floating point
|
|
|
|
Preliminary support for floating point is included.
|
|
|
|
|
|
Who would be interested in PSIM?
|
|
|
|
o the curious
|
|
|
|
Using psim, gdb, gcc and binutils the curious
|
|
user can construct an environment that allows
|
|
them to play with PowerPC Environment without
|
|
the need for real hardware.
|
|
|
|
|
|
o the analyst
|
|
|
|
PSIM includes many (contributed) monitoring
|
|
features which (unlike many other simulators)
|
|
do not come with a great penalty in performance.
|
|
|
|
Thus the performance analyst is able to use
|
|
this simulator to analyse the performance of
|
|
the system under test.
|
|
|
|
If PSIM doesn't monitor a components of interest,
|
|
the source code is freely available, and hence
|
|
there is no hinderance to changing things
|
|
to meet a specific analysts needs.
|
|
|
|
|
|
o the serious SW developer
|
|
|
|
PSIM models all three levels of the PowerPC
|
|
Architecture: UEA, VEA and OEA. Further,
|
|
the internal design is such that PSIM can
|
|
be extended to support additional requirements.
|
|
|
|
|
|
What performance analysis measurements can PSIM perform?
|
|
|
|
Below is the output from a recent analysis run
|
|
(contributed by Michael Meissner):
|
|
|
|
For the following program:
|
|
|
|
long
|
|
simple_rand ()
|
|
{
|
|
static unsigned long seed = 47114711;
|
|
unsigned long this = seed * 1103515245 + 12345;
|
|
seed = this;
|
|
/* cut-cut-cut - see the file RUN.psim */
|
|
}
|
|
|
|
Here is the current output generated with the -I switch on a P90
|
|
(the compiler used is the development version of GCC with a new
|
|
scheduler replacing the old one):
|
|
|
|
CPU #1 executed 41,994 AND instructions.
|
|
CPU #1 executed 519,785 AND Immediate instructions.
|
|
.
|
|
.
|
|
.
|
|
CPU #1 executed 1 System Call instruction.
|
|
CPU #1 executed 207,746 XOR instructions.
|
|
|
|
CPU #1 executed 23,740,856 cycles.
|
|
CPU #1 executed 10,242,780 stalls waiting for data.
|
|
CPU #1 executed 1 stall waiting for a function unit.
|
|
.
|
|
.
|
|
.
|
|
CPU #1 executed 3,136,229 branch functional unit instructions.
|
|
CPU #1 executed 16,949,396 instructions that were accounted for in timing info.
|
|
CPU #1 executed 871,920 data reads.
|
|
CPU #1 executed 971,926 data writes.
|
|
CPU #1 executed 221 icache misses.
|
|
CPU #1 executed 16,949,396 instructions in total.
|
|
|
|
Simulator speed was 250,731 instructions/second
|
|
|
|
|
|
What motivated PSIM?
|
|
|
|
As an idea, psim was first discussed seriously during mid
|
|
1994. At that time its main objectives were:
|
|
|
|
|
|
o good performance
|
|
|
|
Many simulators loose out by only providing
|
|
a binary interface to the internals. This
|
|
interface eventually becomes a bottle neck
|
|
in the simulators performance.
|
|
|
|
It was intended that PSIM would avoid this
|
|
problem by giving the user access to the
|
|
full source code.
|
|
|
|
Further, by exploiting the power of modern
|
|
compilers it was hoped that PSIM would achieve
|
|
good performance with out having to compromise
|
|
its internal design.
|
|
|
|
|
|
o practical portability
|
|
|
|
Rather than try to be portable to every
|
|
C compiler on every platform, it was decided
|
|
that PSIM would restrict its self to supporting
|
|
ANSI compilers that included the extension
|
|
of a long long type.
|
|
|
|
GCC is one such compiler, consequently PSIM
|
|
should be portable to any machine running GCC.
|
|
|
|
|
|
o flexibility in its design
|
|
|
|
PSIM should allow the user to select the
|
|
features required and customise the build
|
|
accordingly. By having the source code,
|
|
the compiler is able to eliminate any un
|
|
used features of the simulator.
|
|
|
|
After all, let the compiler do the work.
|
|
|
|
|
|
o SMP
|
|
|
|
A model that allowed the simulation of
|
|
SMP platforms with out the large overhead
|
|
often encountered with such models.
|
|
|
|
|
|
PSIM achieves each of these objectives.
|
|
|
|
|
|
Is PSIM PowerPC Platform (PPCP) (nee CHRP) Compliant?
|
|
|
|
No.
|
|
|
|
Among other things it does not have an Apple ROM socket.
|
|
|
|
|
|
Could PSIM be extended so that it models a CHRP machine?
|
|
|
|
Yes.
|
|
|
|
PSIM has been designed with the CHRP spec in mind. To model
|
|
a CHRP desktop the following would need to be added:
|
|
|
|
o An apple ROM socket :-)
|
|
|
|
o Model of each of the desktop IO devices
|
|
|
|
o An OpenPIC device.
|
|
|
|
o RTAS (Run Time Abstraction Services).
|
|
|
|
o A fully populated device tree.
|
|
|
|
|
|
Is the source code available?
|
|
|
|
Yes.
|
|
|
|
The source code to PSIM is available under the terms of
|
|
the GNU Public Licence. This allows you to distribute
|
|
the source code for free but with certain conditions.
|
|
|
|
See the file:
|
|
|
|
ftp://archie.au/gnu/COPYING
|
|
|
|
For details of the terms and conditions.
|
|
|
|
|
|
Where do I send bugs or report problems?
|
|
|
|
There is a mailing list (subscribe through majordomo@ci.com.au) at:
|
|
|
|
powerpc-psim@ci.com.au
|
|
|
|
If I get the ftp archive updated I post a note to that mailing list.
|
|
In addition your welcome to send bugs or problems either to me or to
|
|
that e-mail list.
|
|
|
|
This list currently averages zero articles a day.
|
|
|
|
|
|
Does PSIM have any limitations or problems?
|
|
|
|
PSIM can't run rs6000/AIX binaries - At present PSIM can only
|
|
simulate static executables. Since an AIX executable is
|
|
never static, PSIM is unable to simulate its execution.
|
|
|
|
PSIM is still under development - consequently there are going
|
|
to be bugs.
|
|
|
|
See the file BUGS (included in the distribution) for any
|
|
other outstanding issues.
|
|
|