OS/2 Professional/OS2PRO194.ISO/os2/prgramer/unix/info/texinfo.i08

GNU Info File | 1993-06-12 | 50.5 KB | 1,317 lines

This is Info file texinfo, produced by Makeinfo-1.47 from the input
file texinfo2.tex.

   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 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 Foundation.


File: texinfo,  Node: Command List,  Next: Tips,  Prev: Install an Info File,  Up: Top

@-Command List
**************

   Here is an alphabetical list of the @-commands in Texinfo.  Square
brackets ([ ]) indicate optional arguments; an ellipsis (`...')
indicates repeated text.

`@*'
     Force a line break. Do not end a paragraph that uses `@*' with an
     `@refill' command.  *Note Line Breaks::.

`@.'
     Stands for a period that really does end a sentence (usually after
     an end-of-sentence capital letter).  *Note Controlling Spacing::.

`@:'
     Indicate to TeX that an immediately preceding period, question
     mark, exclamation mark, or colon does not end a sentence.  Prevent
     TeX from inserting extra whitespace as it does at the end of a
     sentence.  The command has no effect on the Info file output.
     *Note Controlling Spacing::.

`@@'
     Stands for `@'.  *Note Inserting `@': Braces Atsigns Periods.

`@{'
     Stands for a left-hand brace, `{'. *Note Inserting @ braces and
     periods: Braces Atsigns Periods.

`@}'
     Stands for a right-hand brace, `}'. *Note Inserting @ braces and
     periods: Braces Atsigns Periods.

`@appendix TITLE'
     Begin an appendix.  The title appears in the table of contents of
     a printed manual.  In Info, the title is underlined with
     asterisks.  *Note The `@unnumbered' and `@appendix' Commands:
     unnumbered & appendix.

`@appendixsec TITLE'
`@appendixsection TITLE'
     Begin an appendix section within an appendix.  The section title
     appears in the table of contents of a printed manual.  In Info,
     the title is underlined with equal signs.  `@appendixsection' is a
     longer spelling of the `@appendixsec' command.  *Note Section
     Commands: unnumberedsec appendixsec heading.

`@appendixsubsec TITLE'
     Begin an appendix subsection within an appendix.  The title appears
     in the table of contents of a printed manual.  In Info, the title
     is underlined with hyphens.  *Note Subsection Commands:
     unnumberedsubsec appendixsubsec subheading.

`@appendixsubsubsec TITLE'
     Begin an appendix subsubsection within a subappendix.  The title
     appears in the table of contents of a printed manual.  In Info, the
     title is underlined with periods.  *Note The `subsub' Commands:
     subsubsection.

`@asis'
     Used following `@table', `@ftable', and `@vtable' to print the
     table's first column without highlighting ("as is"). *Note Making
     a Two-column Table: Two-column Tables.

`@author AUTHOR'
     Typeset AUTHOR flushleft and underline it.  *Note The `@title' and
     `@author' Commands: title subtitle author.

`@b{TEXT}'
     Print TEXT in bold font.  No effect in Info.  *Note Fonts::.

`@bullet{}'
     Generate a large round dot, or the closest possible thing to one.
     *Note `@bullet': bullet.

`@bye'
     Terminate TeX processing on the file.  TeX does not see any of the
     contents of the file following the `@bye' command. *Note Ending a
     File::.

`@c COMMENT'
     Begin a comment in Texinfo.  The rest of the line does not appear
     in either the Info file or the printed manual.  A synonym for
     `@comment'.  *Note General Syntactic Conventions: Conventions.

`@cartouche'
     Highlight an example or quotation by drawing a box with rounded
     corners around it.  Pair with `@end cartouche'.  No effect in
     Info.  *Note Drawing Cartouches Around Examples: cartouche.)

`@center LINE-OF-TEXT'
     Center the line of text following the command. *Note `@center':
     titlefont center sp.

`@chapheading TITLE'
     Print a chapter-like heading in the text, but not in the table of
     contents of a printed manual.  In Info, the title is underlined
     with asterisks.  *Note `@majorheading' and `@chapheading':
     majorheading & chapheading.

`@chapter TITLE'
     Begin a chapter.  The chapter title appears in the table of
     contents of a printed manual.  In Info, the title is underlined
     with asterisks.  *Note `@chapter': chapter.

`@cindex ENTRY'
     Add ENTRY to the index of concepts.  *Note  Defining the Entries
     of an Index: Index Entries.

`@cite{REFERENCE}'
     Highlight the name of a book or other reference that lacks a
     companion Info file.  *Note `@cite': cite.

`@clear FLAG'
     Unset FLAG, preventing the Texinfo formatting commands from
     formatting text between subsequent pairs of `@ifset FLAG' and
     `@end ifset' commands.  *Note `@set' and `@clear': set and clear.

`@code{SAMPLE-CODE}'
     Highlight text that is an expression, a syntactically complete
     token of a program, or a program name.  *Note `@code': code.

`@comment COMMENT'
     Begin a comment in Texinfo.  The rest of the line does not appear
     in either the Info file or the printed manual.  A synonym for `@c'.
     *Note General Syntactic Conventions: Conventions.

`@contents'
     Print a complete table of contents.  Has no effect in Info, which
     uses menus instead.  *Note Generating a Table of Contents:
     Contents.

`@copyright{}'
     Generate a copyright symbol.  *Note  `@copyright': copyright
     symbol.

