12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106 |
- \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--2022 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.
|