This is texinfo, produced by makeinfo version 4.8 from texinfo.txi.
This manual is for GNU Texinfo (version 4.8, 29 December 2004), a
documentation system that can produce both online information and a
printed manual from a single source.
Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998,
1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual," and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by
the Free Software Foundation raise funds for GNU development."
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. Update info/dir entries.
* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
END-INFO-DIR-ENTRY
File: texinfo, Node: Footnote Commands, Next: Footnote Styles, Up: Footnotes
12.3.1 Footnote Commands
------------------------
In Texinfo, footnotes are created with the `@footnote' command. This
command is followed immediately by a left brace, then by the text of
the footnote, and then by a terminating right brace. Footnotes may be
of any length (they will be broken across pages if necessary), but are
usually short. The template is:
ordinary text@footnote{TEXT OF FOOTNOTE}
As shown here, the `@footnote' command should come right after the
text being footnoted, with no intervening space; otherwise, the footnote
marker might end up starting a line.
For example, this clause is followed by a sample footnote(1); in the
Texinfo source, it looks like this:
...a sample footnote@footnote{Here is the sample
footnote.}; in the Texinfo source...
As you can see, the source includes two punctuation marks next to each
other; in this case, `.};' is the sequence. This is normal (the first
ends the footnote and the second belongs to the sentence being
footnoted), so don't worry that it looks odd.
In a printed manual or book, the reference mark for a footnote is a
small, superscripted number; the text of the footnote appears at the
bottom of the page, below a horizontal line.
In Info, the reference mark for a footnote is a pair of parentheses
with the footnote number between them, like this: `(1)'. The reference
mark is followed by a cross-reference link to the footnote's text.
In the HTML output, footnote references are marked with a small,
superscripted number which is rendered as a hypertext link to the
footnote text.
By the way, footnotes in the argument of an `@item' command for a
`@table' must be on the same line as the `@item' (as usual). *Note
Two-column Tables::.
---------- Footnotes ----------
(1) Here is the sample footnote.
File: texinfo, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes
12.3.2 Footnote Styles
----------------------
Info has two footnote styles, which determine where the text of the
footnote is located:
* In the `End' node style, all the footnotes for a single node are
placed at the end of that node. The footnotes are separated from
the rest of the node by a line of dashes with the word `Footnotes'
within it. Each footnote begins with an `(N)' reference mark.
Here is an example of a single footnote in the end of node style:
--------- Footnotes ---------
(1) Here is a sample footnote.
* In the `Separate' node style, all the footnotes for a single node
are placed in an automatically constructed node of their own. In
this style, a "footnote reference" follows each `(N)' reference
mark in the body of the node. The footnote reference is actually
a cross reference which you use to reach the footnote node.
The name of the node with the footnotes is constructed by
appending `-Footnotes' to the name of the node that contains the
footnotes. (Consequently, the footnotes' node for the `Footnotes'
node is `Footnotes-Footnotes'!) The footnotes' node has an `Up'
node pointer that leads back to its parent node.
Here is how the first footnote in this manual looks after being
formatted for Info in the separate node style:
File: texinfo.info Node: Overview-Footnotes, Up: Overview
(1) The first syllable of "Texinfo" is pronounced like "speck", not
"hex". ...
Unless your document has long and important footnotes (as in, say,
Gibbon's `Decline and Fall ...'), we recommend the `end' style, as it
is simpler for readers to follow.
Use the `@footnotestyle' command to specify an Info file's footnote
style. Write this command at the beginning of a line followed by an
argument, either `end' for the end node style or `separate' for the
separate node style.
For example,
@footnotestyle end
or
@footnotestyle separate
Write an `@footnotestyle' command before or shortly after the
end-of-header line at the beginning of a Texinfo file. (If you include
the `@footnotestyle' command between the start-of-header and
end-of-header lines, the region formatting commands will format
footnotes as specified.)
If you do not specify a footnote style, the formatting commands use
their default style. Currently, `texinfo-format-buffer' and
`texinfo-format-region' use the `separate' style and `makeinfo' uses
the `end' style.
File: texinfo, Node: Indices, Next: Insertions, Prev: Special Displays, Up: Top
13 Indices
**********
Using Texinfo, you can generate indices without having to sort and
collate entries manually. In an index, the entries are listed in
alphabetical order, together with information on how to find the
discussion of each entry. In a printed manual, this information
consists of page numbers. In an Info file, this information is a menu
entry leading to the first node referenced.
Texinfo provides several predefined kinds of index: an index for
functions, an index for variables, an index for concepts, and so on.
You can combine indices or use them for other than their canonical
purpose. Lastly, you can define your own new indices.
*Note Printing Indices & Menus::, for information on how to print
indices.
* Menu:
* Index Entries:: Choose different words for index entries.
* Predefined Indices:: Use different indices for different kinds
of entries.
* Indexing Commands:: How to make an index entry.
* Combining Indices:: How to combine indices.
* New Indices:: How to define your own indices.
File: texinfo, Node: Index Entries, Next: Predefined Indices, Up: Indices
13.1 Making Index Entries
=========================
When you are making index entries, it is good practice to think of the
different ways people may look for something. Different people _do
not_ think of the same words when they look something up. A helpful
index will have items indexed under all the different words that people
may use. For example, one reader may think it obvious that the
two-letter names for indices should be listed under "Indices,
two-letter names", since the word "Index" is the general concept. But
another reader may remember the specific concept of two-letter names
and search for the entry listed as "Two letter names for indices". A
good index will have both entries and will help both readers.
Like typesetting, the construction of an index is a highly skilled,
professional art, the subtleties of which are not appreciated until you
need to do it yourself.
*Note Printing Indices & Menus::, for information about printing an
index at the end of a book or creating an index menu in an Info file.
File: texinfo, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices
13.2 Predefined Indices
=======================
Texinfo provides six predefined indices. Here are their nominal
meanings, abbreviations, and the corresponding index entry commands:
`cp'
(`@cindex') concept index, for general concepts.
`fn'
(`@findex') function index, for function and function-like names
(such as entry points of libraries).
`ky'
(`@kindex') keystroke index, for keyboard commands.
`pg'
(`@pindex') program index, for names of programs.
`tp'
(`@tindex') data type index, for type names (such as structures
defined in header files).
`vr'
(`@vindex') variable index, for variable names (such as global
variables of libraries).
Not every manual needs all of these, and most manuals use only two or
three at most. The present manual, for example, has two indices: a
concept index and an @-command index (that is actually the function
index but is called a command index in the chapter heading).
You are not required to use the predefined indices strictly for their
canonical purposes. For example, suppose you wish to index some C
preprocessor macros. You could put them in the function index along
with actual functions, just by writing `@findex' commands for them;
then, when you print the "Function Index" as an unnumbered chapter, you
could give it the title `Function and Macro Index' and all will be
consistent for the reader.
On the other hand, it is best not to stray too far from the meaning of
the predefined indices. Otherwise, in the event that your text is
combined with other text from other manuals, the index entries will not
match up. Instead, define your own new index (*note New Indices::).
We recommend having a single index in the final document whenever
possible, however many source indices you use, since then readers have
only one place to look. Two or more source indices can be combined
into one output index using the `@synindex' or `@syncodeindex' commands
(*note Combining Indices::).
File: texinfo, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices
13.3 Defining the Entries of an Index
=====================================
The data to make an index come from many individual indexing commands
scattered throughout the Texinfo source file. Each command says to add
one entry to a particular index; after formatting, the index will give
the current page number or node name as the reference.
An index entry consists of an indexing command at the beginning of a
line followed, on the rest of the line, by the entry.
For example, this section begins with the following five entries for
the concept index:
@cindex Defining indexing entries
@cindex Index entries, defining
@cindex Entries for an index
@cindex Specifying index entries
@cindex Creating index entries
Each predefined index has its own indexing command--`@cindex' for the
concept index, `@findex' for the function index, and so on, as listed
in the previous section.
Concept index entries consist of text. The best way to write an index
is to choose entries that are terse yet clear. If you can do this, the
index often looks better if the entries are not capitalized, but
written just as they would appear in the middle of a sentence.
(Capitalize proper names and acronyms that always call for upper case
letters.) This is the case convention we use in most GNU manuals'
indices.
If you don't see how to make an entry terse yet clear, make it longer
and clear--not terse and confusing. If many of the entries are several
words long, the index may look better if you use a different convention:
to capitalize the first word of each entry. But do not capitalize a
case-sensitive name such as a C or Lisp function name or a shell
command; that would be a spelling error.
Whichever case convention you use, please use it consistently!
Entries in indices other than the concept index are symbol names in
programming languages, or program names; these names are usually
case-sensitive, so use upper and lower case as required for them.
By default, entries for a concept index are printed in a small roman
font and entries for the other indices are printed in a small `@code'
font. You may change the way part of an entry is printed with the
usual Texinfo commands, such as `@file' for file names (*note Marking
Text::), and `@r' for the normal roman font (*note Fonts::).
Caution: Do not use a colon in an index entry. In Info, a colon
separates the menu entry name from the node name, so a colon in
the entry itself confuses Info. *Note Menu Parts::, for more
information about the structure of a menu entry.
File: texinfo, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices
13.4 Combining Indices
======================
Sometimes you will want to combine two disparate indices such as
functions and concepts, perhaps because you have few enough entries
that a separate index would look silly.
You could put functions into the concept index by writing `@cindex'
commands for them instead of `@findex' commands, and produce a
consistent manual by printing the concept index with the title
`Function and Concept Index' and not printing the `Function Index' at
all; but this is not a robust procedure. It works only if your
document is never included as part of another document that is designed
to have a separate function index; if your document were to be included
with such a document, the functions from your document and those from
the other would not end up together. Also, to make your function names
appear in the right font in the concept index, you would need to
enclose every one of them between the braces of `@code'.
* Menu:
* 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.
File: texinfo, Node: syncodeindex, Next: synindex, Up: Combining Indices
13.4.1 `@syncodeindex'
----------------------
When you want to combine functions and concepts into one index, you
should index the functions with `@findex' and index the concepts with
`@cindex', and use the `@syncodeindex' command to redirect the function
index entries into the concept index.
The `@syncodeindex' command takes two arguments; they are the name of
the index to redirect, and the name of the index to redirect it to.
The template looks like this:
@syncodeindex FROM TO
For this purpose, the indices are given two-letter names:
`cp'
concept index
`fn'
function index
`vr'
variable index
`ky'
key index
`pg'
program index
`tp'
data type index
Write an `@syncodeindex' command before or shortly after the
end-of-header line at the beginning of a Texinfo file. For example, to
merge a function index with a concept index, write the following:
@syncodeindex fn cp
This will cause all entries designated for the function index to merge
in with the concept index instead.
To merge both a variables index and a function index into a concept
index, write the following:
@syncodeindex vr cp
@syncodeindex fn cp
The `@syncodeindex' command puts all the entries from the `from'
index (the redirected index) into the `@code' font, overriding whatever
default font is used by the index to which the entries are now
directed. This way, if you direct function names from a function index
into a concept index, all the function names are printed in the `@code'
font as you would expect.
File: texinfo, Node: synindex, Prev: syncodeindex, Up: Combining Indices
13.4.2 `@synindex'
------------------
The `@synindex' command is nearly the same as the `@syncodeindex'
command, except that it does not put the `from' index entries into the
`@code' font; rather it puts them in the roman font. Thus, you use
`@synindex' when you merge a concept index into a function index.
*Note Printing Indices & Menus::, for information about printing an
index at the end of a book or creating an index menu in an Info file.
File: texinfo, Node: New Indices, Prev: Combining Indices, Up: Indices
13.5 Defining New Indices
=========================
In addition to the predefined indices, you may use the `@defindex' and
`@defcodeindex' commands to define new indices. These commands create
new indexing @-commands with which you mark index entries. The
`@defindex' command is used like this:
@defindex NAME
The name of an index should be a two letter word, such as `au'. For
example:
@defindex au
This defines a new index, called the `au' index. At the same time,
it creates a new indexing command, `@auindex', that you can use to make
index entries. Use this new indexing command just as you would use a
predefined indexing command.
For example, here is a section heading followed by a concept index
entry and two `au' index entries.
@section Cognitive Semantics
@cindex kinesthetic image schemas
@auindex Johnson, Mark
@auindex Lakoff, George
(Evidently, `au' serves here as an abbreviation for "author".)
In general, Texinfo constructs the new indexing command by
concatenating the name of the index with `index'; thus, defining an
`xy' index leads to the automatic creation of an `@xyindex' command.
Use the `@printindex' command to print the index, as you do with the
predefined indices. For example:
@node Author Index
@unnumbered Author Index
@printindex au
The `@defcodeindex' is like the `@defindex' command, except that, in
the printed output, it prints entries in an `@code' font by default
instead of a roman font.
You should define new indices before the end-of-header line of a
Texinfo file, and (of course) before any `@synindex' or `@syncodeindex'
commands (*note Texinfo File Header::).
File: texinfo, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top
14 Special Insertions
*********************
Texinfo provides several commands for inserting characters that have
special meaning in Texinfo, such as braces, and for other graphic
elements that do not correspond to simple characters you can type.
* Menu:
* Atsign Braces Comma:: Inserting @ and {} and ,.
* 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.
* euro:: How to insert the Euro currency 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.
File: texinfo, Node: Atsign Braces Comma, Next: Inserting Space, Up: Insertions
14.1 Inserting @ and {} and ,
=============================
`@' and curly braces are special characters in Texinfo. To insert
these characters so they appear in text, you must put an `@' in front
of these characters to prevent Texinfo from misinterpreting them.
The comma `,' is a special character only in one uncommon context: it
separates arguments to commands that take multiple arguments.
* Menu:
* Inserting an Atsign::
* Inserting Braces::
* Inserting a Comma::
File: texinfo, Node: Inserting an Atsign, Next: Inserting Braces, Up: Atsign Braces Comma
14.1.1 Inserting `@' with `@@'
------------------------------
`@@' stands for a single `@' in either printed or Info output.
Do not put braces after an `@@' command.
File: texinfo, Node: Inserting Braces, Next: Inserting a Comma, Prev: Inserting an Atsign, Up: Atsign Braces Comma
14.1.2 Inserting `{' and `}' with `@{' and `@}'
-----------------------------------------------
`@{' stands for a single `{' in either printed or Info output.
`@}' stands for a single `}' in either printed or Info output.
Do not put braces after either an `@{' or an `@}' command.ppp
File: texinfo, Node: Inserting a Comma, Prev: Inserting Braces, Up: Atsign Braces Comma
14.1.3 Inserting `,' with `@comma{}'
------------------------------------
Ordinarily, a comma `,' is a normal character that can be simply typed
in your input where you need it.
However, Texinfo uses the comma as a special character in one uncommon
context: some commands, such as `@acronym' (*note acronym::) and
`@xref' (*note Cross References::), as well as user-defined macros
(*note Defining Macros::), can take more than one argument. In these
cases, the comma character is used to separate arguments.
Since a comma chacter would confuse Texinfo's parsing for these
commands, you must use the command `,' instead if you want to have an
actual comma in the output. Here are some examples:
@acronym{ABC, A Bizarre @comma{}}
@xref{Comma,, The @comma{} symbol}
@mymac{One argument@comma{} containing a comma}
Although , can be used anywhere, there is no need for it anywhere
except in this unusual case.
File: texinfo, Node: Inserting Space, Next: Inserting Accents, Prev: Atsign Braces Comma, Up: Insertions
14.2 Inserting Space
====================
The following sections describe commands that control spacing of various
kinds within and after sentences.
* Menu:
* 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.
File: texinfo, Node: Not Ending a Sentence, Next: Ending a Sentence, Up: Inserting Space
14.2.1 Not Ending a Sentence
----------------------------
Depending on whether a period or exclamation point or question mark is
inside or at the end of a sentence, less or more space is inserted after
a period in a typeset manual. Since it is not always possible to
determine when a period ends a sentence and when it is used in an
abbreviation, special commands are needed in some circumstances.
Usually, Texinfo can guess how to handle periods, so you do not need to
use the special commands; you just enter a period as you would if you
were using a typewriter, which means you put two spaces after the
period, question mark, or exclamation mark that ends a sentence.
Use the `@:' command after a period, question mark, exclamation mark,
or colon that should not be followed by extra space. For example, use
`@:' after periods that end abbreviations which are not at the ends of
sentences.
For example,
The s.o.p.@: has three parts ...
The s.o.p. has three parts ...
produces
The s.o.p. has three parts ...
The s.o.p. has three parts ...
(Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
Procedure".)
`@:' has no effect on the Info and HTML output. In Docbook and XML,
the previous punctuation character (.?!:) is output as an entity
instead of as the normal character: `. ? ! :'.
This gives further processors a chance to notice and not add the usual
extra space.
Do not put braces after `@:' (or any non-alphabetic command).
File: texinfo, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space
14.2.2 Ending a Sentence
------------------------
Use `@.' instead of a period, `@!' instead of an exclamation point, and
`@?' instead of a question mark at the end of a sentence that ends with
a capital letter. Otherwise, TeX will think the letter is an
abbreviation and will not insert the correct end-of-sentence spacing.
Here is an example:
Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
produces
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
In the Info file output, `@.' is equivalent to a simple `.'; likewise
for `@!' and `@?'.
The meanings of `@:' and `@.' in Texinfo are designed to work well
with the Emacs sentence motion commands (*note Sentences:
(emacs)Sentences.).
Do not put braces after any of these commands.
File: texinfo, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space
14.2.3 Multiple Spaces
----------------------
Ordinarily, TeX collapses multiple whitespace characters (space, tab,
and newline) into a single space. Info output, on the other hand,
preserves whitespace as you type it, except for changing a newline into
a space; this is why it is important to put two spaces at the end of
sentences in Texinfo documents.
Occasionally, you may want to actually insert several consecutive
spaces, either for purposes of example (what your program does with
multiple spaces as input), or merely for purposes of appearance in
headings or lists. Texinfo supports three commands: `@SPACE', `@TAB',
and `@NL', all of which insert a single space into the output. (Here,
`@SPACE' represents an `@' character followed by a space, i.e., `@ ',
and `TAB' and `NL' represent the tab character and end-of-line, i.e.,
when `@' is the last character on a line.)
For example,
Spacey@ @ @ @
example.
produces
Spacey example.
Other possible uses of `@SPACE' have been subsumed by `@multitable'
(*note Multi-column Tables::).
Do not follow any of these commands with braces.
To produce a non-breakable space, see *Note `@tie': tie.
File: texinfo, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space
14.2.4 `@dmn'{DIMENSION}: Format a Dimension
--------------------------------------------
At times, you may want to write `12pt' or `8.5in' with little or no
space between the number and the abbreviation for the dimension. You
can use the `@dmn' command to do this. On seeing the command, TeX
inserts just enough space for proper typesetting; the Info formatting
commands insert no space at all, since the Info file does not require
it.
To use the `@dmn' command, write the number and then follow it
immediately, with no intervening space, by `@dmn', and then by the
dimension within braces. For example,
A4 paper is 8.27@dmn{in} wide.
produces
A4 paper is 8.27in wide.
Not everyone uses this style. Some people prefer `8.27 in.@:' or
`8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases,
however, the formatters may insert a line break between the number and
the dimension, so use `@w' (*note w::). Also, if you write a period
after an abbreviation within a sentence, you should write `@:' after
the period to prevent TeX from inserting extra whitespace, as shown
here. *Note Not Ending a Sentence::.
File: texinfo, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions
14.3 Inserting Accents
======================
Here is a table with the commands Texinfo provides for inserting
floating accents. The commands with non-alphabetic names do not take
braces around their argument (which is taken to be the next character).
(Exception: `@,' _does_ take braces around its argument.) This is so
as to make the source as convenient to type and read as possible, since
accented characters are very common in some languages.
To get the true accented characters output in Info, and not just the
ASCII transliterations, you can use the `--enable-encoding' option to
`makeinfo' (*note makeinfo options::).
Command Output What
@"o o" umlaut accent
@'o o' acute accent
@,{c} c, cedilla accent
@=o o= macron/overbar accent
@^o o^ circumflex accent
@`o o` grave accent
@~o o~ tilde accent
@dotaccent{o} o. overdot accent
@H{o} o'' long Hungarian umlaut
@ringaccent{o} o* ring accent
@tieaccent{oo} oo[ tie-after accent
@u{o} o( breve accent
@ubaraccent{o} o_ underbar accent
@udotaccent{o} .o underdot accent
@v{o} o< hacek/check/caron accent
This table lists the Texinfo commands for inserting other characters
commonly used in languages other than English.
@exclamdown{} ! upside-down !
@questiondown{} ? upside-down ?
@aa{} @AA{} aa AA a,A with circle
@ae{} @AE{} ae AE ae,AE ligatures
@dotless{i} i dotless i
@dotless{j} j dotless j
@l{} @L{} /l /L suppressed-L,l
@o{} @O{} /o /O O,o with slash
@oe{} @OE{} oe OE oe,OE ligatures
@ordf{} @ordm{} a o Spanish ordinals
@ss{} ss es-zet or sharp S
File: texinfo, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions
14.4 Inserting Ellipsis and Bullets
===================================
An "ellipsis" (a line of dots) is not typeset as a string of periods,
so a special command is used for ellipsis in Texinfo. The `@bullet'
command is special, too. Each of these commands is followed by a pair
of braces, `{}', without any whitespace between the name of the command
and the braces. (You need to use braces with these commands because
you can use them next to other text; without the braces, the formatters
would be confused. *Note @-Command Syntax: Command Syntax, for further
information.)
* Menu:
* dots:: How to insert dots ...
* bullet:: How to insert a bullet.
File: texinfo, Node: dots, Next: bullet, Up: Dots Bullets
14.4.1 `@dots'{} (...) and `@enddots'{} (....)
----------------------------------------------
Use the `@dots{}' command to generate an ellipsis, which is three dots
in a row, appropriately spaced ... like so. Do not simply write three
periods in the input file; that would work for the Info file output,
but would produce the wrong amount of space between the periods in the
printed manual.
Similarly, the `@enddots{}' command generates an end-of-sentence
ellipsis, which has different spacing afterwards, .... Look closely to
see the difference.
File: texinfo, Node: bullet, Prev: dots, Up: Dots Bullets
14.4.2 `@bullet'{} (*)
----------------------
Use the `@bullet{}' command to generate a large round dot, or the
closest possible thing to one. In Info, an asterisk is used.
Here is a bullet: *
When you use `@bullet' in `@itemize', you do not need to type the
braces, because `@itemize' supplies them. (*Note `@itemize': itemize.)
File: texinfo, Node: TeX and copyright, Next: euro, Prev: Dots Bullets, Up: Insertions
14.5 Inserting TeX and Legal Symbols: (C), (R)
==============================================
The logo `TeX' is typeset in a special fashion and it needs an
@-command. The copyright and registered symbols, `(C)' and `(R)', is
also special. Each of these commands is followed by a pair of braces,
`{}', without any whitespace between the name of the command and the
braces.
* Menu:
* tex:: The TeX logos.
* copyright symbol:: The copyright symbol (c in a circle).
* registered symbol:: The registered symbol (R in a circle).
File: texinfo, Node: tex, Next: copyright symbol, Up: TeX and copyright
14.5.1 `@TeX'{} (TeX) and `@LaTeX'{} (LaTeX)
--------------------------------------------
Use the `@TeX{}' command to generate `TeX'. In a printed manual, this
is a special logo that is different from three ordinary letters. In
Info, it just looks like `TeX'.
Similarly, use the `@LaTeX{}' command to generate `LaTeX', which is
even more special in printed manuals (and different from the incorrect
`La@TeX{}'. In Info, the result is just `LaTeX'. (LaTeX is another
macro package built on top of TeX, very loosely analogous to Texinfo in
that it emphasizes logical structure, but much (much) larger.)
The spelling of these commands are unusual among Texinfo commands in
that they use both uppercase and lowercase letters.
File: texinfo, Node: copyright symbol, Next: registered symbol, Prev: tex, Up: TeX and copyright
14.5.2 `@copyright{}' ((C))
---------------------------
Use the `@copyright{}' command to generate the copyright symbol, `(C)'.
Where possible, this is a `c' inside a circle; in Info, this is `(C)'.
File: texinfo, Node: registered symbol, Prev: copyright symbol, Up: TeX and copyright
14.5.3 `@registeredsymbol{}' ((R))
----------------------------------
Use the `@registeredsymbol{}' command to generate the registered
symbol, `(R)'. Where possible, this is an `R' inside a circle; in
Info, this is `(R)'.
File: texinfo, Node: euro, Next: pounds, Prev: TeX and copyright, Up: Insertions
14.6 `@euro'{} (Euro ): Euro currency symbol
============================================
Use the `@euro{}' command to generate `Euro '. Where possible, this is
the symbol for the Euro currency, invented as part of the European
economic unification relatively recently. In plain Info, it is the
word `Euro '. (The space is included in the text transliteration since
typically there would be no space after the symbol, so it would be
inappropriate to have a space in the source document.)
Texinfo cannot magically synthesize support for the Euro symbol where
the underlying system (fonts, software, whatever) does not support it.
Therefore, in many cases it is preferable to use the word "Euro". (In
banking circles, the abbreviation for the Euro is EUR.)
In order to get the Euro symbol in encoded Info output, for example,
it is necessary to specify `@documentencoding ISO-8859-15'. (*Note
`@documentencoding': documentencoding.) The Euro symbol is in ISO
8859-15 (aka Latin 9), and is _not_ in the more widely-used and
supported ISO 8859-1 (Latin 1).
File: texinfo, Node: pounds, Next: minus, Prev: euro, Up: Insertions
14.7 `@pounds'{} (#): Pounds Sterling
=====================================
Use the `@pounds{}' command to generate `#'. Where possible, this is
the symbol for the currency pounds sterling. In Info, it is a `#'.
File: texinfo, Node: minus, Next: math, Prev: pounds, Up: Insertions
14.8 `@minus'{} (-): Inserting a Minus Sign
===========================================
Use the `@minus{}' command to generate a minus sign. In a fixed-width
font, this is a single hyphen, but in a proportional font, the symbol
is the customary length for a minus sign--a little longer than a
hyphen, shorter than an em-dash:
`-' is a minus sign generated with `@minus{}',
`-' is a hyphen generated with the character `-',
`--' is an em-dash for text.
In the fixed-width font used by Info, `@minus{}' is the same as a
hyphen.
You should not use `@minus{}' inside `@code' or `@example' because
the width distinction is not made in the fixed-width font they use.
When you use `@minus' to specify the mark beginning each entry in an
itemized list, you do not need to type the braces (*note `@itemize':
itemize.).
File: texinfo, Node: math, Next: Glyphs, Prev: minus, Up: Insertions
14.9 `@math': Inserting Mathematical Expressions
================================================
You can write a short mathematical expression with the `@math' command.
Write the mathematical expression between braces, like this:
@math{(a + b)(a + b) = a^2 + 2ab + b^2}
This produces the following in Info and HTML:
(a + b)(a + b) = a^2 + 2ab + b^2
Thus, the `@math' command has no effect on the Info and HTML output;
`makeinfo' just reproduces the input, it does not try to interpret the
mathematics in any way.
`@math' implies `@tex'. This not only makes it possible to write
superscripts and subscripts (as in the above example), but also allows
you to use any of the plain TeX math control sequences. It's
conventional to use `\' instead of `@' for these commands. As in:
@math{\sin 2\pi \equiv \cos 3\pi}
which looks like the input in Info and HTML:
\sin 2\pi \equiv \cos 3\pi
Since `\' is an escape character inside `@math', you can use `@\' to
get a literal backslash (`\\' will work in TeX, but you'll get the
literal `\\' in Info). `@\' is not defined outside of `@math', since a
`\' ordinarily produces a literal `\'.
For displayed equations, you must at present use TeX directly (*note
Raw Formatter Commands::).
File: texinfo, Node: Glyphs, Prev: math, Up: Insertions
14.10 Glyphs for Examples
=========================
In Texinfo, code is often illustrated in examples that are delimited by
`@example' and `@end example', or by `@lisp' and `@end lisp'. In such
examples, you can indicate the results of evaluation or an expansion
using `=>' or `==>'. Likewise, there are commands to insert glyphs to
indicate printed output, error messages, equivalence of expressions,
and the location of point.
The glyph-insertion commands do not need to be used within an
example, but most often they are. Every glyph-insertion command is
followed by a pair of left- and right-hand braces.
* Menu:
* 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.
File: texinfo, Node: Glyphs Summary, Next: result, Up: Glyphs
14.10.1 Glyphs Summary
----------------------
Here are the different glyph commands:
=>
`@result{}' points to the result of an expression.
==>
`@expansion{}' shows the results of a macro expansion.
-|
`@print{}' indicates printed output.
error-->
`@error{}' indicates that the following text is an error message.
==
`@equiv{}' indicates the exact equivalence of two forms.
-!-
`@point{}' shows the location of point.
* Menu:
* result::
* expansion::
* Print Glyph::
* Error Glyph::
* Equivalence::
* Point Glyph::
File: texinfo, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs
14.10.2 `@result{}' (=>): Indicating Evaluation
-----------------------------------------------
Use the `@result{}' command to indicate the result of evaluating an
expression.
The `@result{}' command is displayed as `=>' in Info and HTML and as
a true double stemmed arrow in the printed output.
Thus, the following,
(cdr '(1 2 3))
=> (2 3)
may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
File: texinfo, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs
14.10.3 `@expansion{}' (==>): Indicating an Expansion
-----------------------------------------------------
When an expression is a macro call, it expands into a new expression.
You can indicate the result of the expansion with the `@expansion{}'
command.
The `@expansion{}' command is displayed as `==>' in Info and HTML,
and as a long arrow with a flat base in the printed output.
For example, the following
@lisp
(third '(a b c))
@expansion{} (car (cdr (cdr '(a b c))))
@result{} c
@end lisp
produces
(third '(a b c))
==> (car (cdr (cdr '(a b c))))
=> c
which may be read as:
`(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
result of evaluating the expression is `c'.
Often, as in this case, an example looks better if the `@expansion{}'
and `@result{}' commands are indented.
File: texinfo, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs
14.10.4 `@print{}' (-|): Indicating Printed Output
--------------------------------------------------
Sometimes an expression will print output during its execution. You
can indicate the printed output with the `@print{}' command.
The `@print{}' command is displayed as `-|' in Info and HTML and
(similarly) as a horizontal dash butting against a vertical bar in the
printed output.
In the following example, the printed text is indicated with `-|',
and the value of the expression follows on the last line.
(progn (print 'foo) (print 'bar))
-| foo
-| bar
=> bar
In a Texinfo source file, this example is written as follows:
@lisp
(progn (print 'foo) (print 'bar))
@print{} foo
@print{} bar
@result{} bar
@end lisp
File: texinfo, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs
14.10.5 `@error{}' (error-->): Indicating an Error Message
----------------------------------------------------------
A piece of code may cause an error when you evaluate it. You can
designate the error message with the `@error{}' command.
The `@error{}' command is displayed as `error-->' in Info and HTML
and as the word `error' in a box in the printed output.
Thus,
@lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end lisp
produces
(+ 23 'x)
error--> Wrong type argument: integer-or-marker-p, x
This indicates that the following error message is printed when you
evaluate the expression:
Wrong type argument: integer-or-marker-p, x
`error-->' itself is not part of the error message.
File: texinfo, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs
14.10.6 `@equiv{}' (==): Indicating Equivalence
-----------------------------------------------
Sometimes two expressions produce identical results. You can indicate
the exact equivalence of two forms with the `@equiv{}' command.
The `@equiv{}' command is displayed as `==' in Info and HTML and as a
standard mathematical equivalence sign (three parallel horizontal
lines) in the printed output.
Thus,
@lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end lisp
produces
(make-sparse-keymap) == (list 'keymap)
This indicates that evaluating `(make-sparse-keymap)' produces
identical results to evaluating `(list 'keymap)'.
File: texinfo, Node: Point Glyph, Prev: Equivalence, Up: Glyphs
14.10.7 `@point{}' (-!-): Indicating Point in a Buffer
------------------------------------------------------
Sometimes you need to show an example of text in an Emacs buffer. In
such examples, the convention is to include the entire contents of the
buffer in question between two lines of dashes containing the buffer
name.
You can use the `@point{}' command to show the location of point in
the text in the buffer. (The symbol for point, of course, is not part
of the text in the buffer; it indicates the place _between_ two
characters where point is located.)
The `@point{}' command is displayed as `-!-' in Info and HTML and as
a small five pointed star in the printed output.
The following example shows the contents of buffer `foo' before and
after evaluating a Lisp command to insert the word `changed'.
---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------
(insert "changed ")
=> nil
---------- Buffer: foo ----------
This is the changed -!-contents of foo.
---------- Buffer: foo ----------
In a Texinfo source file, the example is written like this:
@example
---------- Buffer: foo ----------
This is the @point{}contents of foo.
---------- Buffer: foo ----------
(insert "changed ")
@result{} nil
---------- Buffer: foo ----------
This is the changed @point{}contents of foo.
---------- Buffer: foo ----------
@end example
File: texinfo, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
15 Forcing and Preventing Breaks
********************************
Usually, a Texinfo file is processed both by TeX and by one of the Info
formatting commands. Line, paragraph, or page breaks sometimes occur
in the `wrong' place in one or other form of output. You must ensure
that text looks right both in the printed manual and in the Info file.
For example, in a printed manual, page breaks may occur awkwardly in
the middle of an example; to prevent this, you can hold text together
using a grouping command that keeps the text from being split across
two pages. Conversely, you may want to force a page break where none
would occur normally. Fortunately, problems like these do not often
arise. When they do, use the break, break prevention, or pagination
commands.
* Menu:
* Break Commands:: Summary of break-related commands.
* Line Breaks:: Forcing line breaks.
* - and hyphenation:: Helping TeX with hyphenation points.
* w:: Preventing unwanted line breaks in text.
* tie:: Inserting an unbreakable but varying space.
* sp:: Inserting blank lines.
* page:: Forcing the start of a new page.
* group:: Preventing unwanted page breaks.
* need:: Another way to prevent unwanted page breaks.
File: texinfo, Node: Break Commands, Next: Line Breaks, Up: Breaks
15.1 Break Commands
===================
The break commands create or allow line and paragraph breaks:
`@*'
Force a line break.
`@sp N'
Skip N blank lines.
`@-'
Insert a discretionary hyphen.
`@hyphenation{HY-PHEN-A-TED WORDS}'
Define hyphen points in HY-PHEN-A-TED WORDS.
These commands hold text together on a single line:
`@w{TEXT}'
Prevent TEXT from being split and hyphenated across two lines.
`@tie{}'
Insert a normal interword space at which a line break may not
occur.
The pagination commands apply only to printed output, since Info
files do not have pages.
`@page'
Start a new page in the printed manual.
`@group'
Hold text together that must appear on one printed page.
`@need MILS'
Start a new printed page if not enough space on this one.
File: texinfo, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
15.2 `@*' and `@/': Generate and Allow Line Breaks
==================================================
The `@*' command forces a line break in both the printed manual and in
Info. The `@/' command allows a line break (printed manual only).
Here is an example with `@*':
This line @* is broken @*in two places.
produces
This line
is broken
in two places.
The `@/' command can be useful within a url (*note `@uref': uref.),
which tend to be long and are otherwise unbreakable. For example:
The official Texinfo home page is on the GNU web site:
@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}.
produces
The official Texinfo home page is on the GNU web site:
`http://www.gnu.org/software/gnu/texinfo'.
Without the `@/' commands, TeX would have nowhere to break the line.
`@/' has no effect in the online output.
File: texinfo, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
15.3 `@-' and `@hyphenation': Helping TeX Hyphenate
===================================================
Although TeX's hyphenation algorithm is generally pretty good, it does
miss useful hyphenation points from time to time. (Or, far more
rarely, insert an incorrect hyphenation.) So, for documents with an
unusual vocabulary or when fine-tuning for a printed edition, you may
wish to help TeX out. Texinfo supports two commands for this:
`@-'
Insert a discretionary hyphen, i.e., a place where TeX can (but
does not have to) hyphenate. This is especially useful when you
notice an overfull hbox is due to TeX missing a hyphenation (*note
Overfull hboxes::). TeX will not insert any hyphenation points
itself into a word containing `@-'.
`@hyphenation{HY-PHEN-A-TED WORDS}'
Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
a `-' at each hyphenation point. For example:
@hyphenation{man-u-script man-u-scripts}
TeX only uses the specified hyphenation points when the words
match exactly, so give all necessary variants.
Info output is not hyphenated, so these commands have no effect there.
File: texinfo, Node: w, Next: tie, Prev: - and hyphenation, Up: Breaks
15.4 `@w'{TEXT}: Prevent Line Breaks
====================================
`@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT, for both
TeX and `makeinfo'.
Thus, you can use `@w' to produce a non-breakable space, fixed at the
width of a normal interword space:
@w{ } @w{ } @w{ } indentation.
produces:
indentation.
The space from `@w{ }', as well as being non-breakable, also will not
stretch or shrink. Sometimes that is what you want, for instance if
you're doing indenting manual. However, usually you want a normal
interword space that does stretch and shrink (in the printed output);
see the `@tie' command in the next section.
You can also use the `@w' command to prevent TeX from automatically
hyphenating a long name or phrase that happens to fall near the end of
a line. `makeinfo' does not ever hyphenate words.
You can also use `@w' to avoid unwanted keyword expansion in source
control systems. For example, to literally write $Id$ in your
document, use `@w{$}Id$'.
File: texinfo, Node: tie, Next: sp, Prev: w, Up: Breaks
15.5 `@tie{}': Inserting an Unbreakable Space
=============================================
The `@tie{}' command produces a normal interword space at which a line
break may not occur. Always write it with following (empty) braces, as
usual for commands used within a paragraph. Here's an example:
@TeX{} was written by Donald E.@tie{}Knuth.
produces:
TeX was written by Donald E. Knuth.
There are two important differences between `@tie{}' and `@w{ }':
* The space produced by `@tie{}' will stretch and shrink slightly
along with the normal interword spaces in the paragraph; the space
produced by `@w{ }' will not vary.
* `@tie{}' allows hyphenation of the surrounding words, while
`@w{ }' inhibits hyphenation of those words (for TeXnical reasons,
namely that it produces an `\hbox').
File: texinfo, Node: sp, Next: page, Prev: tie, Up: Breaks
15.6 `@sp' N: Insert Blank Lines
================================
A line beginning with and containing only `@sp N' generates N blank
lines of space in both the printed manual and the Info file. `@sp'
also forces a paragraph break. For example,
@sp 2
generates two blank lines.
The `@sp' command is most often used in the title page.
File: texinfo, Node: page, Next: group, Prev: sp, Up: Breaks
15.7 `@page': Start a New Page
==============================
A line containing only `@page' starts a new page in a printed manual.
The command has no effect on Info files since they are not paginated.
An `@page' command is often used in the `@titlepage' section of a
Texinfo file to start the copyright page.
File: texinfo, Node: group, Next: need, Prev: page, Up: Breaks
15.8 `@group': Prevent Page Breaks
==================================
The `@group' command (on a line by itself) is used inside an `@example'
or similar construct to begin an unsplittable vertical group, which
will appear entirely on one page in the printed output. The group is
terminated by a line containing only `@end group'. These two lines
produce no output of their own, and in the Info file output they have
no effect at all.
Although `@group' would make sense conceptually in a wide variety of
contexts, its current implementation works reliably only within
`@example' and variants, and within `@display', `@format', `@flushleft'
and `@flushright'. *Note Quotations and Examples::. (What all these
commands have in common is that each line of input produces a line of
output.) In other contexts, `@group' can cause anomalous vertical
spacing.
This formatting requirement means that you should write:
@example
@group
...
@end group
@end example
with the `@group' and `@end group' commands inside the `@example' and
`@end example' commands.
The `@group' command is most often used to hold an example together
on one page. In this Texinfo manual, more than 100 examples contain
text that is enclosed between `@group' and `@end group'.
If you forget to end a group, you may get strange and unfathomable
error messages when you run TeX. This is because TeX keeps trying to
put the rest of the Texinfo file onto the one page and does not start
to generate error messages until it has processed considerable text.
It is a good rule of thumb to look for a missing `@end group' if you
get incomprehensible error messages in TeX.
File: texinfo, Node: need, Prev: group, Up: Breaks
15.9 `@need MILS': Prevent Page Breaks
======================================
A line containing only `@need N' starts a new page in a printed manual
if fewer than N mils (thousandths of an inch) remain on the current
page. Do not use braces around the argument N. The `@need' command
has no effect on Info files since they are not paginated.
This paragraph is preceded by an `@need' command that tells TeX to
start a new page if fewer than 800 mils (eight-tenths inch) remain on
the page. It looks like this:
@need 800
This paragraph is preceded by ...
The `@need' command is useful for preventing orphans (single lines at
the bottoms of printed pages).
File: texinfo, Node: Definition Commands, Next: Conditionals, Prev: Breaks, Up: Top
16 Definition Commands
**********************
The `@deffn' command and the other "definition commands" enable you to
describe functions, variables, macros, commands, user options, special
forms and other such artifacts in a uniform format.
In the Info file, a definition causes the entity
category--`Function', `Variable', or whatever--to appear at the
beginning of the first line of the definition, followed by the entity's
name and arguments. In the printed manual, the command causes TeX to
print the entity's name and its arguments on the left margin and print
the category next to the right margin. In both output formats, the
body of the definition is indented. Also, the name of the entity is
entered into the appropriate index: `@deffn' enters the name into the
index of functions, `@defvr' enters it into the index of variables, and
so on (*note Predefined Indices::).
A manual need not and should not contain more than one definition for
a given name. An appendix containing a summary should use `@table'
rather than the definition commands.
* Menu:
* Def Cmd Template:: Writing descriptions using definition commands.
* Def Cmd Continuation Lines:: Continuing the heading over source lines.
* Optional Arguments:: Handling optional and repeated arguments.
* deffnx:: Group two or more `first' lines.
* Def Cmds in Detail:: Reference for all the definition commands.
* Def Cmd Conventions:: Conventions for writing definitions.
* Sample Function Definition:: An example.
File: texinfo, Node: Def Cmd Template, Next: Def Cmd Continuation Lines, Up: Definition Commands
16.1 The Template for a Definition
==================================
The `@deffn' command is used for definitions of entities that resemble
functions. To write a definition using the `@deffn' command, write the
`@deffn' command at the beginning of a line and follow it on the same
line by the category of the entity, the name of the entity itself, and
its arguments (if any). Then write the body of the definition on
succeeding lines. (You may embed examples in the body.) Finally, end
the definition with an `@end deffn' command written on a line of its
own.
The other definition commands follow the same format: a line with the
`@def...' command and whatever arguments are appropriate for that
command; the body of the definition; and a corresponding `@end' line.
The template for a definition looks like this:
@deffn CATEGORY NAME ARGUMENTS...
BODY-OF-DEFINITION
@end deffn
For example,
@deffn Command forward-word count
This command moves point forward @var{count} words
(or backward if @var{count} is negative). ...
@end deffn
produces
-- Command: forward-word count
This function moves point forward COUNT words (or backward if
COUNT is negative). ...
Capitalize the category name like a title. If the name of the
category contains spaces, as in the phrase `Interactive Command',
enclose it in braces. For example:
@deffn {Interactive Command} isearch-forward
...
@end deffn
Otherwise, the second word will be mistaken for the name of the entity.
As a general rule, when any of the arguments in the heading line
_except_ the last one are more than one word, you need to enclose them
in braces.
Some of the definition commands are more general than others. The
`@deffn' command, for example, is the general definition command for
functions and the like--for entities that may take arguments. When you
use this command, you specify the category to which the entity belongs.
Three predefined, specialized variations (`@defun', `@defmac', and
`@defspec') specify the category for you: "Function", "Macro", and
"Special Form" respectively. (In Lisp, a special form is an entity
much like a function.) Similarly, the general `@defvr' command is
accompanied by several specialized variations for describing particular
kinds of variables.
*Note Sample Function Definition::, for a detailed example of a
function definition, including the use of `@example' inside the
definition.
Unfortunately, due to implementation difficulties, macros are not
expanded in `@deffn' and all the other definition commands.
File: texinfo, Node: Def Cmd Continuation Lines, Next: Optional Arguments, Prev: Def Cmd Template, Up: Definition Commands
16.2 Definition Command Continuation Lines
==========================================
The heading line of a definition command can get very long. Therefore,
Texinfo has a special syntax allowing them to be continued over
multiple lines of the source file: a lone `@' at the end of each line
to be continued. Here's an example:
@defun fn-name @
arg1 arg2 arg3
This is the basic continued defun.
@end defun
produces:
-- Function: fn-name arg1 arg2 arg3
This is the basic continued defun.
As you can see, the continued lines are combined, as if they had been
typed on one source line.
Although this example only shows a one-line continuation,
continuations may extend over any number of lines; simply put an `@' at
the end of each line to be continued.
The `@' character does not have to be the last character on the
physical line: whitespace is allowed (and ignored) afterwards.
In general, any number of spaces or tabs around the `@' continuation
character, both on the line with the `@' and on the continued line, are
collapsed into a single space. There is one exception: the Texinfo
processors will not fully collapse whitespace around a continuation
inside braces. For example:
@deffn {Category @
Name} ...
The output (not shown) has excess space between `Category' and `Name'.
In this case, simply elide any unwanted whitespace in your input, or
put the continuation `@' outside braces.
`@' does not (currently) function as a continuation character in
_any_ other context. Ordinarily, `@' followed by a whitespace
character (space, tab, newline) produces a normal interword space
(*note Multiple Spaces::).
File: texinfo, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Continuation Lines, Up: Definition Commands
16.3 Optional and Repeated Arguments
====================================
Some entities take optional or repeated arguments, which may be
specified by a distinctive glyph that uses square brackets and
ellipses. For example, a special form often breaks its argument list
into separate arguments in more complicated ways than a straightforward
function.
An argument enclosed within square brackets is optional. Thus,
[OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument
followed by an ellipsis is optional and may be repeated more than once.
Thus, REPEATED-ARGS`...' stands for zero or more arguments.
Parentheses are used when several arguments are grouped into additional
levels of list structure in Lisp.
Here is the `@defspec' line of an example of an imaginary special
form:
-- Special Form: foobar (VAR [FROM TO [INC]]) BODY...
In this example, the arguments FROM and TO are optional, but must both
be present or both absent. If they are present, INC may optionally be
specified as well. These arguments are grouped with the argument VAR
into a list, to distinguish them from BODY, which includes all
remaining elements of the form.
In a Texinfo source file, this `@defspec' line is written like this
(except it would not be split over two lines, as it is in this example).
@defspec foobar (@var{var} [@var{from} @var{to}
[@var{inc}]]) @var{body}@dots{}
The function is listed in the Command and Variable Index under `foobar'.
File: texinfo, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands
16.4 Two or More `First' Lines
==============================
To create two or more `first' or header lines for a definition, follow
the first `@deffn' line by a line beginning with `@deffnx'. The
`@deffnx' command works exactly like `@deffn' except that it does not
generate extra vertical white space between it and the preceding line.
For example,
@deffn {Interactive Command} isearch-forward
@deffnx {Interactive Command} isearch-backward
These two search commands are similar except ...
@end deffn
produces
-- Interactive Command: isearch-forward
-- Interactive Command: isearch-backward
These two search commands are similar except ...
Each definition command has an `x' form: `@defunx', `@defvrx',
`@deftypefunx', etc.
The `x' forms work similarly to `@itemx' (*note itemx::).
File: texinfo, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands
16.5 The Definition Commands
============================
Texinfo provides more than a dozen definition commands, all of which
are described in this section.
The definition commands automatically enter the name of the entity in
the appropriate index: for example, `@deffn', `@defun', and `@defmac'
enter function names in the index of functions; `@defvr' and `@defvar'
enter variable names in the index of variables.
Although the examples that follow mostly illustrate Lisp, the commands
can be used for other programming languages.
* Menu:
* 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.
* Data Types:: The definition command for data types.
* Abstract Objects:: Commands for object-oriented programming.
File: texinfo, Node: Functions Commands, Next: Variables Commands, Up: Def Cmds in Detail
16.5.1 Functions and Similar Entities
-------------------------------------
This section describes the commands for describing functions and similar
entities:
`@deffn CATEGORY NAME ARGUMENTS...'
The `@deffn' command is the general definition command for
functions, interactive commands, and similar entities that may take
arguments. You must choose a term to describe the category of
entity being defined; for example, "Function" could be used if the
entity is a function. The `@deffn' command is written at the
beginning of a line and is followed on the same line by the
category of entity being described, the name of this particular
entity, and its arguments, if any. Terminate the definition with
`@end deffn' on a line of its own.
For example, here is a definition:
@deffn Command forward-char nchars
Move point forward @var{nchars} characters.
@end deffn
This shows a rather terse definition for a "command" named
`forward-char' with one argument, NCHARS.
`@deffn' and prints argument names such as NCHARS in slanted type
in the printed output, because we think of these names as
metasyntactic variables--they stand for the actual argument values.
Within the text of the description, however, write an argument name
explicitly with `@var' to refer to the value of the argument. In
the example above, we used `@var{nchars}' in this way.
In the unusual case when an argument name contains `--', or
another character sequence which is treated specially (*note
Conventions::), use `@var' around the argument. This causes the
name to be printed in slanted typewriter, instead of the regular
slanted font, exactly as input.
The template for `@deffn' is:
@deffn CATEGORY NAME ARGUMENTS...
BODY-OF-DEFINITION
@end deffn
`@defun NAME ARGUMENTS...'
The `@defun' command is the definition command for functions.
`@defun' is equivalent to `@deffn Function ...'. Terminate the
definition with `@end defun' on a line of its own. Thus, the
template is:
@defun FUNCTION-NAME ARGUMENTS...
BODY-OF-DEFINITION
@end defun
`@defmac NAME ARGUMENTS...'
The `@defmac' command is the definition command for macros.
`@defmac' is equivalent to `@deffn Macro ...' and works like
`@defun'.
`@defspec NAME ARGUMENTS...'
The `@defspec' command is the definition command for special
forms. (In Lisp, a special form is an entity much like a function,
*note Special Forms: (elisp)Special Forms.) `@defspec' is
equivalent to `@deffn {Special Form} ...' and works like `@defun'.
All these commands create entries in the index of functions.
File: texinfo, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail
16.5.2 Variables and Similar Entities
-------------------------------------
Here are the commands for defining variables and similar entities:
`@defvr CATEGORY NAME'
The `@defvr' command is a general definition command for something
like a variable--an entity that records a value. You must choose
a term to describe the category of entity being defined; for
example, "Variable" could be used if the entity is a variable.
Write the `@defvr' command at the beginning of a line and follow
it on the same line by the category of the entity and the name of
the entity.
Capitalize the category name like a title. If the name of the
category contains spaces, as in the name "User Option", enclose it
in braces. Otherwise, the second word will be mistaken for the
name of the entity. For example,
@defvr {User Option} fill-column
This buffer-local variable specifies
the maximum width of filled lines.
...
@end defvr
Terminate the definition with `@end defvr' on a line of its own.
The template is:
@defvr CATEGORY NAME
BODY-OF-DEFINITION
@end defvr
`@defvr' creates an entry in the index of variables for NAME.
`@defvar NAME'
The `@defvar' command is the definition command for variables.
`@defvar' is equivalent to `@defvr Variable ...'.
For example:
@defvar kill-ring
...
@end defvar
The template is:
@defvar NAME
BODY-OF-DEFINITION
@end defvar
`@defvar' creates an entry in the index of variables for NAME.
`@defopt NAME'
The `@defopt' command is the definition command for "user
options", i.e., variables intended for users to change according to
taste; Emacs has many such (*note Variables: (emacs)Variables.).
`@defopt' is equivalent to `@defvr {User Option} ...' and works
like `@defvar'. It creates an entry in the index of variables.
File: texinfo, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail
16.5.3 Functions in Typed Languages
-----------------------------------
The `@deftypefn' command and its variations are for describing
functions in languages in which you must declare types of variables and
functions, such as C and C++.
`@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
The `@deftypefn' command is the general definition command for
functions and similar entities that may take arguments and that are
typed. The `@deftypefn' command is written at the beginning of a
line and is followed on the same line by the category of entity
being described, the type of the returned value, the name of this
particular entity, and its arguments, if any.
For example,
@deftypefn {Library Function} int foobar
(int @var{foo}, float @var{bar})
...
@end deftypefn
(where the text before the "...", shown above as two lines, would
actually be a single line in a real Texinfo file) produces the
following in Info:
-- Library Function: int foobar (int FOO, float BAR)
...
This means that `foobar' is a "library function" that returns an
`int', and its arguments are FOO (an `int') and BAR (a `float').
Since in typed languages, the actual names of the arguments are
typically scattered among data type names and keywords, Texinfo
cannot find them without help. You can either (a) write everything
as straight text, and it will be printed in slanted type; (b) use
`@var' for the variable names, which will uppercase the variable
names in Info and use the slanted typewriter font in printed
output; (c) use `@var' for the variable names and `@code' for the
type names and keywords, which will be dutifully obeyed.
The template for `@deftypefn' is:
@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
BODY-OF-DESCRIPTION
@end deftypefn
Note that if the CATEGORY or DATA TYPE is more than one word then
it must be enclosed in braces to make it a single argument.
If you are describing a procedure in a language that has packages,
such as Ada, you might consider using `@deftypefn' in a manner
somewhat contrary to the convention described in the preceding
paragraphs. For example:
@deftypefn stacks private push @
(@var{s}:in out stack; @
@var{n}:in integer)
...
@end deftypefn
(The `@deftypefn' arguments are shown using continuations (*note
Def Cmd Continuation Lines::), but could be on a single line in a
real Texinfo file.)
In this instance, the procedure is classified as belonging to the
package `stacks' rather than classified as a `procedure' and its
data type is described as `private'. (The name of the procedure
is `push', and its arguments are S and N.)
`@deftypefn' creates an entry in the index of functions for NAME.
`@deftypefun DATA-TYPE NAME ARGUMENTS...'
The `@deftypefun' command is the specialized definition command
for functions in typed languages. The command is equivalent to
`@deftypefn Function ...'. The template is:
@deftypefun TYPE NAME ARGUMENTS...
BODY-OF-DESCRIPTION
@end deftypefun
`@deftypefun' creates an entry in the index of functions for NAME.
File: texinfo, Node: Typed Variables, Next: Data Types, Prev: Typed Functions, Up: Def Cmds in Detail
16.5.4 Variables in Typed Languages
-----------------------------------
Variables in typed languages are handled in a manner similar to
functions in typed languages. *Note Typed Functions::. The general
definition command `@deftypevr' corresponds to `@deftypefn' and the
specialized definition command `@deftypevar' corresponds to
`@deftypefun'.
`@deftypevr CATEGORY DATA-TYPE NAME'
The `@deftypevr' command is the general definition command for
something like a variable in a typed language--an entity that
records a value. You must choose a term to describe the category
of the entity being defined; for example, "Variable" could be used
if the entity is a variable.
The `@deftypevr' command is written at the beginning of a line and
is followed on the same line by the category of the entity being
described, the data type, and the name of this particular entity.
For example:
@deftypevr {Global Flag} int enable
...
@end deftypevr
produces the following in Info:
-- Global Flag: int enable
...
The template is:
@deftypevr CATEGORY DATA-TYPE NAME
BODY-OF-DESCRIPTION
@end deftypevr
`@deftypevar DATA-TYPE NAME'
The `@deftypevar' command is the specialized definition command
for variables in typed languages. `@deftypevar' is equivalent to
`@deftypevr Variable ...'. The template is:
@deftypevar DATA-TYPE NAME
BODY-OF-DESCRIPTION
@end deftypevar
These commands create entries in the index of variables.
File: texinfo, Node: Data Types, Next: Abstract Objects, Prev: Typed Variables, Up: Def Cmds in Detail
16.5.5 Data Types
-----------------
Here is the command for data types:
`@deftp CATEGORY NAME ATTRIBUTES...'
The `@deftp' command is the generic definition command for data
types. The command is written at the beginning of a line and is
followed on the same line by the category, by the name of the type
(which is a word like `int' or `float'), and then by names of
attributes of objects of that type. Thus, you could use this
command for describing `int' or `float', in which case you could
use `data type' as the category. (A data type is a category of
certain objects for purposes of deciding which operations can be
performed on them.)
In Lisp, for example, "pair" names a particular data type, and an
object of that type has two slots called the CAR and the CDR.
Here is how you would write the first line of a definition of
`pair'.
@deftp {Data type} pair car cdr
...
@end deftp
The template is:
@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
BODY-OF-DEFINITION
@end deftp
`@deftp' creates an entry in the index of data types.
File: texinfo, Node: Abstract Objects, Prev: Data Types, Up: Def Cmds in Detail
16.5.6 Object-Oriented Programming
----------------------------------
Here are the commands for formatting descriptions about abstract
objects, such as are used in object-oriented programming. A class is a
defined type of abstract object. An instance of a class is a
particular object that has the type of the class. An instance variable
is a variable that belongs to the class but for which each instance has
its own value.
* Menu:
* Variables: Object-Oriented Variables.
* Methods: Object-Oriented Methods.
File: texinfo, Node: Object-Oriented Variables, Next: Object-Oriented Methods, Up: Abstract Objects
16.5.6.1 Object-Oriented Variables
..................................
These commands allow you to define different sorts of variables in
object-oriented programming languages.
`@defcv CATEGORY CLASS NAME'
The `@defcv' command is the general definition command for
variables associated with classes in object-oriented programming.
The `@defcv' command is followed by three arguments: the category
of thing being defined, the class to which it belongs, and its
name. For instance:
@defcv {Class Option} Window border-pattern
...
@end defcv
produces:
-- Class Option of Window: border-pattern
...
`@defcv' creates an entry in the index of variables.
`@deftypecv CATEGORY CLASS DATA-TYPE NAME'
The `@deftypecv' command is the definition command for typed class
variables in object-oriented programming. It is analogous to
`@defcv' with the addition of the DATA-TYPE parameter to specify
the type of the instance variable. Ordinarily, the data type is a
programming language construct that should be marked with `@code'.
For instance:
@deftypecv {Class Option} Window @code{int} border-pattern
...
@end deftypecv
produces:
-- Class Option of Window: `int' border-pattern
...
`@deftypecv' creates an entry in the index of variables.
`@defivar CLASS NAME'
The `@defivar' command is the definition command for instance
variables in object-oriented programming. `@defivar' is
equivalent to `@defcv {Instance Variable} ...'. For instance:
@defivar Window border-pattern
...
@end defivar
produces:
-- Instance Variable of Window: border-pattern
...
`@defivar' creates an entry in the index of variables.
`@deftypeivar CLASS DATA-TYPE NAME'
The `@deftypeivar' command is the definition command for typed
instance variables in object-oriented programming. It is
analogous to `@defivar' with the addition of the DATA-TYPE
parameter to specify the type of the instance variable.
Ordinarily, the data type is a programming language construct that
should be marked with `@code'. For instance:
@deftypeivar Window @code{int} border-pattern
...
@end deftypeivar
produces:
-- Instance Variable of Window: `int' border-pattern
...
`@deftypeivar' creates an entry in the index of variables.
File: texinfo, Node: Object-Oriented Methods, Prev: Object-Oriented Variables, Up: Abstract Objects
16.5.6.2 Object-Oriented Methods
................................
These commands allow you to define different sorts of function-like
entities resembling methods in object-oriented programming languages.
These entities take arguments, as functions do, but are associated with
particular classes of objects.
`@defop CATEGORY CLASS NAME ARGUMENTS...'
The `@defop' command is the general definition command for these
method-like entities.
For example, some systems have constructs called "wrappers" that
are associated with classes as methods are, but that act more like
macros than like functions. You could use `@defop Wrapper' to
describe one of these.
Sometimes it is useful to distinguish methods and "operations".
You can think of an operation as the specification for a method.
Thus, a window system might specify that all window classes have a
method named `expose'; we would say that this window system
defines an `expose' operation on windows in general. Typically,
the operation has a name and also specifies the pattern of
arguments; all methods that implement the operation must accept
the same arguments, since applications that use the operation do
so without knowing which method will implement it.
Often it makes more sense to document operations than methods. For
example, window application developers need to know about the
`expose' operation, but need not be concerned with whether a given
class of windows has its own method to implement this operation.
To describe this operation, you would write:
@defop Operation windows expose
The `@defop' command is written at the beginning of a line and is
followed on the same line by 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.
The template is:
@defop CATEGORY CLASS NAME ARGUMENTS...
BODY-OF-DEFINITION
@end defop
`@defop' creates an entry, such as ``expose' on `windows'', in the
index of functions.
`@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
The `@deftypeop' command is the definition command for typed
operations in object-oriented programming. It is similar to
`@defop' with the addition of the DATA-TYPE parameter to specify
the return type of the method. `@deftypeop' creates an entry in
the index of functions.
`@defmethod CLASS NAME ARGUMENTS...'
The `@defmethod' command is the definition command for methods in
object-oriented programming. A method is a kind of function that
implements an operation for a particular class of objects and its
subclasses.
`@defmethod' is equivalent to `@defop Method ...'. The command is
written at the beginning of a line and is followed by the name of
the class of the method, the name of the method, and its
arguments, if any.
For example:
@defmethod `bar-class' bar-method argument
...
@end defmethod
illustrates the definition for a method called `bar-method' of the
class `bar-class'. The method takes an argument.
`@defmethod' creates an entry in the index of functions.
`@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...'
The `@deftypemethod' command is the definition command for methods
in object-oriented typed languages, such as C++ and Java. It is
similar to the `@defmethod' command with the addition of the
DATA-TYPE parameter to specify the return type of the method.
`@deftypemethod' creates an entry in the index of functions.
File: texinfo, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands
16.6 Conventions for Writing Definitions
========================================
When you write a definition using `@deffn', `@defun', or one of the
other definition commands, please take care to use arguments that
indicate the meaning, as with the COUNT argument to the `forward-word'
function. Also, if the name of an argument contains the name of a
type, such as INTEGER, take care that the argument actually is of that
type.
File: texinfo, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands
16.7 A Sample Function Definition
=================================
A function definition uses the `@defun' and `@end defun' commands. The
name of the function follows immediately after the `@defun' command and
it is followed, on the same line, by the parameter list.
Here is a definition from *Note Calling Functions: (elisp)Calling
Functions.
-- Function: apply function &rest arguments
`apply' calls FUNCTION with ARGUMENTS, just like `funcall'
but with one difference: the last of ARGUMENTS is a list of
arguments to give to FUNCTION, rather than a single argument.
We also say that this list is "appended" to the other
arguments.
`apply' returns the result of calling FUNCTION. As with
`funcall', FUNCTION must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in `apply'.
(setq f 'list)
=> list
(apply f 'x 'y 'z)
error--> Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
=> 10
(apply '+ '(1 2 3 4))
=> 10
(apply 'append '((a b c) nil (x y z) nil))
=> (a b c x y z)
An interesting example of using `apply' is found in the
description of `mapcar'.
In the Texinfo source file, this example looks like this:
@defun apply function &rest arguments
@code{apply} calls @var{function} with
@var{arguments}, just like @code{funcall} but with one
difference: the last of @var{arguments} is a list of
arguments to give to @var{function}, rather than a single
argument. We also say that this list is @dfn{appended}
to the other arguments.
@code{apply} returns the result of calling
@var{function}. As with @code{funcall},
@var{function} must either be a Lisp function or a
primitive function; special forms and macros do not make
sense in @code{apply}.
@example
(setq f 'list)
@result{} list
(apply f 'x 'y 'z)
@error{} Wrong type argument: listp, z
(apply '+ 1 2 '(3 4))
@result{} 10
(apply '+ '(1 2 3 4))
@result{} 10
(apply 'append '((a b c) nil (x y z) nil))
@result{} (a b c x y z)
@end example
An interesting example of using @code{apply} is found
in the description of @code{mapcar}.
@end defun
In this manual, this function is listed in the Command and Variable
Index under `apply'.
Ordinary variables and user options are described using a format like
that for functions except that variables do not take arguments.
File: texinfo, Node: Conditionals, Next: Internationalization, Prev: Definition Commands, Up: Top
17 Conditionally Visible Text
*****************************
The "conditional commands" allow you to use different text for
different output formats, or for general conditions that you define.
For example, you can use them to specify different text for the printed
manual and the Info output.
The conditional commands comprise the following categories.
* Commands specific to an output format (Info, TeX, HTML, ...).
* Commands specific to any output format _other_ than a given one
(not Info, not TeX, ...).
* `Raw' formatter text for any output format, passed straight
through with no interpretation of @-commands.
* Format-independent variable substitutions, and testing if a
variable is set or clear.
* Menu:
* Conditional Commands:: Text for a given format.
* Conditional Not Commands:: Text for any format other than a given one.
* Raw Formatter Commands:: Using raw formatter commands.
* set clear value:: Variable tests and substitutions.
* Conditional Nesting:: Using conditionals inside conditionals.
File: texinfo, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals
17.1 Conditional Commands
=========================
Texinfo has an `@ifFORMAT' environment for each output format, to allow
conditional inclusion of text for a particular output format.
`@ifinfo' begins segments of text that should be ignored by TeX when
it typesets the printed manual, and by `makeinfo' when not producing
Info output. The segment of text appears only in the Info file and,
for historical compatibility, the plain text output.
The environments for the other formats are analogous:
`@ifdocbook ... @end ifdocbook'
Text to appear only in the Docbook output.
`@ifhtml ... @end ifhtml'
Text to appear only in the HTML output.
`@ifplaintext ... @end ifplaintext'
Text to appear only in the plain text output.
`@iftex ... @end iftex'
Text to appear only in the printed manual.
`@ifxml ... @end ifxml'
Text to appear only in the XML output.
The `@if...' and `@end if...' commands must appear on lines by
themselves in your source file.
Here is an example showing all these conditionals:
@iftex
This text will appear only in the printed manual.
@end iftex
@ifinfo
However, this text will appear only in Info and plain text.
@end ifinfo
@ifhtml
And this text will only appear in HTML.
@end ifhtml
@ifplaintext
Whereas this text will only appear in plain text.
@end ifplaintext
@ifxml
Notwithstanding that this will only appear in XML.
@end ifxml
@ifdocbook
Nevertheless, this will only appear in Docbook.
@end ifdocbook
The preceding example produces the following line:
However, this text will appear only in Info and plain text.
Notice that you only see one of the input lines, depending on which
version of the manual you are reading.
File: texinfo, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals
17.2 Conditional Not Commands
=============================
You can specify text to be included in any output format _other_ than a
given one with the `@ifnot...' environments:
@ifnotdocbook ... @end ifnotdocbook
@ifnothtml ... @end ifnothtml
@ifnotinfo ... @end ifnotinfo
@ifnotplaintext ... @end ifnotplaintext
@ifnottex ... @end ifnottex
@ifnotxml ... @end ifnotxml
The `@ifnot...' command and the `@end' command must appear on lines by
themselves in your actual source file.
If the output file is being made in the given format, the region is
_ignored_. Otherwise, it is included.
There is one exception (for historical compatibility): `@ifnotinfo'
text is omitted for both Info and plain text output, not just Info. To
specify text which appears only in Info and not in plain text, use
`@ifnotplaintext', like this:
@ifinfo
@ifnotplaintext
This will be in Info, but not plain text.
@end ifnotplaintext
@end ifinfo
The regions delimited by these commands are ordinary Texinfo source as
with `@iftex', not raw formatter source as with `@tex' (*note Raw
Formatter Commands::).
File: texinfo, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals
17.3 Raw Formatter Commands
===========================
Inside a region delineated by `@iftex' and `@end iftex', you can embed
some raw TeX commands. The Texinfo processors will ignore such a
region unless TeX output is being produced. You can write the TeX
commands as you would write them in a normal TeX file, except that you
must replace the `\' used by TeX with an `@'. For example, in the
`@titlepage' section of a Texinfo file, you can use the TeX command
`@vskip' to format the copyright page. (The `@titlepage' command
causes Info to ignore the region automatically, as it does with the
`@iftex' command.)
However, most features of plain TeX will not work within `@iftex', as
they are overridden by Texinfo features. The purpose of `@iftex' is to
provide conditional processing for the Texinfo source, not provide
access to underlying formatting features.
You can enter plain TeX completely, and use `\' in the TeX commands,
by delineating a region with the `@tex' and `@end tex' commands. All
plain TeX commands and category codes are restored within an `@tex'
region. The sole exception is that the `@' character still introduces
a command, so that `@end tex' can be recognized properly. As with
`@iftex', Texinfo processors will ignore such a region unless TeX
output is being produced.
In complex cases, you may wish to define new TeX macros within
`@tex'. You must use `\gdef' to do this, not `\def', because `@tex'
regions are processed in a TeX group.
As an example, here is a mathematical expression written in plain TeX:
@tex
$$ \chi^2 = \sum_{i=1}^N
\left (y_i - (a + b x_i)
\over \sigma_i\right)^2 $$
@end tex
The output of this example will appear only in a printed manual. If
you are reading this in Info, you will not see the equation that appears
in the printed manual.
Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
region to be included in HTML output only, and `@html ... @end html'
for a region of raw HTML.
Likewise, you can use `@ifxml ... @end ifxml' to delimit a region to
be included in XML output only, and `@xml ... @end xml' for a region
of raw XML.
Again likewise, you can use `@ifdocbook ... @end ifdocbook' to
delimit a region to be included in Docbook output only, and `@docbook
... @end docbook' for a region of raw Docbook.
In all cases, the exception to the raw processing is that `@' is
still an escape character, so the `@end' command can be recognized.
File: texinfo, Node: set clear value, Next: Conditional Nesting, Prev: Raw Formatter Commands, Up: Conditionals
17.4 `@set', `@clear', and `@value'
===================================
You can direct the Texinfo formatting commands to format or ignore parts
of a Texinfo file with the `@set', `@clear', `@ifset', and `@ifclear'
commands.
Here are brief descriptions of these commands, see the following
sections for more details:
`@set FLAG [VALUE]'
Set the variable FLAG, to the optional VALUE if specifed.
`@clear FLAG'
Undefine the variable FLAG, whether or not it was previously
defined.
`@ifset FLAG'
If FLAG is set, text through the next `@end ifset' command is
formatted. If FLAG is clear, text through the following `@end
ifset' command is ignored.
`@ifclear FLAG'
If FLAG is set, text through the next `@end ifclear' command is
ignored. If FLAG is clear, text through the following `@end
ifclear' command is formatted.
* Menu:
* set value:: Expand a flag variable to a string.
* ifset ifclear:: Format a region if a flag is set.
* value Example:: An easy way to update edition information.
File: texinfo, Node: set value, Next: ifset ifclear, Up: set clear value
17.4.1 `@set' and `@value'
--------------------------
You use the `@set' command to specify a value for a flag, which is
later expanded by the `@value' command.
A "flag" (aka "variable") is an identifier. It is best to use only
letters and numerals in a flag name, not `-' or `_'--they will work in
some contexts, but not all, due to limitations in TeX.
The value is the remainder of the input line, and can contain
anything.
Write the `@set' command like this:
@set foo This is a string.
This sets the value of the flag `foo' to "This is a string.".
The Texinfo formatters then replace an `@value{FLAG}' command with
the string to which FLAG is set. Thus, when `foo' is set as shown
above, the Texinfo formatters convert this:
@value{foo}
to this:
This is a string.
You can write an `@value' command within a paragraph; but you must
write an `@set' command on a line of its own.
If you write the `@set' command like this:
@set foo
without specifying a string, the value of `foo' is the empty string.
If you clear a previously set flag with `@clear FLAG', a subsequent
`@value{flag}' command will report an error.
For example, if you set `foo' as follows:
@set howmuch very, very, very
then the formatters transform
It is a @value{howmuch} wet day.
into
It is a very, very, very wet day.
If you write
@clear howmuch
then the formatters transform
It is a @value{howmuch} wet day.
into
It is a {No value for "howmuch"} wet day.
File: texinfo, Node: ifset ifclear, Next: value Example, Prev: set value, Up: set clear value
17.4.2 `@ifset' and `@ifclear'
------------------------------
When a FLAG is set, the Texinfo formatting commands format text between
subsequent pairs of `@ifset FLAG' and `@end ifset' commands. When the
FLAG is cleared, the Texinfo formatting commands do _not_ format the
text. `@ifclear' operates analogously.
Write the conditionally formatted text between `@ifset FLAG' and
`@end ifset' commands, like this:
@ifset FLAG
CONDITIONAL-TEXT
@end ifset
For example, you can create one document that has two variants, such
as a manual for a `large' and `small' model:
You can use this machine to dig up shrubs
without hurting them.
@set large
@ifset large
It can also dig up fully grown trees.
@end ifset
Remember to replant promptly ...
In the example, the formatting commands will format the text between
`@ifset large' and `@end ifset' because the `large' flag is set.
When FLAG is cleared, the Texinfo formatting commands do _not_ format
the text between `@ifset FLAG' and `@end ifset'; that text is ignored
and does not appear in either printed or Info output.
For example, if you clear the flag of the preceding example by writing
an `@clear large' command after the `@set large' command (but before
the conditional text), then the Texinfo formatting commands ignore the
text between the `@ifset large' and `@end ifset' commands. In the
formatted output, that text does not appear; in both printed and Info
output, you see only the lines that say, "You can use this machine to
dig up shrubs without hurting them. Remember to replant promptly ...".
If a flag is cleared with an `@clear FLAG' command, then the
formatting commands format text between subsequent pairs of `@ifclear'
and `@end ifclear' commands. But if the flag is set with `@set FLAG',
then the formatting commands do _not_ format text between an `@ifclear'
and an `@end ifclear' command; rather, they ignore that text. An
`@ifclear' command looks like this:
@ifclear FLAG
File: texinfo, Node: value Example, Prev: ifset ifclear, Up: set clear value
17.4.3 `@value' Example
-----------------------
You can use the `@value' command to minimize the number of places you
need to change when you record an update to a manual. *Note GNU Sample
Texts::, for the full text of an example of using this to work with
Automake distributions.
This example is adapted from *Note Overview: (make)Top.
1. Set the flags:
@set EDITION 0.35 Beta
@set VERSION 3.63 Beta
@set UPDATED 14 August 1992
@set UPDATE-MONTH August 1992
2. Write text for the `@copying' section (*note copying::):
@copying
This is Edition @value{EDITION},
last updated @value{UPDATED},
of @cite{The GNU Make Manual},
for @code{make}, version @value{VERSION}.
Copyright ...
Permission is granted ...
@end copying
3. Write text for the title page, for people reading the printed
manual:
@titlepage
@title GNU Make
@subtitle A Program for Directing Recompilation
@subtitle Edition @value{EDITION}, ...
@subtitle @value{UPDATE-MONTH}
@page
@insertcopying
...
@end titlepage
(On a printed cover, a date listing the month and the year looks
less fussy than a date listing the day as well as the month and
year.)
4. Write text for the Top node, for people reading the Info file:
@ifnottex
@node Top
@top Make
@insertcopying
...
@end ifnottex
After you format the manual, the `@value' constructs have been
expanded, so the output contains text like this:
This is Edition 0.35 Beta, last updated 14 August 1992,
of `The GNU Make Manual', for `make', Version 3.63 Beta.
When you update the manual, you change only the values of the flags;
you do not need to edit the three sections.
File: texinfo, Node: Conditional Nesting, Prev: set clear value, Up: Conditionals
17.5 Conditional Nesting
========================
Conditionals can be nested; however, the details are a little tricky.
The difficulty comes with failing conditionals, such as `@ifhtml' when
HTML is not being produced, where the included text is to be ignored.
However, it is not to be _completely_ ignored, since it is useful to
have one `@ifset' inside another, for example--that is a way to include
text only if two conditions are met. Here's an example:
@ifset somevar
@ifset anothervar
Both somevar and anothervar are set.
@end ifset
@ifclear anothervar
Somevar is set, anothervar is not.
@end ifclear
@end ifset
Technically, Texinfo requires that for a failing conditional, the
ignored text must be properly nested with respect to that failing
conditional. Unfortunately, it's not always feasible to check that
_all_ conditionals are properly nested, because then the processors
could have to fully interpret the ignored text, which defeats the
purpose of the command. Here's an example illustrating these rules:
@ifset a
@ifset b
@ifclear ok - ok, ignored
@end junky - ok, ignored
@end ifset
@c WRONG - missing @end ifset.
Finally, as mentioned above, all conditional commands must be on lines
by themselves, with no text (even spaces) before or after. Otherwise,
the processors cannot reliably determine which commands to consider for
nesting purposes.
File: texinfo, Node: Internationalization, Next: Defining New Texinfo Commands, Prev: Conditionals, Up: Top
18 Internationalization
***********************
Texinfo has some support for writing in languages other than English,
although this area still needs considerable work.
For a list of the various accented and special characters Texinfo
supports, see *Note Inserting Accents::.
* Menu:
* documentlanguage:: Declaring the current language.
* documentencoding:: Declaring the input encoding.
File: texinfo, Node: documentlanguage, Next: documentencoding, Up: Internationalization
18.1 `@documentlanguage CC': Set the Document Language
======================================================
The `@documentlanguage' command declares the current document language.
Write it on a line by itself, with a two-letter ISO-639 language code
following (list is included below). If you have a multilingual
document, the intent is to be able to use this command multiple times,
to declare each language change. If the command is not used at all,
the default is `en' for English.
At present, this command is ignored in Info and HTML output. For
TeX, it causes the file `txi-CC.tex' to be read (if it exists). Such a
file appropriately redefines the various English words used in TeX
output, such as `Chapter', `See', and so on.
It would be good if this command also changed TeX's ideas of the
current hyphenation patterns (via the TeX primitive `\language'), but
this is unfortunately not currently implemented.
Hereare the valid language codes, from ISO-639.
`aa' Afar `ab' Abkhazian `af' Afrikaans
`am' Amharic `ar' Arabic `as' Assamese
`ay' Aymara `az' Azerbaijani `ba' Bashkir
`be' Byelorussian `bg' Bulgarian `bh' Bihari
`bi' Bislama `bn' Bengali; Bangla `bo' Tibetan
`br' Breton `ca' Catalan `co' Corsican
`cs' Czech `cy' Welsh `da' Danish
`de' German `dz' Bhutani `el' Greek
`en' English `eo' Esperanto `es' Spanish
`et' Estonian `eu' Basque `fa' Persian
`fi' Finnish `fj' Fiji `fo' Faroese
`fr' French `fy' Frisian `ga' Irish
`gd' Scots Gaelic `gl' Galician `gn' Guarani
`gu' Gujarati `ha' Hausa `he' Hebrew
`hi' Hindi `hr' Croatian `hu' Hungarian
`hy' Armenian `ia' Interlingua `id' Indonesian
`ie' Interlingue `ik' Inupiak `is' Icelandic
`it' Italian `iu' Inuktitut `ja' Japanese
`jw' Javanese `ka' Georgian `kk' Kazakh
`kl' Greenlandic `km' Cambodian `kn' Kannada
`ks' Kashmiri `ko' Korean `ku' Kurdish
`ky' Kirghiz `la' Latin `ln' Lingala
`lt' Lithuanian `lo' Laothian `lv' Latvian, Lettish
`mg' Malagasy `mi' Maori `mk' Macedonian
`ml' Malayalam `mn' Mongolian `mo' Moldavian
`mr' Marathi `ms' Malay `mt' Maltese
`my' Burmese `na' Nauru `ne' Nepali
`nl' Dutch `no' Norwegian `oc' Occitan
`om' (Afan) Oromo `or' Oriya `pa' Punjabi
`pl' Polish `ps' Pashto, Pushto `pt' Portuguese
`qu' Quechua `rm' Rhaeto-Romance `rn' Kirundi
`ro' Romanian `ru' Russian `rw' Kinyarwanda
`sa' Sanskrit `sd' Sindhi `sg' Sangro
`sh' Serbo-Croatian `si' Sinhalese `sk' Slovak
`sl' Slovenian `sm' Samoan `sn' Shona
`so' Somali `sq' Albanian `sr' Serbian
`ss' Siswati `st' Sesotho `su' Sundanese
`sv' Swedish `sw' Swahili `ta' Tamil
`te' Telugu `tg' Tajik `th' Thai
`ti' Tigrinya `tk' Turkmen `tl' Tagalog
`tn' Setswana `to' Tonga `tr' Turkish
`ts' Tsonga `tt' Tatar `tw' Twi
`ug' Uighur `uk' Ukrainian `ur' Urdu
`uz' Uzbek `vi' Vietnamese `vo' Volapuk
`wo' Wolof `xh' Xhosa `yi' Yiddish
`yo' Yoruba `za' Zhuang `zh' Chinese
`zu' Zulu
File: texinfo, Node: documentencoding, Prev: documentlanguage, Up: Internationalization
18.2 `@documentencoding ENC': Set Input Encoding
================================================
The `@documentencoding' command declares the input document encoding.
Write it on a line by itself, with a valid encoding specification
following.
At present, Texinfo supports only these encodings:
`US-ASCII'
This has no particular effect, but it's included for completeness.
`ISO-8859-1'
`ISO-8859-15'
`ISO-8859-2'
These specify the standard encodings for Western European (the
first two) and Eastern European languages (the third),
respectively. ISO 8859-15 replaces some little-used characters
from 8859-1 (e.g., precomposed fractions) with more commonly
needed ones, such as the Euro symbol.
A full description of the encodings is beyond our scope here; one
useful reference is `http://czyborra.com/charsets/iso8859.html'.
Specifying an encoding ENC has the following effects:
In Info output, if the option `--enable-encoding' is given to
`makeinfo', a so-called `Local Variables' section (*note File
Variables: (emacs)File Variables.) is output including ENC. This
allows Info readers to set the encoding appropriately.
Local Variables:
coding: ENC
End:
In HTML output, a `<meta>' tag is output, in the `<head>' section of
the HTML, that specifies ENC. Web servers and browsers cooperate to
use this information so the correct encoding is used to display the
page, if supported by the system.
<meta http-equiv="Content-Type" content="text/html;
charset=ENC">
In all other cases, it is recognized but ignored.
File: texinfo, Node: Defining New Texinfo Commands, Next: Hardcopy, Prev: Internationalization, Up: Top
19 Defining New Texinfo Commands
********************************
Texinfo provides several ways to define new commands:
* A Texinfo "macro" allows you to define a new Texinfo command as any
sequence of text and/or existing commands (including other
macros). The macro can have any number of "parameters"--text you
supply each time you use the macro.
Incidentally, these macros have nothing to do with the `@defmac'
command, which is for documenting macros in the subject of the
manual (*note Def Cmd Template::).
* `@alias' is a convenient way to define a new name for an existing
command.
* `@definfoenclose' allows you to define new commands with
customized output in the Info file.
* Menu:
* Defining Macros:: Defining and undefining new commands.
* Invoking Macros:: Using a macro, once you've defined it.
* Macro Details:: Limitations of Texinfo macros.
* alias:: Command aliases.
* definfoenclose:: Customized highlighting.
File: texinfo, Node: Defining Macros, Next: Invoking Macros, Up: Defining New Texinfo Commands
19.1 Defining Macros
====================
You use the Texinfo `@macro' command to define a macro, like this:
@macro MACRONAME{PARAM1, PARAM2, ...}
TEXT ... \PARAM1\ ...
@end macro
The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
when the macro is subsequently used in the document (described in the
next section).
For a macro to work consistently with TeX, MACRONAME must consist
entirely of letters: no digits, hyphens, underscores, or other special
characters. So, we recommend using only letters. However, `makeinfo'
will accept anything except `{}_^='; `_' and `^' are excluded so that
macros can be called in `@math' mode without a following space (*note
`@math': math.).
If a macro needs no parameters, you can define it either with an empty
list (`@macro foo {}') or with no braces at all (`@macro foo').
The definition or "body" of the macro can contain most Texinfo
commands, including previously-defined macros. Not-yet-defined macro
invocations are not allowed; thus, it is not possible to have mutually
recursive Texinfo macros. Also, a macro definition that defines another
macro does not work in TeX due to limitations in the design of `@macro'.
In the macro body, instances of a parameter name surrounded by
backslashes, as in `\PARAM1\' in the example above, are replaced by the
corresponding argument from the macro invocation. You can use
parameter names any number of times in the body, including zero.
To get a single `\' in the macro expansion, use `\\'. Any other use
of `\' in the body yields a warning.
The newlines after the `@macro' line and before the `@end macro' line
are ignored, that is, not included in the macro body. All other
whitespace is treated according to the usual Texinfo rules.
To allow a macro to be used recursively, that is, in an argument to a
call to itself, you must define it with `@rmacro', like this:
@rmacro rmac {arg}
a\arg\b
@end rmacro
...
@rmac{1@rmac{text}2}
This produces the output `a1atextb2b'. With `@macro' instead of
`@rmacro', an error message is given.
You can undefine a macro FOO with `@unmacro FOO'. It is not an error
to undefine a macro that is already undefined. For example:
@unmacro foo
File: texinfo, Node: Invoking Macros, Next: Macro Details, Prev: Defining Macros, Up: Defining New Texinfo Commands
19.2 Invoking Macros
====================
After a macro is defined (see the previous section), you can use
("invoke") it in your document like this:
@MACRONAME {ARG1, ARG2, ...}
and the result will be just as if you typed the body of MACRONAME at
that spot. For example:
@macro foo {p, q}
Together: \p\ & \q\.
@end macro
@foo{a, b}
produces:
Together: a & b.
Thus, the arguments and parameters are separated by commas and
delimited by braces; any whitespace after (but not before) a comma is
ignored. The braces are required in the invocation (but not the
definition), even when the macro takes no arguments, consistent with
all other Texinfo commands. For example:
@macro argless {}
No arguments here.
@end macro
@argless{}
produces:
No arguments here.
To insert a comma, brace, or backslash in an argument, prepend a
backslash, as in
@MACNAME {\\\{\}\,}
which will pass the (almost certainly error-producing) argument `\{},'
to MACNAME. However, commas in parameters, even if escaped by a
backslash, might cause trouble in TeX.
If the macro is defined to take a single argument, and is invoked
without any braces, the entire rest of the line after the macro name is
supplied as the argument. For example:
@macro bar {p}
Twice: \p\ & \p\.
@end macro
@bar aah
produces:
Twice: aah & aah.
If the macro is defined to take a single argument, and is invoked with
braces, the braced text is passed as the argument, regardless of
commas. For example:
@macro bar {p}
Twice: \p\ & \p\.
@end macro
@bar{a,b}
produces:
Twice: a,b & a,b.
File: texinfo, Node: Macro Details, Next: alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands
19.3 Macro Details and Caveats
==============================
Due to unavoidable limitations, certain macro-related constructs cause
problems with TeX. If you get macro-related errors when producing the
printed version of a manual, try expanding the macros with `makeinfo'
by invoking `texi2dvi' with the `-E' option (*note Format with
texi2dvi::).
* As mentioned earlier, macro names must consist entirely of letters.
* It is not advisable to redefine any TeX primitive, plain, or
Texinfo command name as a macro. Unfortunately this is a very large
set of names, and the possible resulting errors are unpredictable.
* All macros are expanded inside at least one TeX group. This means
that `@set' and other such commands have no effect inside a macro.
* Commas in macro arguments, even if escaped by a backslash, don't
always work.
* Macro arguments cannot cross lines.
* It is (usually) best to avoid comments inside macro definitions,
but see the next item.
* Macros containing a command which must be on a line by itself,
such as a conditional, cannot be invoked in the middle of a line.
In general, the interaction of newlines in the macro definitions
and invocations depends on the precise commands and context. You
may be able to work around some problems with judicious use of
`@c'. Suppose you define a macro that is always intended to be
used on a line by itself:
@macro linemac
@cindex whatever
@c
@end macro
...
foo
@linemac
bar
Without the `@c', there will be an unwanted blank line between the
`@cindex whatever' and the `bar' (one newline comes from the macro
definition, one from after the invocation), causing a paragraph
break.
On the other hand, you wouldn't want the `@c' if the macro was
sometimes invoked in the middle of a line (the text after the
invocation would be treated as a comment).
* In general, you can't arbitrarily substitute a macro call for
Texinfo command arguments, even when the text is the same. It
might work with some commands, it fails with others. Best not to
do it at all. For instance, this fails:
@macro offmacro
off
@end macro
@headings @offmacro
You would expect this to be equivalent to `@headings off', but for
TeXnical reasons, it fails with a mysterious error message
(`Paragraph ended before @headings was complete').
* Macros cannot define macros in the natural way. To do this, you
must use conditionals and raw TeX. For example:
@ifnottex
@macro ctor {name, arg}
@macro \name\
something involving \arg\ somehow
@end macro
@end macro
@end ifnottex
@tex
\gdef\ctor#1{\ctorx#1,}
\gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}}
@end tex
The `makeinfo' implementation also has limitations:
* `@verbatim' and macros do not mix; for instance, you can't start a
verbatim block inside a macro and end it outside. (*Note
verbatim::.) Starting any environment inside a macro and ending
it outside may or may not work, for that matter.
* Macros that completely define macros are ok, but it's not possible
to have incorrectly nested macro definitions. That is, `@macro'
and `@end macro' (likewise for `@rmacro') must be correctly
paired. For example, you cannot start a macro definition within a
macro, and then end the nested definition outside the macro.
* `@rmacro' is a kludge.
One more limitation is common to both implementations: white space is
ignored at the beginnings of lines.
Future major revisions of Texinfo may ease some of these limitations
(by introducing a new macro syntax).
File: texinfo, Node: alias, Next: definfoenclose, Prev: Macro Details, Up: Defining New Texinfo Commands
19.4 `@alias NEW=EXISTING'
==========================
The `@alias' command defines a new command to be just like an existing
one. This is useful for defining additional markup names, thus
preserving semantic information in the input even though the output
result may be the same.
Write the `@alias' command on a line by itself, followed by the new
command name, an equals sign, and the existing command name.
Whitespace around the equals sign is ignored. Thus:
@alias NEW = EXISTING
For example, if your document contains citations for both books and
some other media (movies, for example), you might like to define a
macro `@moviecite{}' that does the same thing as an ordinary `@cite{}'
but conveys the extra semantic information as well. You'd do this as
follows:
@alias moviecite = cite
Macros do not always have the same effect as aliases, due to vagaries
of argument parsing. Also, aliases are much simpler to define than
macros. So the command is not redundant. (It was also heavily used in
the Jargon File!)
Aliases must not be recursive, directly or indirectly.
It is not advisable to redefine any TeX primitive, plain, or Texinfo
command name as an alias. Unfortunately this is a very large set of
names, and the possible resulting errors are completely random.
File: texinfo, Node: definfoenclose, Prev: alias, Up: Defining New Texinfo Commands
19.5 `definfoenclose': Customized Highlighting
==============================================
A `@definfoenclose' command may be used to define a highlighting
command for Info, but not for TeX. A command defined using
`@definfoenclose' marks text by enclosing it in strings that precede
and follow the text. You can use this to get closer control of your
Info output.
Presumably, if you define a command with `@definfoenclose' for Info,
you will create a corresponding command for TeX, either in
`texinfo.tex', `texinfo.cnf', or within an `@iftex' in your document.
Write a `@definfoenclose' command on a line and follow it with three
arguments separated by commas. The first argument to `@definfoenclose'
is the @-command name (without the `@'); the second argument is the
Info start delimiter string; and the third argument is the Info end
delimiter string. The latter two arguments enclose the highlighted
text in the Info file. A delimiter string may contain spaces. Neither
the start nor end delimiter is required. If you do not want a start
delimiter but do want an end delimiter, you must follow the command
name with two commas in a row; otherwise, the Info formatting commands
will naturally misinterpret the end delimiter string you intended as
the start delimiter string.
If you do a `@definfoenclose' on the name of a pre-defined macro
(such as `@emph', `@strong', `@t', or `@i'), the enclosure definition
will override the built-in definition.
An enclosure command defined this way takes one argument in braces;
this is intended for new markup commands (*note Marking Text::).
For example, you can write:
@definfoenclose phoo,//,\\
near the beginning of a Texinfo file to define `@phoo' as an Info
formatting command that inserts `//' before and `\\' after the argument
to `@phoo'. You can then write `@phoo{bar}' wherever you want
`//bar\\' highlighted in Info.
Also, for TeX formatting, you could write
@iftex
@global@let@phoo=@i
@end iftex
to define `@phoo' as a command that causes TeX to typeset the argument
to `@phoo' in italics.
Each definition applies to its own formatter: one for TeX, the other
for `texinfo-format-buffer' or `texinfo-format-region'. The
`@definfoenclose' command need not be within `@ifinfo', but the raw TeX
commands do need to be in `@iftex'.
Here is another example: write
@definfoenclose headword, , :
near the beginning of the file, to define `@headword' as an Info
formatting command that inserts nothing before and a colon after the
argument to `@headword'.
`@definfoenclose' definitions must not be recursive, directly or
indirectly.
File: texinfo, Node: Hardcopy, Next: Creating and Installing Info Files, Prev: Defining New Texinfo Commands, Up: Top
20 Formatting and Printing Hardcopy
***********************************
There are three major shell commands for making a printed manual from a
Texinfo file: one for converting the Texinfo file into a file that will
be printed, a second for sorting indices, and a third for printing the
formatted document. When you use the shell commands, you can either
work directly in the operating system shell or work within a shell
inside GNU Emacs.
If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands. In addition to the three commands to
format a file, sort the indices, and print the result, Texinfo mode
offers key bindings for commands to recenter the output buffer, show the
print queue, and delete a job from the print queue.
* Menu:
* Use TeX:: Use TeX to format for hardcopy.
* Format with tex/texindex:: How to format with explicit shell commands.
* Format with texi2dvi:: A simpler way to format.
* 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 to do before you 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 A4 or A5 paper.
* pagesizes:: How to print with customized page sizes.
* Cropmarks and Magnification:: How to print marks to indicate the size
of pages and how to print scaled up output.
* PDF Output:: Portable Document Format output.
* Obtaining TeX:: How to Obtain TeX.
File: texinfo, Node: Use TeX, Next: Format with tex/texindex, Up: Hardcopy
20.1 Use TeX
============
The typesetting program called TeX is used for formatting a Texinfo
file. TeX is a very powerful typesetting program and, if used
correctly, does an exceptionally good job. (*Note How to Obtain TeX:
Obtaining TeX, for information on how to obtain TeX.)
The standalone `makeinfo' program and Emacs functions
`texinfo-format-region' and `texinfo-format-buffer' commands read the
very same @-commands in the Texinfo file as does TeX, but process them
differently to make an Info file (*note Creating an Info File::).
File: texinfo, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Hardcopy
20.2 Format with `tex' and `texindex'
====================