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