`@defcodeindex INDEX-NAME'
     Define a new index and its indexing command.  Print entries in an
     `@code' font.  *Note Defining New Indices: New Indices.

`@defcv CATEGORY CLASS NAME'
     Format a description for a variable associated with a class in
     object-oriented programming.  Takes three arguments: the category
     of thing being defined, the class to which it belongs, and its
     name. *Note Definition Commands::.

`@deffn CATEGORY NAME ARGUMENTS...'
     Format a description for a function, interactive command, or
     similar entity that may take arguments.  `@deffn' takes as
     arguments the category of entity being described, the name of this
     particular entity, and its arguments, if any.  *Note Definition
     Commands::.

`@defindex INDEX-NAME'
     Define a new index and its indexing command.  Print entries in a
     roman font.  *Note Defining New Indices: New Indices.

`@defivar CLASS INSTANCE-VARIABLE-NAME'
     Format a description for an instance variable in object-oriented
     programming.  The command is equivalent to `@defcv {Instance
     Variable} ...'.  *Note Definition Commands::.

`@defmac MACRO-NAME ARGUMENTS...'
     Format a description for a macro.  The command is equivalent to
     `@deffn Macro ...'.  *Note Definition Commands::.

`@defmethod CLASS METHOD-NAME ARGUMENTS...'
     Format a description for a method in object-oriented programming.
     The command is equivalent to `@defop Method ...'.  Takes as
     arguments the name of the class of the method, the name of the
     method, and its arguments, if any.  *Note Definition Commands::.

`@defop CATEGORY CLASS NAME ARGUMENTS...'
     Format a description for an operation in object-oriented
     programming. `@defop' takes as arguments the overall name of the
     category of operation, the name of the class of the operation, the
     name of the operation, and its arguments, if any.  *Note
     Definition Commands::.

`@defopt OPTION-NAME'
     Format a description for a user option.  The command is equivalent
     to `@defvr {User Option} ...'.  *Note Definition Commands::.

`@defspec SPECIAL-FORM-NAME ARGUMENTS...'
     Format a description for a special form.  The command is
     equivalent to `@deffn {Special Form} ...'.  *Note Definition
     Commands::.

