Commit | Line | Data |
---|---|---|
c906108c SS |
1 | \input texinfo.tex @c -*-texinfo-*- |
2 | @comment %**start of header | |
3 | @setfilename texinfo | |
4 | @settitle Texinfo @value{edition} | |
5 | @syncodeindex vr fn | |
6 | @footnotestyle separate | |
7 | @paragraphindent 2 | |
8 | @smallbook | |
9 | @comment %**end of header | |
10 | ||
11 | @c Set smallbook if printing in smallbook format so the example of the | |
12 | @c smallbook font is actually written using smallbook; in bigbook, a kludge | |
13 | @c is used for TeX output. | |
14 | @set smallbook | |
15 | @c @@clear smallbook | |
16 | ||
17 | @ignore | |
18 | @ifinfo | |
19 | @format | |
20 | START-INFO-DIR-ENTRY | |
21 | * Texinfo: (texinfo). The documentation format for the GNU Project. | |
22 | END-INFO-DIR-ENTRY | |
23 | @end format | |
24 | @end ifinfo | |
25 | @end ignore | |
26 | ||
27 | @set edition 2.21 | |
28 | @set update-date 7 June 1995 | |
29 | @set update-month June 1995 | |
30 | ||
31 | @c Experiment with smaller amounts of whitespace between chapters | |
32 | @c and sections. | |
33 | @tex | |
34 | \global\chapheadingskip = 15pt plus 4pt minus 2pt | |
35 | \global\secheadingskip = 12pt plus 3pt minus 2pt | |
36 | \global\subsecheadingskip = 9pt plus 2pt minus 2pt | |
37 | @end tex | |
38 | ||
39 | @c Experiment with smaller amounts of whitespace between paragraphs in | |
40 | @c the 8.5 by 11 inch format. | |
41 | @ifclear smallbook | |
42 | @tex | |
43 | \global\parskip 6pt plus 1pt | |
44 | @end tex | |
45 | @end ifclear | |
46 | ||
47 | @finalout | |
48 | ||
49 | @c Currently undocumented command, 5 December 1993: | |
50 | @c | |
51 | @c nwnode (Same as node, but no warnings; for `makeinfo'.) | |
52 | ||
53 | @ifinfo | |
54 | This file documents Texinfo, a documentation system that uses a single | |
55 | source file to produce both on-line information and a printed manual. | |
56 | ||
42a4f53d | 57 | Copyright (C) 1988-2019 Free Software Foundation, Inc. |
c906108c SS |
58 | |
59 | This is the second edition of the Texinfo documentation,@* | |
60 | and is consistent with version 2 of @file{texinfo.tex}. | |
61 | ||
62 | Permission is granted to make and distribute verbatim copies of | |
63 | this manual provided the copyright notice and this permission notice | |
64 | are preserved on all copies. | |
65 | ||
66 | @ignore | |
67 | Permission is granted to process this file through TeX and print the | |
68 | results, provided the printed document carries copying permission | |
69 | notice identical to this one except for the removal of this paragraph | |
70 | (this paragraph not being relevant to the printed manual). | |
71 | ||
72 | @end ignore | |
73 | Permission is granted to copy and distribute modified versions of this | |
74 | manual under the conditions for verbatim copying, provided that the entire | |
75 | resulting derived work is distributed under the terms of a permission | |
76 | notice identical to this one. | |
77 | ||
78 | Permission is granted to copy and distribute translations of this manual | |
79 | into another language, under the above conditions for modified versions, | |
80 | except that this permission notice may be stated in a translation approved | |
81 | by the Free Software Foundation. | |
82 | @end ifinfo | |
83 | ||
84 | @setchapternewpage odd | |
85 | ||
86 | @shorttitlepage Texinfo | |
87 | ||
88 | @titlepage | |
89 | @c use the new format for titles | |
90 | @title Texinfo | |
91 | @subtitle The GNU Documentation Format | |
92 | @subtitle Edition @value{edition}, for Texinfo Version Three | |
93 | @subtitle @value{update-month} | |
94 | ||
95 | @author by Robert J. Chassell and Richard M. Stallman | |
96 | ||
97 | @comment Include the Distribution inside the titlepage so | |
98 | @c that headings are turned off. | |
99 | ||
100 | @page | |
101 | @vskip 0pt plus 1filll | |
2e0ddd92 | 102 | Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 2010, 2011 |
dc3cf14f | 103 | Free Software Foundation, Inc. |
c906108c SS |
104 | |
105 | @sp 2 | |
106 | This is the second edition of the Texinfo documentation,@* | |
107 | and is consistent with version 2 of @file{texinfo.tex}. | |
108 | @sp 2 | |
109 | ||
110 | Published by the Free Software Foundation @* | |
111 | 59 Temple Place Suite 330, @* | |
112 | Boston, MA 02111-1307 USA @* | |
113 | Printed copies are available for $15 each.@* | |
114 | ISBN 1-882114-63-9 | |
115 | @c ISBN number 1-882114-63-9 is for edition 2.20 of 28 February 1995 | |
116 | ||
117 | Permission is granted to make and distribute verbatim copies of | |
118 | this manual provided the copyright notice and this permission notice | |
119 | are preserved on all copies. | |
120 | ||
121 | Permission is granted to copy and distribute modified versions of this | |
122 | manual under the conditions for verbatim copying, provided that the entire | |
123 | resulting derived work is distributed under the terms of a permission | |
124 | notice identical to this one. | |
125 | ||
126 | Permission is granted to copy and distribute translations of this manual | |
127 | into another language, under the above conditions for modified versions, | |
128 | except that this permission notice may be stated in a translation approved | |
129 | by the Free Software Foundation. | |
130 | @sp 2 | |
131 | Cover art by Etienne Suvasa. | |
132 | @end titlepage | |
133 | ||
134 | @ifinfo | |
135 | @node Top, Copying, (dir), (dir) | |
136 | @top Texinfo | |
137 | ||
138 | Texinfo is a documentation system that uses a single source file to | |
139 | produce both on-line information and printed output.@refill | |
140 | ||
141 | The first part of this master menu lists the major nodes in this Info | |
142 | document, including the @@-command and concept indices. The rest of | |
143 | the menu lists all the lower level nodes in the document.@refill | |
144 | ||
145 | This is Edition @value{edition} of the Texinfo documentation, | |
146 | @w{@value{update-date},} for Texinfo Version Three. | |
147 | @end ifinfo | |
148 | ||
149 | @c Here is a spare copy of the chapter menu entry descriptions, | |
150 | @c in case they are accidently deleted | |
151 | @ignore | |
152 | Your rights. | |
153 | Texinfo in brief. | |
154 | How to use Texinfo mode. | |
155 | What is at the beginning of a Texinfo file? | |
156 | What is at the end of a Texinfo file? | |
157 | How to create chapters, sections, subsections, | |
158 | appendices, and other parts. | |
159 | How to provide structure for a document. | |
160 | How to write nodes. | |
161 | How to write menus. | |
162 | How to write cross references. | |
163 | How to mark words and phrases as code, | |
164 | keyboard input, meta-syntactic | |
165 | variables, and the like. | |
166 | How to write quotations, examples, etc. | |
167 | How to write lists and tables. | |
168 | How to create indices. | |
169 | How to insert @@-signs, braces, etc. | |
170 | How to indicate results of evaluation, | |
171 | expansion of macros, errors, etc. | |
172 | How to force and prevent line and page breaks. | |
173 | How to describe functions and the like in a uniform manner. | |
174 | How to write footnotes. | |
175 | How to specify text for either @TeX{} or Info. | |
176 | How to print hardcopy. | |
177 | How to create an Info file. | |
178 | How to install an Info file | |
179 | A list of all the Texinfo @@-commands. | |
180 | Hints on how to write a Texinfo document. | |
181 | A sample Texinfo file to look at. | |
182 | Tell readers they have the right to copy | |
183 | and distribute. | |
184 | How to incorporate other Texinfo files. | |
185 | How to write page headings and footings. | |
186 | How to find formatting mistakes. | |
187 | All about paragraph refilling. | |
188 | A description of @@-Command syntax. | |
189 | Texinfo second edition features. | |
190 | A menu containing commands and variables. | |
191 | A menu covering many topics. | |
192 | @end ignore | |
193 | ||
194 | @menu | |
195 | * Copying:: Your rights. | |
196 | * Overview:: Texinfo in brief. | |
197 | * Texinfo Mode:: How to use Texinfo mode. | |
198 | * Beginning a File:: What is at the beginning of a Texinfo file? | |
199 | * Ending a File:: What is at the end of a Texinfo file? | |
200 | * Structuring:: How to create chapters, sections, subsections, | |
201 | appendices, and other parts. | |
202 | * Nodes:: How to write nodes. | |
203 | * Menus:: How to write menus. | |
204 | * Cross References:: How to write cross references. | |
205 | * Marking Text:: How to mark words and phrases as code, | |
206 | keyboard input, meta-syntactic | |
207 | variables, and the like. | |
208 | * Quotations and Examples:: How to write quotations, examples, etc. | |
209 | * Lists and Tables:: How to write lists and tables. | |
210 | * Indices:: How to create indices. | |
211 | * Insertions:: How to insert @@-signs, braces, etc. | |
212 | * Glyphs:: How to indicate results of evaluation, | |
213 | expansion of macros, errors, etc. | |
214 | * Breaks:: How to force and prevent line and page breaks. | |
215 | * Definition Commands:: How to describe functions and the like | |
216 | in a uniform manner. | |
217 | * Footnotes:: How to write footnotes. | |
218 | * Conditionals:: How to specify text for either @TeX{} or Info. | |
219 | * Format/Print Hardcopy:: How to convert a Texinfo file to a file | |
220 | for printing and how to print that file. | |
221 | * Create an Info File:: Convert a Texinfo file into an Info file. | |
222 | * Install an Info File:: Make an Info file accessible to users. | |
223 | * Command List:: All the Texinfo @@-commands. | |
224 | * Tips:: Hints on how to write a Texinfo document. | |
225 | * Sample Texinfo File:: A sample Texinfo file to look at. | |
226 | * Sample Permissions:: Tell readers they have the right to copy | |
227 | and distribute. | |
228 | * Include Files:: How to incorporate other Texinfo files. | |
229 | * Headings:: How to write page headings and footings. | |
230 | * Catching Mistakes:: How to find formatting mistakes. | |
231 | * Refilling Paragraphs:: All about paragraph refilling. | |
232 | * Command Syntax:: A description of @@-Command syntax. | |
233 | * Obtaining TeX:: How to Obtain @TeX{}. | |
234 | * New Features:: Texinfo second edition features. | |
235 | * Command and Variable Index:: A menu containing commands and variables. | |
236 | * Concept Index:: A menu covering many topics. | |
237 | ||
238 | --- The Detailed Node Listing --- | |
239 | ||
240 | Overview of Texinfo | |
241 | ||
242 | * Using Texinfo:: Create a conventional printed book | |
243 | or an Info file. | |
244 | * Info Files:: What is an Info file? | |
245 | * Printed Books:: Characteristics of a printed book or manual. | |
246 | * Formatting Commands:: @@-commands are used for formatting. | |
247 | * Conventions:: General rules for writing a Texinfo file. | |
248 | * Comments:: How to write comments and mark regions that | |
249 | the formatting commands will ignore. | |
250 | * Minimum:: What a Texinfo file must have. | |
251 | * Six Parts:: Usually, a Texinfo file has six parts. | |
252 | * Short Sample:: A short sample Texinfo file. | |
253 | * Acknowledgements:: | |
254 | ||
255 | Using Texinfo Mode | |
256 | ||
257 | * Texinfo Mode Overview:: How Texinfo mode can help you. | |
258 | * Emacs Editing:: Texinfo mode adds to GNU Emacs' general | |
259 | purpose editing features. | |
260 | * Inserting:: How to insert frequently used @@-commands. | |
261 | * Showing the Structure:: How to show the structure of a file. | |
262 | * Updating Nodes and Menus:: How to update or create new nodes and menus. | |
263 | * Info Formatting:: How to format for Info. | |
264 | * Printing:: How to format and print part or all of a file. | |
265 | * Texinfo Mode Summary:: Summary of all the Texinfo mode commands. | |
266 | ||
267 | Updating Nodes and Menus | |
268 | ||
269 | * Updating Commands:: Five major updating commands. | |
270 | * Updating Requirements:: How to structure a Texinfo file for | |
271 | using the updating command. | |
272 | * Other Updating Commands:: How to indent descriptions, insert | |
273 | missing nodes lines, and update | |
274 | nodes in sequence. | |
275 | ||
276 | Beginning a Texinfo File | |
277 | ||
278 | * Four Parts:: Four parts begin a Texinfo file. | |
279 | * Sample Beginning:: Here is a sample beginning for a Texinfo file. | |
280 | * Header:: The very beginning of a Texinfo file. | |
281 | * Info Summary and Permissions:: Summary and copying permissions for Info. | |
282 | * Titlepage & Copyright Page:: Creating the title and copyright pages. | |
283 | * The Top Node:: Creating the `Top' node and master menu. | |
284 | * Software Copying Permissions:: Ensure that you and others continue to | |
285 | have the right to use and share software. | |
286 | ||
287 | The Texinfo File Header | |
288 | ||
289 | * First Line:: The first line of a Texinfo file. | |
290 | * Start of Header:: Formatting a region requires this. | |
291 | * setfilename:: Tell Info the name of the Info file. | |
292 | * settitle:: Create a title for the printed work. | |
293 | * setchapternewpage:: Start chapters on right-hand pages. | |
294 | * paragraphindent:: An option to specify paragraph indentation. | |
295 | * End of Header:: Formatting a region requires this. | |
296 | ||
297 | The Title and Copyright Pages | |
298 | ||
299 | * titlepage:: Create a title for the printed document. | |
300 | * titlefont center sp:: The @code{@@titlefont}, @code{@@center}, | |
301 | and @code{@@sp} commands. | |
302 | * title subtitle author:: The @code{@@title}, @code{@@subtitle}, | |
303 | and @code{@@author} commands. | |
304 | * Copyright & Permissions:: How to write the copyright notice and | |
305 | include copying permissions. | |
306 | * end titlepage:: Turn on page headings after the title and | |
307 | copyright pages. | |
308 | * headings on off:: An option for turning headings on and off | |
309 | and double or single sided printing. | |
310 | ||
311 | The `Top' Node and Master Menu | |
312 | ||
313 | * Title of Top Node:: Sketch what the file is about. | |
314 | * Master Menu Parts:: A master menu has three or more parts. | |
315 | ||
316 | Ending a Texinfo File | |
317 | ||
318 | * Printing Indices & Menus:: How to print an index in hardcopy and | |
319 | generate index menus in Info. | |
320 | * Contents:: How to create a table of contents. | |
321 | * File End:: How to mark the end of a file. | |
322 | ||
323 | Chapter Structuring | |
324 | ||
325 | * Tree Structuring:: A manual is like an upside down tree @dots{} | |
326 | * Structuring Command Types:: How to divide a manual into parts. | |
327 | * makeinfo top:: The @code{@@top} command, part of the `Top' node. | |
328 | * chapter:: | |
329 | * unnumbered & appendix:: | |
330 | * majorheading & chapheading:: | |
331 | * section:: | |
332 | * unnumberedsec appendixsec heading:: | |
333 | * subsection:: | |
334 | * unnumberedsubsec appendixsubsec subheading:: | |
335 | * subsubsection:: Commands for the lowest level sections. | |
336 | * Raise/lower sections:: How to change commands' hierarchical level. | |
337 | ||
338 | Nodes | |
339 | ||
340 | * Two Paths:: Different commands to structure | |
341 | Info output and printed output. | |
342 | * Node Menu Illustration:: A diagram, and sample nodes and menus. | |
343 | * node:: How to write a node, in detail. | |
344 | * makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. | |
345 | ||
346 | The @code{@@node} Command | |
347 | ||
348 | * Node Names:: How to choose node and pointer names. | |
349 | * Writing a Node:: How to write an @code{@@node} line. | |
350 | * Node Line Tips:: Keep names short. | |
351 | * Node Line Requirements:: Keep names unique, without @@-commands. | |
352 | * First Node:: How to write a `Top' node. | |
353 | * makeinfo top command:: How to use the @code{@@top} command. | |
354 | * Top Node Summary:: Write a brief description for readers. | |
355 | ||
356 | Menus | |
357 | ||
358 | * Menu Location:: Put a menu in a short node. | |
359 | * Writing a Menu:: What is a menu? | |
360 | * Menu Parts:: A menu entry has three parts. | |
361 | * Less Cluttered Menu Entry:: Two part menu entry. | |
362 | * Menu Example:: Two and three part menu entries. | |
363 | * Other Info Files:: How to refer to a different Info file. | |
364 | ||
365 | Cross References | |
366 | ||
367 | * References:: What cross references are for. | |
368 | * Cross Reference Commands:: A summary of the different commands. | |
369 | * Cross Reference Parts:: A cross reference has several parts. | |
370 | * xref:: Begin a reference with `See' @dots{} | |
371 | * Top Node Naming:: How to refer to the beginning of another file. | |
372 | * ref:: A reference for the last part of a sentence. | |
373 | * pxref:: How to write a parenthetical cross reference. | |
374 | * inforef:: How to refer to an Info-only file. | |
375 | ||
376 | @code{@@xref} | |
377 | ||
378 | * Reference Syntax:: What a reference looks like and requires. | |
379 | * One Argument:: @code{@@xref} with one argument. | |
380 | * Two Arguments:: @code{@@xref} with two arguments. | |
381 | * Three Arguments:: @code{@@xref} with three arguments. | |
382 | * Four and Five Arguments:: @code{@@xref} with four and five arguments. | |
383 | ||
384 | Marking Words and Phrases | |
385 | ||
386 | * Indicating:: How to indicate definitions, files, etc. | |
387 | * Emphasis:: How to emphasize text. | |
388 | ||
389 | Indicating Definitions, Commands, etc. | |
390 | ||
391 | * Useful Highlighting:: Highlighting provides useful information. | |
392 | * code:: How to indicate code. | |
393 | * kbd:: How to show keyboard input. | |
394 | * key:: How to specify keys. | |
395 | * samp:: How to show a literal sequence of characters. | |
396 | * var:: How to indicate a metasyntactic variable. | |
397 | * file:: How to indicate the name of a file. | |
398 | * dfn:: How to specify a definition. | |
399 | * cite:: How to refer to a book that is not in Info. | |
400 | ||
401 | Emphasizing Text | |
402 | ||
403 | * emph & strong:: How to emphasize text in Texinfo. | |
404 | * Smallcaps:: How to use the small caps font. | |
405 | * Fonts:: Various font commands for printed output. | |
406 | * Customized Highlighting:: How to define highlighting commands. | |
407 | ||
408 | Quotations and Examples | |
409 | ||
410 | * Block Enclosing Commands:: Use different constructs for | |
411 | different purposes. | |
412 | * quotation:: How to write a quotation. | |
413 | * example:: How to write an example in a fixed-width font. | |
414 | * noindent:: How to prevent paragraph indentation. | |
415 | * Lisp Example:: How to illustrate Lisp code. | |
416 | * smallexample & smalllisp:: Forms for the @code{@@smallbook} option. | |
417 | * display:: How to write an example in the current font. | |
418 | * format:: How to write an example that does not narrow | |
419 | the margins. | |
420 | * exdent:: How to undo the indentation of a line. | |
421 | * flushleft & flushright:: How to push text flushleft or flushright. | |
422 | * cartouche:: How to draw cartouches around examples. | |
423 | ||
424 | Making Lists and Tables | |
425 | ||
426 | * Introducing Lists:: Texinfo formats lists for you. | |
427 | * itemize:: How to construct a simple list. | |
428 | * enumerate:: How to construct a numbered list. | |
429 | * Two-column Tables:: How to construct a two-column table. | |
430 | ||
431 | Making a Two-column Table | |
432 | ||
433 | * table:: How to construct a two-column table. | |
434 | * ftable vtable:: How to construct a two-column table | |
435 | with automatic indexing. | |
436 | * itemx:: How to put more entries in the first column. | |
437 | ||
438 | Creating Indices | |
439 | ||
440 | * Index Entries:: Choose different words for index entries. | |
441 | * Predefined Indices:: Use different indices for different kinds | |
442 | of entry. | |
443 | * Indexing Commands:: How to make an index entry. | |
444 | * Combining Indices:: How to combine indices. | |
445 | * New Indices:: How to define your own indices. | |
446 | ||
447 | Combining Indices | |
448 | ||
449 | * syncodeindex:: How to merge two indices, using @code{@@code} | |
450 | font for the merged-from index. | |
451 | * synindex:: How to merge two indices, using the | |
452 | default font of the merged-to index. | |
453 | ||
454 | Special Insertions | |
455 | ||
456 | * Braces Atsigns Periods:: How to insert braces, @samp{@@} and periods. | |
457 | * dmn:: How to format a dimension. | |
458 | * Dots Bullets:: How to insert dots and bullets. | |
459 | * TeX and copyright:: How to insert the @TeX{} logo | |
460 | and the copyright symbol. | |
461 | * minus:: How to insert a minus sign. | |
462 | * math:: How to format a mathematical expression. | |
463 | ||
464 | Inserting @samp{@@}, Braces, and Periods | |
465 | ||
466 | * Inserting An Atsign:: | |
467 | * Inserting Braces:: How to insert @samp{@{} and @samp{@}} | |
468 | * Controlling Spacing:: How to insert the right amount of space | |
469 | after punctuation within a sentence. | |
470 | ||
471 | Inserting Ellipsis, Dots, and Bullets | |
472 | ||
473 | * dots:: How to insert dots @dots{} | |
474 | * bullet:: How to insert a bullet. | |
475 | ||
476 | Inserting @TeX{} and the Copyright Symbol | |
477 | ||
478 | * tex:: How to insert the @TeX{} logo. | |
479 | * copyright symbol:: How to use @code{@@copyright}@{@}. | |
480 | ||
481 | Glyphs for Examples | |
482 | ||
483 | * Glyphs Summary:: | |
484 | * result:: How to show the result of expression. | |
485 | * expansion:: How to indicate an expansion. | |
486 | * Print Glyph:: How to indicate printed output. | |
487 | * Error Glyph:: How to indicate an error message. | |
488 | * Equivalence:: How to indicate equivalence. | |
489 | * Point Glyph:: How to indicate the location of point. | |
490 | ||
491 | Making and Preventing Breaks | |
492 | ||
493 | * Break Commands:: Cause and prevent splits. | |
494 | * Line Breaks:: How to force a single line to use two lines. | |
495 | * w:: How to prevent unwanted line breaks. | |
496 | * sp:: How to insert blank lines. | |
497 | * page:: How to force the start of a new page. | |
498 | * group:: How to prevent unwanted page breaks. | |
499 | * need:: Another way to prevent unwanted page breaks. | |
500 | ||
501 | Definition Commands | |
502 | ||
503 | * Def Cmd Template:: How to structure a description using a | |
504 | definition command. | |
505 | * Optional Arguments:: How to handle optional and repeated arguments. | |
506 | * deffnx:: How to group two or more `first' lines. | |
507 | * Def Cmds in Detail:: All the definition commands. | |
508 | * Def Cmd Conventions:: Conventions for writing definitions. | |
509 | * Sample Function Definition:: | |
510 | ||
511 | The Definition Commands | |
512 | ||
513 | * Functions Commands:: Commands for functions and similar entities. | |
514 | * Variables Commands:: Commands for variables and similar entities. | |
515 | * Typed Functions:: Commands for functions in typed languages. | |
516 | * Typed Variables:: Commands for variables in typed languages. | |
517 | * Abstract Objects:: Commands for object-oriented programming. | |
518 | * Data Types:: The definition command for data types. | |
519 | ||
520 | Footnotes | |
521 | ||
522 | * Footnote Commands:: How to write a footnote in Texinfo. | |
523 | * Footnote Styles:: Controlling how footnotes appear in Info. | |
524 | ||
525 | Conditionally Visible Text | |
526 | ||
527 | * Conditional Commands:: How to specify text for Info or @TeX{}. | |
528 | * Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. | |
529 | * set clear value:: How to designate which text to format (for | |
530 | both Info and @TeX{}); and how to set a | |
531 | flag to a string that you can insert. | |
532 | ||
533 | @code{@@set}, @code{@@clear}, and @code{@@value} | |
534 | ||
535 | * ifset ifclear:: Format a region if a flag is set. | |
536 | * value:: Replace a flag with a string. | |
537 | * value Example:: An easy way to update edition information. | |
538 | ||
539 | Format and Print Hardcopy | |
540 | ||
541 | * Use TeX:: Use @TeX{} to format for hardcopy. | |
542 | * Format with tex/texindex:: How to format in a shell. | |
543 | * Format with texi2dvi:: A simpler way to use the shell. | |
544 | * Print with lpr:: How to print. | |
545 | * Within Emacs:: How to format and print from an Emacs shell. | |
546 | * Texinfo Mode Printing:: How to format and print in Texinfo mode. | |
547 | * Compile-Command:: How to print using Emacs's compile command. | |
548 | * Requirements Summary:: @TeX{} formatting requirements summary. | |
549 | * Preparing for TeX:: What you need to do to use @TeX{}. | |
550 | * Overfull hboxes:: What are and what to do with overfull hboxes. | |
551 | * smallbook:: How to print small format books and manuals. | |
552 | * A4 Paper:: How to print on European A4 paper. | |
553 | * Cropmarks and Magnification:: How to print marks to indicate the size | |
554 | of pages and how to print scaled up output. | |
555 | ||
556 | Creating an Info File | |
557 | ||
558 | * makeinfo advantages:: @code{makeinfo} provides better error checking. | |
559 | * Invoking makeinfo:: How to run @code{makeinfo} from a shell. | |
560 | * makeinfo options:: Specify fill-column and other options. | |
561 | * Pointer Validation:: How to check that pointers point somewhere. | |
562 | * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. | |
563 | * texinfo-format commands:: Two Info formatting commands written | |
564 | in Emacs Lisp are an alternative | |
565 | to @code{makeinfo}. | |
566 | * Batch Formatting:: How to format for Info in Emacs Batch mode. | |
567 | * Tag and Split Files:: How tagged and split files help Info | |
568 | to run better. | |
569 | ||
570 | Installing an Info File | |
571 | ||
572 | * Directory file:: The top level menu for all Info files. | |
573 | * New Info File:: Listing a new info file. | |
574 | * Other Info Directories:: How to specify Info files that are | |
575 | located in other directories. | |
576 | ||
577 | Sample Permissions | |
578 | ||
579 | * Inserting Permissions:: How to put permissions in your document. | |
580 | * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. | |
581 | * Titlepage Permissions:: Sample Titlepage copying permissions. | |
582 | ||
583 | Include Files | |
584 | ||
585 | * Using Include Files:: How to use the @code{@@include} command. | |
586 | * texinfo-multiple-files-update:: How to create and update nodes and | |
587 | menus when using included files. | |
588 | * Include File Requirements:: What @code{texinfo-multiple-files-update} expects. | |
589 | * Sample Include File:: A sample outer file with included files | |
590 | within it; and a sample included file. | |
591 | * Include Files Evolution:: How use of the @code{@@include} command | |
592 | has changed over time. | |
593 | ||
594 | Page Headings | |
595 | ||
596 | * Headings Introduced:: Conventions for using page headings. | |
597 | * Heading Format:: Standard page heading formats. | |
598 | * Heading Choice:: How to specify the type of page heading. | |
599 | * Custom Headings:: How to create your own headings and footings. | |
600 | ||
601 | Formatting Mistakes | |
602 | ||
603 | * makeinfo preferred:: @code{makeinfo} finds errors. | |
604 | * Debugging with Info:: How to catch errors with Info formatting. | |
605 | * Debugging with TeX:: How to catch errors with @TeX{} formatting. | |
606 | * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. | |
607 | * Using occur:: How to list all lines containing a pattern. | |
608 | * Running Info-Validate:: How to find badly referenced nodes. | |
609 | ||
610 | Finding Badly Referenced Nodes | |
611 | ||
612 | * Using Info-validate:: How to run @code{Info-validate}. | |
613 | * Unsplit:: How to create an unsplit file. | |
614 | * Tagifying:: How to tagify a file. | |
615 | * Splitting:: How to split a file manually. | |
616 | ||
617 | Second Edition Features | |
618 | ||
619 | * New Texinfo Mode Commands:: The updating commands are especially useful. | |
620 | * New Commands:: Many newly described @@-commands. | |
621 | @end menu | |
622 | ||
623 | @node Copying, Overview, Top, Top | |
624 | @comment node-name, next, previous, up | |
625 | @unnumbered Texinfo Copying Conditions | |
626 | @cindex Copying conditions | |
627 | @cindex Conditions for copying Texinfo | |
628 | ||
629 | The programs currently being distributed that relate to Texinfo include | |
630 | portions of GNU Emacs, plus other separate programs (including | |
631 | @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). | |
632 | These programs are @dfn{free}; this means that everyone is free to use | |
633 | them and free to redistribute them on a free basis. The Texinfo-related | |
634 | programs are not in the public domain; they are copyrighted and there | |
635 | are restrictions on their distribution, but these restrictions are | |
636 | designed to permit everything that a good cooperating citizen would want | |
637 | to do. What is not allowed is to try to prevent others from further | |
638 | sharing any version of these programs that they might get from | |
639 | you.@refill | |
640 | ||
641 | Specifically, we want to make sure that you have the right to give | |
642 | away copies of the programs that relate to Texinfo, that you receive | |
643 | source code or else can get it if you want it, that you can change these | |
644 | programs or use pieces of them in new free programs, and that you know | |
645 | you can do these things.@refill | |
646 | ||
647 | To make sure that everyone has such rights, we have to forbid you to | |
648 | deprive anyone else of these rights. For example, if you distribute | |
649 | copies of the Texinfo related programs, you must give the recipients all | |
650 | the rights that you have. You must make sure that they, too, receive or | |
651 | can get the source code. And you must tell them their rights.@refill | |
652 | ||
653 | Also, for our own protection, we must make certain that everyone finds | |
654 | out that there is no warranty for the programs that relate to Texinfo. | |
655 | If these programs are modified by someone else and passed on, we want | |
656 | their recipients to know that what they have is not what we distributed, | |
657 | so that any problems introduced by others will not reflect on our | |
658 | reputation.@refill | |
659 | ||
660 | The precise conditions of the licenses for the programs currently | |
661 | being distributed that relate to Texinfo are found in the General Public | |
662 | Licenses that accompany them.@refill | |
663 | ||
664 | @node Overview, Texinfo Mode, Copying, Top | |
665 | @comment node-name, next, previous, up | |
666 | @chapter Overview of Texinfo | |
667 | @cindex Overview of Texinfo | |
668 | @cindex Texinfo overview | |
669 | ||
670 | @dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is | |
671 | pronounced like ``speck'', not ``hex''. This odd pronunciation is | |
672 | derived from, but is not the same as, the pronunciation of @TeX{}. In | |
673 | the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' | |
674 | rather than the English letter ``ex''. Pronounce @TeX{} as if the | |
675 | @samp{X} were the last sound in the name `Bach'; but pronounce Texinfo | |
676 | as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' | |
677 | and write the other letters in lower case.} | |
678 | is a documentation system that uses a single source file to produce both | |
679 | on-line information and printed output. This means that instead of | |
680 | writing two different documents, one for the on-line help or other on-line | |
681 | information and the other for a typeset manual or other printed work, you | |
682 | need write only one document. When the work is revised, you need revise | |
683 | only one document. (You can read the on-line information, known as an | |
684 | @dfn{Info file}, with an Info documentation-reading program.)@refill | |
685 | ||
686 | @menu | |
687 | * Using Texinfo:: Create a conventional printed book | |
688 | or an Info file. | |
689 | * Info Files:: What is an Info file? | |
690 | * Printed Books:: Characteristics of a printed book or manual. | |
691 | * Formatting Commands:: @@-commands are used for formatting. | |
692 | * Conventions:: General rules for writing a Texinfo file. | |
693 | * Comments:: How to write comments and mark regions that | |
694 | the formatting commands will ignore. | |
695 | * Minimum:: What a Texinfo file must have. | |
696 | * Six Parts:: Usually, a Texinfo file has six parts. | |
697 | * Short Sample:: A short sample Texinfo file. | |
698 | * Acknowledgements:: | |
699 | @end menu | |
700 | ||
701 | @c ************************************************************************ | |
702 | ||
703 | ||
704 | ||
705 | \input texinfo @c -*-texinfo-*- | |
706 | @c %**start of header | |
707 | @setfilename psim.info | |
708 | @settitle PSIM | |
709 | @setchapternewpage odd | |
710 | @c %**end of header | |
711 | ||
712 | ||
713 | ||
714 | @ifinfo | |
715 | This file documents the program PSIM. | |
716 | ||
717 | Copyright (C) 1994-1996, Andrew Cagney. | |
718 | ||
719 | Permission is granted to make and distribute verbatim copies of | |
720 | this manual provided the copyright notice and this permission notice | |
721 | are preserved on all copies. | |
722 | ||
723 | @ignore | |
724 | Permission is granted to process this file through Tex and print the | |
725 | results, provided the printed document carries copying permission | |
726 | notice identical to this one except for the removal of this paragraph | |
727 | (this paragraph not being relevant to the printed manual). | |
728 | ||
729 | @end ignore | |
730 | Permission is granted to copy and distribute modified versions of this | |
731 | manual under the conditions for verbatim copying, subject to the terms | |
732 | of the GNU General Public License, which includes the provision that the | |
733 | entire resulting derived work is distributed under the terms of a | |
734 | permission notice identical to this one. | |
735 | ||
736 | Permission is granted to copy and distribute translations of this manual | |
737 | into another language, under the above conditions for modified versions. | |
738 | @end ifinfo | |
739 | ||
740 | ||
741 | @titlepage | |
742 | @title PSIM | |
743 | @subtitle Model of the PowerPC Environments | |
744 | @author Andrew Cagney | |
745 | ||
746 | @page | |
747 | @vskip Opt plus ifill | |
748 | Copyright @copyright{} 1994-1996, Andrew Cagney | |
749 | ||
750 | This is the first edition of the PSIM manual and is consistent with PSIM | |
751 | version 1.0. | |
752 | ||
753 | Permission is granted to make and distribute verbatim copies of | |
754 | this manual provided the copyright notice and this permission notice | |
755 | are preserved on all copies. | |
756 | ||
757 | Permission is granted to copy and distribute modified versions of this | |
758 | manual under the conditions for verbatim copying, subject to the terms | |
759 | of the GNU General Public License, which includes the provision that the | |
760 | entire resulting derived work is distributed under the terms of a | |
761 | permission notice identical to this one. | |
762 | ||
763 | Permission is granted to copy and distribute translations of this manual | |
764 | into another language, under the above conditions for modified versions. | |
765 | @end titlepage | |
766 | ||
767 | ||
768 | ||
769 | @menu | |
770 | ||
771 | * Copying:: Your rights and freedoms. | |
772 | * First Chappeter:: Getting started .... | |
773 | * Second Chapter:: Getting finished .... | |
774 | ||
775 | ||
776 | @end menu | |
777 | ||
778 | ||
779 | PSIM is a program written in extended ANSI-C that implements an | |
780 | instruction level simulation of the PowerPC environment. It is freely | |
781 | available in source code form under the terms of the GNU General | |
3fd725ef | 782 | Public License (version 3 or later). |
c906108c SS |
783 | |
784 | The PowerPC Architecture is described as having three levels of | |
785 | compliance: | |
786 | ||
787 | UEA - User Environment Architecture | |
788 | VEA - Virtual Environment Architecture | |
789 | OEA - Operating Environment Architecture | |
790 | ||
791 | PSIM both implements all three levels of the PowerPC and includes (for | |
792 | each level) a corresponding simulated run-time environment. | |
793 | ||
794 | In addition, PSIM, to the execution unit level, models the performance | |
795 | of most of the current PowerPC implementations (contributed by Michael | |
796 | Meissner). This detailed performance monitoring (unlike many other | |
797 | simulators) resulting in only a relatively marginal reduction in the | |
798 | simulators performance. | |
799 | ||
800 | ||
801 | A description of how to build PSIM is contained in the file: | |
802 | ||
803 | ftp://ftp.ci.com.au/pub/psim/INSTALL | |
804 | or ftp://cambridge.cygnus.com/pub/psim/INSTALL | |
805 | ||
806 | while an overview of how to use PSIM is in: | |
807 | ||
808 | ftp://ftp.ci.com.au/pub/psim/RUN | |
809 | or ftp://cambridge.cygnus.com/pub/psim/RUN | |
810 | ||
811 | This file is found in: | |
812 | ||
813 | ftp://ftp.ci.com.au/pub/psim/README | |
814 | or ftp://cambridge.cygnus.com/pub/psim/README | |
815 | ||
816 | ||
817 | Thanks goes firstly to: | |
818 | ||
819 | Corinthian Engineering Pty Ltd | |
820 | Cygnus Support | |
821 | Highland Logic Pty Ltd | |
822 | ||
823 | who provided the resources needed for making this software available | |
824 | on the Internet. | |
825 | ||
826 | More importantly I'd like to thank the following individuals who each | |
827 | contributed in their own unique way: | |
828 | ||
829 | Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam, | |
830 | Michael Meissner, Bob Mercier, Richard Perini, Dale Rahn, | |
831 | Richard Stallman, Mitchele Walker | |
832 | ||
833 | ||
834 | Andrew Cagney | |
835 | Feb, 1995 | |
836 | ||
837 | ||
838 | ---------------------------------------------------------------------- | |
839 | ||
840 | ||
841 | What features does PSIM include? | |
842 | ||
843 | Monitoring and modeling | |
844 | ||
845 | PSIM includes (thanks to Michael Meissner) | |
846 | a detailed model of most of the PowerPC | |
847 | implementations to the functional unit level. | |
848 | ||
849 | ||
850 | SMP | |
851 | ||
852 | The PowerPC ISA defines SMP synchronizing instructions. | |
853 | This simulator implements a limited, but functional, | |
854 | subset of the PowerPC synchronization instructions | |
855 | behaviour. Programs that restrict their synchronization | |
856 | primitives to those that work with this functional | |
857 | sub-set (eg P() and V()) are able to run on the SMP | |
858 | version of PSIM. | |
859 | ||
860 | People intending to use this system should study | |
861 | the code implementing the lwarx instruction. | |
862 | ||
863 | ENDIAN SUPPORT | |
864 | ||
865 | PSIM implements the PowerPC's big and little (xor | |
866 | endian) modes and correctly simulates code that | |
867 | switches between these two modes. | |
868 | ||
869 | In addition, psim can model a true little-endian | |
870 | machine. | |
871 | ||
872 | ISA (Instruction Set Architecture) models | |
873 | ||
874 | PSIM includes a model of the UEA, VEA and OEA. This | |
875 | includes the time base registers (VEA) and HTAB | |
876 | and BATS (OEA). | |
877 | ||
878 | In addition, a preliminary model of the 64 bit | |
879 | PowerPC architecture is implemented. | |
880 | ||
881 | IO Hardware | |
882 | ||
883 | PSIM's internals are based around the concept | |
884 | of a Device Tree. This tree intentionally | |
885 | resembles that of the Device Tree found in | |
886 | OpenBoot firmware. PSIM is flexible enough | |
887 | to allow the user to fully configure this device | |
888 | tree (and consequently the hardware model) at | |
889 | run time. | |
890 | ||
891 | Run-time environments: | |
892 | ||
893 | PSIM's UEA model includes emulation for BSD | |
894 | based UNIX system calls. | |
895 | ||
896 | PSIM's OEA model includes emulation of either: | |
897 | ||
898 | o OpenBoot client interface | |
899 | ||
900 | o MOTO's BUG interface. | |
901 | ||
902 | ||
903 | Floating point | |
904 | ||
905 | Preliminary support for floating point is included. | |
906 | ||
907 | ||
908 | Who would be interested in PSIM? | |
909 | ||
910 | o the curious | |
911 | ||
912 | Using psim, gdb, gcc and binutils the curious | |
913 | user can construct an environment that allows | |
914 | them to play with PowerPC Environment without | |
915 | the need for real hardware. | |
916 | ||
917 | ||
918 | o the analyst | |
919 | ||
920 | PSIM includes many (contributed) monitoring | |
921 | features which (unlike many other simulators) | |
922 | do not come with a great penalty in performance. | |
923 | ||
924 | Thus the performance analyst is able to use | |
925 | this simulator to analyse the performance of | |
926 | the system under test. | |
927 | ||
928 | If PSIM doesn't monitor a components of interest, | |
929 | the source code is freely available, and hence | |
930 | there is no hinderance to changing things | |
931 | to meet a specific analysts needs. | |
932 | ||
933 | ||
934 | o the serious SW developer | |
935 | ||
936 | PSIM models all three levels of the PowerPC | |
937 | Architecture: UEA, VEA and OEA. Further, | |
938 | the internal design is such that PSIM can | |
939 | be extended to support additional requirements. | |
940 | ||
941 | ||
942 | What performance analysis measurements can PSIM perform? | |
943 | ||
944 | Below is the output from a recent analysis run | |
945 | (contributed by Michael Meissner): | |
946 | ||
947 | For the following program: | |
948 | ||
949 | long | |
950 | simple_rand () | |
951 | { | |
952 | static unsigned long seed = 47114711; | |
953 | unsigned long this = seed * 1103515245 + 12345; | |
954 | seed = this; | |
955 | /* cut-cut-cut - see the file RUN.psim */ | |
956 | } | |
957 | ||
958 | Here is the current output generated with the -I switch on a P90 | |
959 | (the compiler used is the development version of GCC with a new | |
960 | scheduler replacing the old one): | |
961 | ||
962 | CPU #1 executed 41,994 AND instructions. | |
963 | CPU #1 executed 519,785 AND Immediate instructions. | |
964 | . | |
965 | . | |
966 | . | |
967 | CPU #1 executed 1 System Call instruction. | |
968 | CPU #1 executed 207,746 XOR instructions. | |
969 | ||
970 | CPU #1 executed 23,740,856 cycles. | |
971 | CPU #1 executed 10,242,780 stalls waiting for data. | |
972 | CPU #1 executed 1 stall waiting for a function unit. | |
973 | . | |
974 | . | |
975 | . | |
976 | CPU #1 executed 3,136,229 branch functional unit instructions. | |
977 | CPU #1 executed 16,949,396 instructions that were accounted for in timing info. | |
978 | CPU #1 executed 871,920 data reads. | |
979 | CPU #1 executed 971,926 data writes. | |
980 | CPU #1 executed 221 icache misses. | |
981 | CPU #1 executed 16,949,396 instructions in total. | |
982 | ||
983 | Simulator speed was 250,731 instructions/second | |
984 | ||
985 | ||
986 | What motivated PSIM? | |
987 | ||
988 | As an idea, psim was first discussed seriously during mid | |
989 | 1994. At that time its main objectives were: | |
990 | ||
991 | ||
992 | o good performance | |
993 | ||
994 | Many simulators loose out by only providing | |
995 | a binary interface to the internals. This | |
996 | interface eventually becomes a bottle neck | |
997 | in the simulators performance. | |
998 | ||
999 | It was intended that PSIM would avoid this | |
1000 | problem by giving the user access to the | |
1001 | full source code. | |
1002 | ||
1003 | Further, by exploiting the power of modern | |
1004 | compilers it was hoped that PSIM would achieve | |
1005 | good performance with out having to compromise | |
1006 | its internal design. | |
1007 | ||
1008 | ||
1009 | o practical portability | |
1010 | ||
1011 | Rather than try to be portable to every | |
1012 | C compiler on every platform, it was decided | |
1013 | that PSIM would restrict its self to supporting | |
1014 | ANSI compilers that included the extension | |
1015 | of a long long type. | |
1016 | ||
1017 | GCC is one such compiler, consequently PSIM | |
1018 | should be portable to any machine running GCC. | |
1019 | ||
1020 | ||
1021 | o flexibility in its design | |
1022 | ||
1023 | PSIM should allow the user to select the | |
1024 | features required and customise the build | |
1025 | accordingly. By having the source code, | |
1026 | the compiler is able to eliminate any un | |
1027 | used features of the simulator. | |
1028 | ||
1029 | After all, let the compiler do the work. | |
1030 | ||
1031 | ||
1032 | o SMP | |
1033 | ||
1034 | A model that allowed the simulation of | |
1035 | SMP platforms with out the large overhead | |
1036 | often encountered with such models. | |
1037 | ||
1038 | ||
1039 | PSIM achieves each of these objectives. | |
1040 | ||
1041 | ||
1042 | Is PSIM PowerPC Platform (PPCP) (nee CHRP) Compliant? | |
1043 | ||
1044 | No. | |
1045 | ||
1046 | Among other things it does not have an Apple ROM socket. | |
1047 | ||
1048 | ||
1049 | Could PSIM be extended so that it models a CHRP machine? | |
1050 | ||
1051 | Yes. | |
1052 | ||
1053 | PSIM has been designed with the CHRP spec in mind. To model | |
1054 | a CHRP desktop the following would need to be added: | |
1055 | ||
1056 | o An apple ROM socket :-) | |
1057 | ||
1058 | o Model of each of the desktop IO devices | |
1059 | ||
1060 | o An OpenPIC device. | |
1061 | ||
1062 | o RTAS (Run Time Abstraction Services). | |
1063 | ||
1064 | o A fully populated device tree. | |
1065 | ||
1066 | ||
1067 | Is the source code available? | |
1068 | ||
1069 | Yes. | |
1070 | ||
1071 | The source code to PSIM is available under the terms of | |
1072 | the GNU Public Licence. This allows you to distribute | |
1073 | the source code for free but with certain conditions. | |
1074 | ||
1075 | See the file: | |
1076 | ||
1077 | ftp://archie.au/gnu/COPYING | |
1078 | ||
1079 | For details of the terms and conditions. | |
1080 | ||
1081 | ||
1082 | Where do I send bugs or report problems? | |
1083 | ||
1084 | There is a mailing list (subscribe through majordomo@ci.com.au) at: | |
1085 | ||
1086 | powerpc-psim@ci.com.au | |
1087 | ||
1088 | If I get the ftp archive updated I post a note to that mailing list. | |
1089 | In addition your welcome to send bugs or problems either to me or to | |
1090 | that e-mail list. | |
1091 | ||
1092 | This list currently averages zero articles a day. | |
1093 | ||
1094 | ||
1095 | Does PSIM have any limitations or problems? | |
1096 | ||
1097 | PSIM can't run rs6000/AIX binaries - At present PSIM can only | |
1098 | simulate static executables. Since an AIX executable is | |
1099 | never static, PSIM is unable to simulate its execution. | |
1100 | ||
1101 | PSIM is still under development - consequently there are going | |
1102 | to be bugs. | |
1103 | ||
1104 | See the file BUGS (included in the distribution) for any | |
1105 | other outstanding issues. | |
1106 |