+++ /dev/null
-This is Info file ../info/texinfo.info, produced by Makeinfo version
-1.68 from the input file texinfo.texi.
-
-INFO-DIR-SECTION Texinfo documentation system
-START-INFO-DIR-ENTRY
-* Texinfo: (texinfo). The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. Updating info/dir entries.
-* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
-* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
-* makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
-END-INFO-DIR-ENTRY
-
- This file documents Texinfo, a documentation system that can produce
-both on-line information and a printed manual from a single source file.
-
- Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
-Foundation, Inc.
-
- This edition is for Texinfo version 3.12.
-
- 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.
-
-\1f
-File: texinfo.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 3.12 of the Texinfo documentation, 27 February 1998.
-
-* 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.
-* 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.
-* Macros:: Defining new Texinfo commands.
-* 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.
-* 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.
-* Raise/lower sections:: How to change commands' hierarchical level.
-
-Nodes
-
-* Two Paths:: Different commands to structure
- Info output and printed output.
-* Node Menu Illustration:: A diagram, and sample nodes and menus.
-* node:: How to write a node, in detail.
-* makeinfo Pointer Creation:: How to create node pointers with `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.
-* uref:: How to refer to a uniform resource locator.
-
-`@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.
-* url:: How to indicate a world wide web reference.
-* email:: How to indicate an electronic mail address.
-
-Emphasizing Text
-
-* emph & strong:: How to emphasize text in Texinfo.
-* Smallcaps:: How to use the small caps font.
-* Fonts:: Various font commands for printed output.
-* Customized Highlighting:: How to define highlighting commands.
-
-Quotations and Examples
-
-* Block Enclosing Commands:: Use different constructs for
- different purposes.
-* quotation:: How to write a quotation.
-* example:: How to write an example in a fixed-width font.
-* noindent:: How to prevent paragraph indentation.
-* Lisp Example:: How to illustrate Lisp code.
-* smallexample & smalllisp:: Forms for the `@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.
-
-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.
-* Multi-column Tables:: How to construct generalized tables.
-
-Making a Two-column Table
-
-* table:: How to construct a two-column table.
-* ftable vtable:: Automatic indexing for two-column tables.
-* itemx:: How to put more entries in the first column.
-
-Multi-column Tables
-
-* Multitable Column Widths:: Defining multitable column widths.
-* Multitable Rows:: Defining multitable rows, with examples.
-
-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:: How to insert braces, `@'.
-* Inserting Space:: How to insert the right amount of space
- within a sentence.
-* Inserting Accents:: How to insert accents and special characters.
-* Dots Bullets:: How to insert dots and bullets.
-* TeX and copyright:: How to insert the TeX logo
- and the copyright symbol.
-* pounds:: How to insert the pounds currency symbol.
-* minus:: How to insert a minus sign.
-* math:: How to format a mathematical expression.
-* Glyphs:: How to indicate results of evaluation,
- expansion of macros, errors, etc.
-* Images:: How to include graphics.
-
-Inserting @ and Braces
-
-* Inserting An Atsign:: How to insert `@'.
-* Inserting Braces:: How to insert `{' and `}'.
-
-Inserting Space
-
-* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
-* Ending a Sentence:: Sometimes it does.
-* Multiple Spaces:: Inserting multiple spaces.
-* dmn:: How to format a dimension.
-
-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.
-
-Glyphs Summary
-
-* result::
-* expansion::
-* Print Glyph::
-* Error Glyph::
-* Equivalence::
-* Point Glyph::
-
-Making and Preventing Breaks
-
-* Break Commands:: Cause and prevent splits.
-* Line Breaks:: How to force a single line to use two lines.
-* - and hyphenation:: How to tell TeX about hyphenation points.
-* w:: How to prevent unwanted line breaks.
-* sp:: How to insert blank lines.
-* page:: How to force the start of a new page.
-* group:: How to prevent unwanted page breaks.
-* need:: Another way to prevent unwanted page breaks.
-
-Definition Commands
-
-* Def Cmd Template:: How to structure a description using a
- definition command.
-* Optional Arguments:: How to handle optional and repeated arguments.
-* deffnx:: How to group two or more `first' lines.
-* Def Cmds in Detail:: All the definition commands.
-* Def Cmd Conventions:: Conventions for writing definitions.
-* Sample Function Definition::
-
-The Definition Commands
-
-* Functions Commands:: Commands for functions and similar entities.
-* Variables Commands:: Commands for variables and similar entities.
-* Typed Functions:: Commands for functions in typed languages.
-* Typed Variables:: Commands for variables in typed languages.
-* Abstract Objects:: Commands for object-oriented programming.
-* Data Types:: The definition command for data types.
-
-Footnotes
-
-* Footnote Commands:: How to write a footnote in Texinfo.
-* Footnote Styles:: Controlling how footnotes appear in Info.
-
-Conditionally Visible Text
-
-* Conditional Commands:: Specifying text for HTML, Info, or TeX.
-* Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
-* Raw Formatter Commands:: Using raw TeX or HTML commands.
-* set clear value:: Designating which text to format (for
- all output formats); 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.
-
-Macros: Defining New Texinfo Commands
-
-* Defining Macros:: Both defining and undefining new commands.
-* Invoking Macros:: Using a macro, once you've defined it.
-
-Format and Print Hardcopy
-
-* Use TeX:: Use TeX to format for hardcopy.
-* Format with tex/texindex:: How to format in a shell.
-* Format with texi2dvi:: A simpler way to use the shell.
-* Print with lpr:: How to print.
-* Within Emacs:: How to format and print from an Emacs shell.
-* Texinfo Mode Printing:: How to format and print in Texinfo mode.
-* Compile-Command:: How to print using Emacs's compile command.
-* Requirements Summary:: TeX formatting requirements summary.
-* Preparing for TeX:: What you need to do to use TeX.
-* Overfull hboxes:: What are and what to do with overfull hboxes.
-* smallbook:: How to print small format books and manuals.
-* A4 Paper:: How to print on European A4 paper.
-* Cropmarks and Magnification:: How to print marks to indicate the size
- of pages and how to print scaled up output.
-
-Creating an Info File
-
-* makeinfo advantages:: `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.
-* Installing Dir Entries:: How to specify what menu entry to add
- to the Info directory.
-* Invoking install-info:: `install-info' options.
-
-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.
-
-How to Obtain TeX
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.info, Node: Overview, Next: Texinfo Mode, Prev: Copying, Up: Top
-
-Overview of Texinfo
-*******************
-
- "Texinfo"(1) (*note Overview-Footnotes::) 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::
-
-\1f
-File: texinfo.info, Node: Overview-Footnotes, Up: Overview
-
- (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.
-
-\1f
-File: texinfo.info, Node: Using Texinfo, Next: Info Files, Prev: Overview, 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, plain TeX.) 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 printers; 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.
-
-\1f
-File: texinfo.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) (*note Info Files-Footnotes::)
-
- 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
-occasionally 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
-named `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.
-Alternatively, with the standalone Info program, you can specify
-specific menu items on the command line (*note Top: (info)Top.).
-
- If you want to read through an Info file in sequence, as if it were a
-printed manual, you can hit <SPC> repeatedly, or you get the whole file
-with the advanced Info command `g *'. (*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.
-
-\1f
-File: texinfo.info, Node: Info Files-Footnotes, Up: Info Files
-
- (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.
-
-\1f
-File: texinfo.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) (*note Printed Books-Footnotes::)
-
- 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 superset 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: (xemacs)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.
-
-\1f
-File: texinfo.info, Node: Printed Books-Footnotes, Up: Printed Books
-
- (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 not part of the standard GNU
-distribution.
-
-\1f
-File: texinfo.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) (*note Formatting
-Commands-Footnotes::) 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.)
-
-\1f
-File: texinfo.info, Node: Formatting Commands-Footnotes, Up: Formatting Commands
-
- (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.
-
-\1f
-File: texinfo.info, Node: Conventions, Next: Comments, Prev: Formatting Commands, Up: Overview
-
-General Syntactic Conventions
-=============================
-
- All printable ASCII 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 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 plain
-TeX 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. Similarly for `@ifhtml ... @end ifhtml',
-`@ifnothtml ... @end ifnothtml', `@ifnotinfo ... @end ifnotinfo',
-`@ifnottex ... @end ifnottex', *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. Furthermore,
- `makeinfo' does nothing special with tabs, and thus a tab character
- in your input file may appear differently in the output.
-
- 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.
-
- Don't use tabs.
-
-\1f
-File: texinfo.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.
-
-\1f
-File: texinfo.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 tells TeX to open auxiliary files. 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.
-
-\1f
-File: texinfo.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.
-
projects / chise / xemacs-chise.git.1 / blobdiff