`@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
     Format a description for a data type.  `@deftp' takes as arguments
     the category, the name of the type (which is a word like `int' or
     `float'), and then the names of attributes of objects of that
     type.  *Note Definition Commands::.

`@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
     Format a description for a function or similar entity that may take
     arguments and that is typed.  `@deftypefn' takes as arguments the
     classification of entity being described, the type, the name of
     the entity, and its arguments, if any.  *Note Definition
     Commands::.

`@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
     Format a description for a function in a typed language. The
     command is equivalent to `@deftypefn Function ...'. *Note
     Definition Commands::.

`@deftypevr CLASSIFICATION DATA-TYPE NAME'
     Format a description for something like a variable in a typed
     language--an entity that records a value.  Takes as arguments the
     classification of entity being described, the type, and the name of
     the entity.  *Note Definition Commands::.

`@deftypevar DATA-TYPE VARIABLE-NAME'
     Format a description for a variable in a typed language.  The
     command is equivalent to `@deftypevr Variable ...'.  *Note
     Definition Commands::.

`@defun FUNCTION-NAME ARGUMENTS...'
     Format a description for functions.  The command is equivalent to
     `@deffn Function ...'.  *Note Definition Commands::.

`@defvar VARIABLE-NAME'
     Format a description for variables.  The command is equivalent to
     `@defvr Variable ...'.  *Note Definition Commands::.

`@defvr CATEGORY NAME'
     Format a description for any kind of variable.  `@defvr' takes as
     arguments the category of the entity and the name of the entity.
     *Note Definition Commands::.

`@dfn{TERM}'
     Highlight the introductory or defining use of a term. *Note
     `@dfn': dfn.

`@display'
     Begin a kind of example.  Indent text, do not fill, do not select a
     new font.  Pair with `@end display'.  *Note  `@display': display.

`@dmn{DIMENSION}'
     Format a dimension.  Causes TeX to insert a narrow space before
     DIMENSION.  Has no effect in Info.  Used for writing a number
     followed by an abbreviation of a dimension name, such as `12pt',
     written as `12@dmn{pt}', with no space between the number and the
     `@dmn' command.  *Note  `@dmn': dmn.

`@dots{}'
     Insert an ellipsis: `...'. *Note `@dots': dots.

`@emph{TEXT}'
     Highlight TEXT; text is displayed in *italics* in printed output,
     and surrounded by asterisks in Info.  *Note Emphasizing Text:
     Emphasis.

`@enumerate'
     Begin a numbered list, using `@item' for each entry.  Pair with
     `@end enumerate'.  *Note  `@enumerate': enumerate.

`@equiv{}'
     Indicate to the reader the exact equivalence of two forms with a
     glyph: `=='.  *Note Equivalence::.

`@error{}'
     Indicate to the reader with a glyph that the following text is an
     error message: `error-->'.  *Note Error Glyph::.

`@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings for even-numbered (left-hand) pages.  Not
     relevant to Info.  *Note How to Make Your Own Headings: Custom
     Headings.

`@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page headings for even-numbered (left-hand) pages.  Not
     relevant to Info.  *Note How to Make Your Own Headings: Custom
     Headings.

`@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings for every page.  Not relevant to Info.
     *Note How to Make Your Own Headings: Custom Headings.

`@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page headings for every page.  Not relevant to Info.
     *Note How to Make Your Own Headings: Custom Headings.

`@example'
     Begin an example.  Indent text, do not fill, and select
     fixed-width font. Pair with `@end example'.  *Note  `@example':
     example.

`@exdent LINE-OF-TEXT'
     Remove any indentation a line might have.  *Note  Undoing the
     Indentation of a Line: exdent.

`@expansion{}'
     Indicate the result of a macro expansion to the reader with a
     special glyph: `==>'. *Note ==> Indicating an Expansion: expansion.

`@file{FILENAME}'
     Highlight the name of a file, buffer, node, or directory.  *Note
     `@file': file.

`@finalout'
     Prevent TeX from printing large black warning rectangles beside
     over-wide lines.  *Note Overfull hboxes::.

`@findex ENTRY'
     Add ENTRY to the index of functions.  *Note  Defining the Entries
     of an Index: Index Entries.

`@flushleft'
     Left justify every line but leave the right end ragged. Leave font
     as is.  Pair with `@end flushleft'. *Note `@flushleft' and
     `@flushright': flushleft & flushright.

`@flushright'
     Right justify every line but leave the left end ragged. Leave font
     as is.  Pair with `@end flushright'. *Note `@flushleft' and
     `@flushright': flushleft & flushright.

`@footnote{TEXT-OF-FOOTNOTE}'
     Enter a footnote.  Footnote text is printed at the bottom of the
     page by TeX; Info may format in either `End' node or `Separate'
     node style. *Note Footnotes::.

`@footnotestyle STYLE'
     Specify an Info file's footnote style, either `end' for the end
     node style or `separate' for the separate node style. *Note
     Footnotes::.

`@format'
     Begin a kind of example.  Like `@example' or `@display', but do
     not narrow the margins and do not select the fixed-width font.
     Pair with `@end format'.  *Note  `@example': example.

`@ftable FORMATTING-COMMAND'
     Begin a two-column table, using `@item' for each entry.
     Automatically enter each of the items in the first column into the
     index of functions.  Pair with `@end ftable'.  The same as
     `@table', except for indexing.  *Note  `@ftable' and `@vtable':
     ftable vtable.

`@group'
     Hold text together that must appear on one printed page.  Pair with
     `@end group'.  Not relevant to Info.  *Note  `@group': group.

`@heading TITLE'
     Print an unnumbered section-like heading in the text, but not in
     the table of contents of a printed manual.  In Info, the title is
     underlined with equal signs.  *Note Section Commands:
     unnumberedsec appendixsec heading.

`@headings ON-OFF-SINGLE-DOUBLE'
     Turn page headings on or off, or specify single-sided or
     double-sided page headings for printing.  `@headings on' is
     synonymous with `@headings double'.  *Note The `@headings'
     Command: headings on off.

`@i{TEXT}'
     Print TEXT in italic font.  No effect in Info. *Note Fonts::.

`@ifclear FLAG'
     If FLAG is cleared, the Texinfo formatting commands format text
     between `@ifclear FLAG' and the following `@end ifclear' command.
     *Note `@set' and `@clear': set and clear.

`@ifinfo'
     Begin a stretch of text that will be ignored by TeX when it
     typesets the printed manual.  The text appears only in the Info
     file. Pair with `@end ifinfo'.  *Note Conditionally Visible Text:
     Conditionals.

`@ifset FLAG'
     If FLAG is set, the Texinfo formatting commands format text
     between `@ifset FLAG' and the following `@end ifset' command.
     *Note `@set' and `@clear': set and clear.

`@iftex'
     Begin a stretch of text that will not appear in the Info file, but
     will be processed only by TeX.  Pair with `@end iftex'. *Note
     Conditionally Visible Text: Conditionals.

`@ignore'
     Begin a stretch of text that will not appear in either the Info
     file or the printed output.  Pair with `@end ignore'. *Note
     Comments and Ignored Text: Comments.

`@include FILENAME'
     Incorporate the contents of the file FILENAME into the Info file
     or printed document.  *Note Include Files::.

`@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
     Make a cross reference to an Info file for which there is no
     printed manual.  *Note Cross references using `@inforef': inforef.

`\input MACRO-DEFINITIONS-FILE'
     Use the specified macro definitions file.  This command is used
     only in the first line of a Texinfo file to cause TeX to make use
     of the `texinfo' macro definitions file.  The backslash in `\input'
     is used instead of an `@' because TeX does not properly recognize
     `@' until after it has read the definitions file. *Note The
     Texinfo File Header: Header.

`@item'
     Indicate the beginning of a marked paragraph for `@itemize' and
     `@enumerate'; indicate the beginning of the text of a first column
     entry for `@table', `@ftable', and `@vtable'. *Note Lists and
     Tables::.

`@itemize  MARK-GENERATING-CHARACTER-OR-COMMAND'
     Produce a sequence of indented paragraphs, with a mark inside the
     left margin at the beginning of each paragraph.  Pair with `@end
     itemize'.  *Note `@itemize': itemize.

`@itemx'
     Like `@item' but do not generate extra vertical space above the
     item text.  *Note `@itemx': itemx.

`@kbd{KEYBOARD-CHARACTERS}'
     Indicate text that consists of characters of input to be typed by
     users.  *Note `@kbd': kbd.

`@key{KEY-NAME}'
     Highlight KEY-NAME, a conventional name for a key on a keyboard.
     *Note `@key': key.

`@kindex ENTRY'
     Add ENTRY to the index of keys.  *Note Defining the Entries of an
     Index: Index Entries.

`@lisp'
     Begin an example of Lisp code.  Indent text, do not fill, and
     select fixed-width font.  Pair with `@end lisp'.  *Note  `@lisp':
     Lisp Example.

`@majorheading  TITLE'
     Print a chapter-like heading in the text, but not in the table of
     contents of a printed manual.  Generate more vertical whitespace
     before the heading than the `@chapheading' command.  In Info, the
     chapter heading line is underlined with asterisks.  *Note
     `@majorheading' and `@chapheading': majorheading & chapheading.

`@menu'
     Mark the beginning of a menu of nodes in Info.  No effect in a
     printed manual.  Pair with `@end menu'.  *Note Menus::.

`@minus{}'
     Generate a minus sign.  *Note `@minus': minus.

`@need N'
     Start a new page in a printed manual if fewer than N mils
     (thousandths of an inch) remain on the current page.  *Note
     `@need': need.

`@node NAME, NEXT, PREVIOUS, UP'
     Define the beginning of a new node in Info, and serve as a locator
     for references for TeX.  *Note `@node': node.

`@noindent'
     Prevent text from being indented as if it were a new paragraph.
     *Note `@noindent': noindent.

`@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings for odd-numbered (right-hand) pages.  Not
     relevant to Info.  *Note How to Make Your Own Headings: Custom
     Headings.

`@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page headings for odd-numbered (right-hand) pages.  Not
     relevant to Info.  *Note How to Make Your Own Headings: Custom
     Headings.

`@page'
     Start a new page in a printed manual.  No effect in Info. *Note
     `@page': page.

`@paragraphindent INDENT'
     Indent paragraphs by INDENT number of spaces; delete indentation
     if the value of INDENT is 0; and do not change indentation if
     INDENT is `asis'. *Note Paragraph Indenting: paragraphindent.

`@pindex ENTRY'
     Add ENTRY to the index of programs.  *Note Defining the Entries of
     an Index: Index Entries.

`@point{}'
     Indicate the position of point in a buffer to the reader with a
     glyph: `-!-'.  *Note Indicating Point in a Buffer: Point Glyph.

`@print{}'
     Indicate printed output to the reader with a glyph: `-|'.  *Note
     Print Glyph::.

`@printindex INDEX-NAME'
     Print an alphabetized two-column index in a printed manual or
     generate an alphabetized menu of index entries for Info.  *Note
     Printing Indices & Menus::.

`@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
     Make a reference that starts with a lower case `see' in a printed
     manual.  Use within parentheses only.  Do not follow command with a
     punctuation mark.  The Info formatting commands automatically
     insert terminating punctuation as needed, which is why you do not
     need to insert punctuation.  Only the first argument is mandatory.
     *Note `@pxref': pxref.

`@quotation'
     Narrow the margins to indicate text that is quoted from another
     real or imaginary work.  Write command on a line of its own.  Pair
     with `@end quotation'.  *Note  `@quotation': quotation.

`@r{TEXT}'
     Print TEXT in roman font.  No effect in Info. *Note Fonts::.

`@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
     Make a reference.  In a printed manual, the reference does not
     start with a `See'.  Follow command with a punctuation mark.  Only
     the first argument is mandatory.  *Note `@ref': ref.

`@refill'
     In Info, refill and indent the paragraph after all the other
     processing has been done.  No effect on TeX, which always refills.
      This command is no longer needed, since all formatters now
     automatically refill. *Note Refilling Paragraphs::.

`@result{}'
     Indicate the result of an expression to the reader with a special
     glyph: `=>'.  *Note `@result': result.

`@samp{TEXT}'
     Highlight TEXT that is a literal example of a sequence of
     characters.  Used for single characters, for statements, and often
     for entire shell commands.  *Note `@code': samp.

`@sc{TEXT}'
     Set TEXT in a printed output in THE SMALL CAPS FONT and set text
     in the Info file in uppercase letters. *Note Smallcaps::.

`@section TITLE'
     Begin a section within a chapter.  In a printed manual, the section
     title is numbered and appears in the table of contents.  In Info,
     the title is underlined with equal signs.  *Note  `@section':
     section.

`@set FLAG'
     Set FLAG, causing the Texinfo formatting commands to format text
     between subsequent pairs of `@ifset FLAG' and `@end ifset'
     commands.  *Note `@set' and `@clear': set and clear.

`@setchapternewpage ON-OFF-ODD'
     Specify whether chapters start on new pages, and if so, whether on
     odd-numbered (right-hand) new pages.  *Note  `@setchapternewpage':
     setchapternewpage.

`@setfilename INFO-FILE-NAME'
     Provide a name for the Info file.  *Note General Syntactic
     Conventions: Conventions.

`@settitle TITLE'
     Provide a title for page headers in a printed manual. *Note
     General Syntactic Conventions: Conventions.

`@shortcontents'
     Print a short table of contents.  Not relevant to Info, which uses
     menus rather than tables of contents.  A synonym for
     `@summarycontents'.  *Note Generating a Table of Contents:
     Contents.

`@smallbook'
     Cause TeX to produce a printed manual in a 7 by 9.25 inch format
     rather than the regular 8.5 by 11 inch format.  *Note  Printing
     Small Books: smallbook.  Also, see *Note  `@smallexample' and
     `@smalllisp': smallexample & smalllisp.

`@smallexample'
     Indent text to indicate an example.  Do not fill, select
     fixed-width font.  In `@smallbook' format, print text in a smaller
     font than with `@example'.  Pair with `@end smallexample'. *Note
     `@smallexample' and `@smalllisp': smallexample & smalllisp.

`@smalllisp'
     Begin an example of Lisp code.  Indent text, do not fill, select
     fixed-width font.  In `@smallbook' format, print text in a smaller
     font.  Pair with `@end smalllisp'.  *Note `@smallexample' and
     `@smalllisp': smallexample & smalllisp.

`@sp N'
     Skip N blank lines.  *Note `@sp': sp.

`@strong TEXT'
     Emphasize TEXT by typesetting it in a *bold* font for the printed
     manual and by surrounding it with asterisks for Info. *Note
     Emphasizing Text: emph & strong.

`@subheading TITLE'
     Print an unnumbered subsection-like heading in the text, but not in
     the table of contents of a printed manual.  In Info, the title is
     underlined with hyphens.  *Note `@unnumberedsubsec'
     `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
     subheading.

`@subsection TITLE'
     Begin a subsection within a section.  In a printed manual, the
     subsection title is numbered and appears in the table of contents.
      In Info, the title is underlined with hyphens.  *Note
     `@subsection': subsection.

`@subsubheading TITLE'
     Print an unnumbered subsubsection-like heading in the text, but
     not in the table of contents of a printed manual.  In Info, the
     title is underlined with periods.  *Note The `subsub' Commands:
     subsubsection.

`@subsubsection TITLE'
     Begin a subsubsection within a subsection.  In a printed manual,
     the subsubsection title is numbered and appears in the table of
     contents.  In Info, the title is underlined with periods. *Note
     The `subsub' Commands: subsubsection.

`@subtitle TITLE'
     In a printed manual, set a subtitle in a normal sized font flush to
     the right-hand side of the page.  Not relevant to Info, which does
     not have title pages.  *Note `@title' `@subtitle' and `@author'
     Commands: title subtitle author.

`@summarycontents'
     Print a short table of contents.  Not relevant to Info, which uses
     menus rather than tables of contents.  A synonym for
     `@shortcontents'.  *Note Generating a Table of Contents: Contents.

`@syncodeindex FROM-INDEX INTO-INDEX'
     Merge the index named in the first argument into the index named in
     the second argument, printing the entries from the first index in
     `@code' font.  *Note Combining Indices::.

`@synindex FROM-INDEX INTO-INDEX'
     Merge the index named in the first argument into the index named in
     the second argument.  Do not change the font of FROM-INDEX
     entries.  *Note Combining Indices::.

`@t{TEXT}'
     Print TEXT in a fixed-width, typewriter-like font. No effect in
     Info.  *Note Fonts::.

`@table FORMATTING-COMMAND'
     Begin a two-column table, using `@item' for each entry.  Write
     each first column entry on the same line as `@item'.  First column
     entries are printed in the font resulting from FORMATTING-COMMAND.
      Pair with `@end table'. *Note Making a Two-column Table:
     Two-column Tables. Also see *Note `@ftable' and `@vtable': ftable
     vtable, and *Note `@itemx': itemx.

`@TeX{}'
     Insert the logo TeX.  *Note Inserting TeX and (C): TeX and
     copyright.

`@tex'
     Enter TeX completely.  Pair with `@end tex'.  *Note Using Ordinary
     TeX Commands: Using Ordinary TeX Commands.

`@thischapter'
     In a heading or footing, stands for the number and name of the
     current chapter, in the format `Chapter 1: Title'.  *Note How to
     Make Your Own Headings: Custom Headings.

`@thischaptername'
     In a heading or footing, stands for the name of the current
     chapter. *Note How to Make Your Own Headings: Custom Headings.

`@thisfile'
     In a heading or footing, stands for the name of the current
     `@include' file.  Does not insert anything if not within an
     `@include' file.  *Note How to Make Your Own Headings: Custom
     Headings.

`@thispage'
     In a heading or footing, stands for the current page number. *Note
     How to Make Your Own Headings: Custom Headings.

`@thistitle'
     In a heading or footing, stands for the name of the document, as
     specified by the `@settitle' command.  *Note How to Make Your Own
     Headings: Custom Headings.

`@tindex ENTRY'
     Add ENTRY to the index of data types.  *Note  Defining the Entries
     of an Index: Index Entries.

`@title TITLE'
     In a printed manual, set a title flush to the left-hand side of the
     page in a larger than normal font and underline it with a black
     rule. Not relevant to Info, which does not have title pages.
     *Note The `@title' `@subtitle' and `@author' Commands: title
     subtitle author.

`@titlefont{TEXT}'
     In a printed manual, print TEXT in a larger than normal font. Not
     relevant to Info, which does not have title pages. *Note The
     `@titlefont' `@center' and `@sp' Commands: titlefont center sp.

`@titlepage'
     Indicate to Texinfo the beginning of the title page.  Write
     command on a line of its own.  Pair with `@end titlepage'.
     Nothing between `@titlepage' and `@end titlepage' appears in Info.
     *Note `@titlepage': titlepage.

`@today{}'
     Insert the current date, in `1 Jan 1900' style.  *Note How to Make
     Your Own Headings: Custom Headings.

`@top TITLE'
     In a Texinfo file to be formatted with `makeinfo', identify the
     topmost `@node' line in the file, which must be written on the line
     immediately preceding the `@top' command.  Used for `makeinfo''s
     node pointer insertion feature.  The title is underlined with
     asterisks.  Both the `@node' line and the `@top' line normally
     should be enclosed by `@ifinfo' and `@end ifinfo'.  In TeX and
     `texinfo-format-buffer', the `@top' command is merely a synonym
     for `@unnumbered'.  *Note Creating Pointers with `makeinfo':
     makeinfo Pointer Creation.

`@unnumbered TITLE'
     In a printed manual, begin a chapter that appears without chapter
     numbers of any kind.  The title appears in the table of contents
     of a printed manual.  In Info, the title is underlined with
     asterisks. *Note `@unnumbered' and `@appendix': unnumbered &
     appendix.

`@unnumberedsec TITLE'
     In a printed manual, begin a section that appears without section
     numbers of any kind.  The title appears in the table of contents
     of a printed manual.  In Info, the title is underlined with equal
     signs. *Note Section Commands: unnumberedsec appendixsec heading.

`@unnumberedsubsec TITLE'
     In a printed manual, begin an unnumbered subsection within a
     chapter.  The title appears in the table of contents of a printed
     manual.  In Info, the title is underlined with hyphens. *Note
     `@unnumberedsubsec' `@appendixsubsec' `@subheading':
     unnumberedsubsec appendixsubsec subheading.

`@unnumberedsubsubsec TITLE'
     In a printed manual, begin an unnumbered subsubsection within a
     chapter.  The title appears in the table of contents of a printed
     manual.  In Info, the title is underlined with periods. *Note The
     `subsub' Commands: subsubsection.

`@var{METASYNTACTIC-VARIABLE}'
     Highlight a metasyntactic variable, which is something that stands
     for another piece of text.  *Note Indicating Metasyntactic
     Variables: var.

`@vindex ENTRY'
     Add ENTRY to the index of variables.  *Note  Defining the Entries
     of an Index: Index Entries.

`@vskip AMOUNT'
     In a printed manual, insert whitespace so as to push text on the
     remainder of the page towards the bottom of the page.  Used in
     formatting the copyright page with the argument `0pt plus 1filll'.
      (Note spelling of `filll'.)  `@vskip' may be used only in
     contexts ignored for Info.  *Note  The Copyright Page and Printed
     Permissions: Copyright & Permissions.

`@vtable FORMATTING-COMMAND'
     Begin a two-column table, using `@item' for each entry.
     Automatically enter each of the items in the first column into the
     index of variables.  Pair with `@end vtable'.  The same as
     `@table', except for indexing.  *Note  `@ftable' and `@vtable':
     ftable vtable.

`@w{TEXT}'
     Prevent TEXT from being split across two lines.  Do not end a
     paragraph that uses `@w' with an `@refill' command. In the Texinfo
     file, keep TEXT on one line. *Note `@w': w.

`@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
     Make a reference that starts with `See' in a printed manual.
     Follow command with a punctuation mark.  Only the first argument is
     mandatory.  *Note `@xref': xref.


File: texinfo,  Node: Tips,  Next: Sample Texinfo File,  Prev: Command List,  Up: Top

Tips and Hints
**************

   Here are some tips for writing Texinfo documentation:

   * Write in the present tense, not in the past or the future.

   * Write actively!  For example, write "We recommend that ..." rather
     than "It is recommended that ...".

   * Use 70 or 72 as your fill column.  Longer lines are hard to read.

   * Include a copyright notice and copying permissions.

Index, index, index!
....................

   Write many index entries, in different ways. Readers like indices;
they are helpful and convenient.

   Although it is easiest to write index entries as you write the body
of the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.

   Here are more hints we have found valuable:

   * Write each index entry differently, so each entry refers to a
     different place in the document.  The index of an Info file lists
     only one location for each entry.

   * Write index entries only where a topic is discussed significantly.
      For example, it is not useful to index "debugging information" in
     a chapter on reporting bugs.  Someone who wants to know about
     debugging information will certainly not find it in that chapter.

   * Consistently capitalize the first word of every index entry, or
     else use lower case.  According to convention, you should
     capitalize the first word of an index entry.  However, this
     practice may make an index look crowded.  Some writers prefer
     lower case.  Regardless of which you prefer, choose one style and
     stick to it.  Mixing the two styles looks bad.

   * Always capitalize or use upper case for those words in an index for
     which this is proper, such as names of countries or acronyms.

   * Write the indexing commands that refer to a whole section
     immediately after the section command, and write the indexing
     commands that refer to the paragraph before the paragraph.

     For example:

          @section The Dog and the Fox
          @cindex Jumping, in general
          @cindex Leaping

          @cindex Dog, lazy, jumped over
          @cindex Lazy dog jumped over
          @cindex Fox, jumps over dog
          @cindex Quick fox jumps over dog
          The quick brown fox jumps over the lazy dog.

     (Note that the example shows entries for the same concept that are
     written in different ways--`Lazy dog', and `Dog, lazy'--so readers
     can look up the concept in different ways.)

Blank lines
...........

   * Insert a blank line between a sectioning command and the first
     following sentence or paragraph, or between the indexing commands
     associated with the sectioning command and the first following
     sentence or paragraph, as shown in the tip on indexing.
     Otherwise, a formatter may fold title and paragraph together.

   * Always insert a blank line before an `@table' command and after an
     `@end table' command; but never insert a blank line after an
     `@table' command or before an `@end table' command.

     For example:

          Types of fox:

          @table @samp
          @item Quick
          Jump over lazy dogs.

          @item Brown
          Also jump over lazy dogs.
          @end table

          @noindent
          On the other hand, ...

     Insert blank lines before and after `@itemize' ... `@end itemize'
     and `@enumerate' ... `@end enumerate' in the same way.

Complete phrases
................

   Complete phrases are easier to read than ....

   * Write entries in an itemized list as complete sentences; or at
     least, as complete phrases.  Incomplete expressions ... awkward
     ... like this.

   * Write the prefatory sentence or phrase for a multi-item list or
     table as a complete expression.  Do not write "You can set:";
     instead, write "You can set these variables:".  The former
     expression sounds cut off.

Editions, dates and versions
............................

   Write the edition and version numbers and date in three places in
every manual:

  1. In the first `@ifinfo' section, for people reading the Texinfo
     file.

  2. In the `@titlepage' section, for people reading the printed manual.

  3. In the `Top' node, for people reading the Info file.

Also, it helps to write a note before the first ifinfo section to
explain what you are doing.

For example:

     @c ===> NOTE! <==
     @c Specify the edition and version numbers and date
     @c in *three* places:
     @c   1. First ifinfo section  2. title page  3. top node
     @c To find the locations, search for !!set

     @ifinfo
     @c !!set edition, date, version
     This is Edition 4.03, January 1992,
     of the @cite{GDB Manual} for GDB Version 4.3.
     ...

Definition Commands
...................

   Definition commands are `@deffn', `@defun', `@defmac', and the like,
and enable you to write descriptions in a uniform format.

   * Write just one definition command for each entity you define with a
     definition command.  The automatic indexing feature creates an
     index entry that leads the reader to the definition.

   * Use `@table' ... `@end table' in an appendix that contains a
     summary of functions, not `@deffn' or other definition commands.

Capitalization
..............

   * Capitalize `Texinfo'; it is a name.  Do not write the `x' or `i'
     in upper case.

   * Capitalize `Info'; it is a name.

   * Write TeX using the `@TeX{}' command.  Note the uppercase `T' and
     `X'.  This command causes the formatters to typeset the name
     according to the wishes of Donald Knuth, who wrote TeX.

Spaces
......

   Do not use spaces to format a Texinfo file, except inside of
`@example' ... `@end example' and similar commands.

   For example, TeX fills the following:

         @kbd{C-x v}
         @kbd{M-x vc-next-action}
            Perform the next logical operation
            on the version-controlled file
            corresponding to the current buffer.

so it looks like this:

     `C-x v' `M-x vc-next-action' Perform the next logical operation on
     the version-controlled file corresponding to the current buffer.

In this case, the text should be formatted with `@table', `@item', and
`@itemx', to create a table.

@code, @samp, @var, and `---'
.............................

   * Use `@code' around Lisp symbols, including command names. For
     example:

          The main function is @code{vc-next-action}, ...

   * Avoid putting letters such as `s' immediately after an `@code'.
     Such letters look bad.

   * Use `@var' around meta-variables.  Do not write angle brackets
     around them.

   * Use three hyphens in a row, `---', to indicate a long dash.  TeX
     typesets these as a long dash and the Info formatters reduce three
     hyphens to two.

Periods Outside of Quotes
.........................

   Place periods and other punctuation marks *outside* of quotations,
unless the punctuation is part of the quotation.  This practice goes
against convention, but enables the reader to distinguish between the
contents of the quotation and the whole passage.

   For example, you should write the following sentence with the period
outside the end quotation marks:

     Evidently, `au' is an abbreviation for ``author''.

since `au' does *not* serve as an  abbreviation for `author.' (with a
period following the word).

Introducing New Terms
.....................

   * Introduce new terms so that a user who does not know them can
     understand them from context; or write a definition for the term.

     For example, in the following, the terms "check in", "register" and
     "delta" are all appearing for the first time; the example sentence
     should be rewritten so they are understandable.

          The major function assists you in checking in a file to your
          version control system and registering successive sets of
          changes to it as deltas.

   * Use the `@dfn' command around a word being introduced, to indicate
     that the user should not expect to know the meaning already, and
     should expect to learn the meaning from this passage.

@pxref
......

   Absolutely never use `@pxref' except in the special context for
which it is designed: inside parentheses, with the closing parenthesis
following immediately after the closing brace.  One formatter
automatically inserts closing punctuation and the other does not.  This
means that the output looks right both in printed output and in an Info
file, but only when the command is used inside parentheses.

Invoking from a Shell
.....................

   You can invoke programs such as Emacs, GCC, and GAWK from a shell.
The documentation for each program should contain a section that
describes this.  Unfortunately, if the node names and titles for these
sections are all different, readers find it hard to search for the
section.

   Name such sections with a phrase beginning with the word
`Invoking ...', as in `Invoking Emacs'; this way users can find the
section easily.

ANSI C Syntax
.............

   When you use `@example' to describe a C function's calling
conventions, use the ANSI C syntax, like this:

     void dld_init (char *@var{path});

And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with `@var'.

   Avoid the obsolete style that looks like this:

     #include <dld.h>

     dld_init (path)
     char *path;

   Also, it is best to avoid writing `#include' above the declaration
just to indicate that the function is declared in a header file.  The
practice may give the misimpression that the `#include' belongs near
the declaration of the function.  Either state explicitly which header
file holds the declaration or, better yet, name the header file used
for a group of functions at the beginning of the section that describes
the functions.

Bad Examples
............

   Here are several examples of bad writing to avoid:

     If you are working with other people, it assists in coordinating
     everyone's changes so they do not step on each other.

It is not clear what `it' refers to.

     SCCS, RCS and other version-control systems all perform similar
     functions in broadly similar ways (it is this resemblance which
     makes a unified control mode like this possible).

Say, "... makes a unified interface such as VC mode possible."

     When you are done editing the file, you must perform a
     `@dfn'{check in}.

Say, " ... you must `@dfn'{check in} the new version." That flows
better.

And Finally ...
...............

   * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
     in the name `Bach'.  But pronounce Texinfo as in `speck':
     `teckinfo'.

   * Write notes for yourself at the very end of a Texinfo file after
     the `@bye'.  None of the formatters process text after the `@bye';
     it is as if the text were within `@ignore' ... `@end ignore'.


File: texinfo,  Node: Sample Texinfo File,  Next: Sample Permissions,  Prev: Tips,  Up: Top

A Sample Texinfo File
*********************

   Here is a complete, short sample Texinfo file, without any
commentary. You can see this file, with comments, in the first chapter.
*Note A Short Sample Texinfo File: Short Sample.

     \input texinfo   @c -*-texinfo-*-
     @c %**start of header
     @setfilename sample.info
     @settitle Sample Document
     @c %**end of header

     @setchapternewpage odd

     @ifinfo
     This is a short example of a complete Texinfo file.

     Copyright @copyright{} 1990 Free Software Foundation, Inc.
     @end ifinfo

     @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

     @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

     @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.

     @node    Concept Index,    ,  First Chapter, Top
     @comment node-name,    next,  previous,      up
     @unnumbered Concept Index

     @printindex cp

     @contents
     @bye


File: texinfo,  Node: Sample Permissions,  Next: Include Files,  Prev: Sample Texinfo File,  Up: Top

Sample Permissions
******************

   Texinfo files should contain sections that tell the readers that they
have the right to copy and distribute the Texinfo file, the Info file,
the printed manual, and any accompanying software.  Here are samples
containing the standard text of the Free Software Foundation copying
permission notice for an Info file and printed manual.

   *Note Distribution: (emacs)Distrib, for an example of the text that
could be used in the software "Distribution", "General Public License",
and "NO WARRANTY" sections of a document.

* Menu:

* Inserting Permissions::       How to put permissions in your document.
* ifinfo Permissions::          Sample `ifinfo' copying permissions.
* Titlepage Permissions::       Sample Titlepage copying permissions.


File: texinfo,  Node: Inserting Permissions,  Next: ifinfo Permissions,  Up: Sample Permissions

Inserting Permissions
=====================

   In a Texinfo file, the first `@ifinfo' section usually begins with a
line that says what the file documents.  This is what a person reading
the unprocessed Texinfo file or using the advanced Info command `g *'
sees first.  *note Advanced Info commands: (info)Expert, for more
information. (A reader using the regular Info commands will usually
start reading at the first node and skip this first section, which is
not in a node.)

   In the `@ifinfo' section, the summary sentence should be followed by
a copyright notice and then by the copying permission notice.  One of
the copying permission paragraphs is enclosed in `@ignore' and `@end
ignore' commands.  This paragraph states that the Texinfo file can be
processed through TeX and printed, provided the printed manual carries
the proper copying permission notice.  This paragraph is not made part
of the Info file since it is not relevant to the Info file; but it is a
mandatory part of the Texinfo file since it permits people to process
the Texinfo file in TeX.

   In the printed manual, the Free Software Foundation copying
permission notice follows the copyright notice and publishing
information and is located within the region delineated by the
`@titlepage' and `@end titlepage' commands.  The copying permission
notice is exactly the same as the notice in the `@ifinfo' section
except that the paragraph enclosed in `@ignore' and `@end ignore'
commands is not part of the notice.

   To make it simple to copy the permission notice into each section of
the Texinfo file, the complete permission notices for each section are
reproduced in full below.

   Note that you may need to specify the correct name of a section
mentioned in the permission notice.  For example, in `The GDB Manual',
the name of the section referring to the General Public License is
called the "GDB General Public License", but in the sample shown below,
that section is referred to generically as the "General Public License".


File: texinfo,  Node: ifinfo Permissions,  Next: Titlepage Permissions,  Prev: Inserting Permissions,  Up: Sample Permissions

`ifinfo' Copying Permissions
============================

   In the `@ifinfo' section of the Texinfo file, the standard Free
Software Foundation permission notices reads as follows:

     This file documents ...

     Copyright 1988 Free Software Foundation, Inc.

     Permission is granted to make and distribute verbatim
     copies of this manual provided the copyright notice and
     this permission notice are preserved on all copies.

     @ignore
     Permission is granted to process this file through TeX
     and print the results, provided the printed document
     carries a copying permission notice identical to this
     one except for the removal of this paragraph (this
     paragraph not being relevant to the printed manual).

     @end ignore
     Permission is granted to copy and distribute modified
     versions of this manual under the conditions for
     verbatim copying, provided also that the sections
     entitled ``Distribution'' and ``General Public License''
     are included exactly as in the original, and 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
     the sections entitled ``Distribution'' and ``General
     Public License'' may be included in a translation
     approved by the author instead of in the original
     English.