This is texinfo, produced by makeinfo version 4.3 from texinfo.txi.
This manual is for GNU Texinfo (version 4.3, 14 November 2002), 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 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.
* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
END-INFO-DIR-ENTRY
File: texinfo, Node: Abstract Objects, Next: Data Types, Prev: Typed Variables, Up: Def Cmds in Detail
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.
In a definition, if the name of a class is truly a name defined in the
programming system for a class, then you should write an `@code' around
it. Otherwise, it is printed in the usual text font.
`@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. Thus,
@defcv {Class Option} Window border-pattern
...
@end defcv
illustrates how you would write the first line of a definition of
the `border-pattern' class option of the class `Window'.
The template is:
@defcv CATEGORY CLASS NAME
...
@end defcv
`@defcv' 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} ...'
The template is:
@defivar CLASS INSTANCE-VARIABLE-NAME
BODY-OF-DEFINITION
@end defivar
`@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 similar
to `@defivar' with the addition of the DATA-TYPE parameter to
specify the type of the instance variable. `@deftypeivar' creates
an entry in the index of variables.
`@defop CATEGORY CLASS NAME ARGUMENTS...'
The `@defop' command is the general definition command for
entities that may resemble methods in object-oriented programming.
These entities take arguments, as functions do, but are associated
with particular classes of objects.
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.
The template is:
@defmethod CLASS METHOD-NAME ARGUMENTS...
BODY-OF-DEFINITION
@end defmethod
`@defmethod' creates an entry, such as ``bar-method' on
`bar-class'', 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.
File: texinfo, Node: Data Types, Prev: Abstract Objects, Up: Def Cmds in Detail
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: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands
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
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
Conditionally Visible Text
**************************
Sometimes it is good to use different text for different output
formats. For example, you can use the "conditional commands" to specify
different text for the printed manual and the Info output.
Conditional commands may not be nested.
The conditional commands comprise the following categories.
* Commands for HTML, Info, or TeX.
* Commands for not HTML, Info, or TeX.
* Raw TeX or HTML commands.
* Substituting text for all formats, and testing if a flag is set or
clear.
* Menu:
* Conditional Commands:: Specifying text for HTML, Info, or TeX.
* Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
* Raw Formatter Commands:: Using raw TeX or HTML commands.
* set clear value:: Designating which text to format (for
all output formats); and how to set a
flag to a string that you can insert.
File: texinfo, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals
Conditional Commands
====================
Texinfo has an `@if...' 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. The segment of text appears only in
the Info file and (for historical compatibility) the plain text output.
The `@ifinfo' command should appear on a line by itself; end the
Info-only text with a line containing `@end ifinfo' by itself.
The `@iftex' and `@end iftex' commands are analogous to the `@ifinfo'
and `@end ifinfo' commands; they specify text that will appear in the
printed manual but not in the Info file. Likewise for `@ifhtml' and
`@end ifhtml', which specify text to appear only in HTML output. And
for `@ifplaintext' and `@end ifplaintext', which specify text to appear
only in plain text output. And for `@ifxml' and `@end ifxml', for the
XML output.
For example,
@iftex
This text will appear only in the printed manual.
@end iftex
@ifinfo
However, this text will appear only in Info (or 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
And this will only appear in XML output.
@end ifxml
The preceding example produces the following line: However, this text
will appear only in Info (or 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
Conditional Not Commands
========================
You can specify text to be included in any output format _other_ than
some given one with the `@ifnot...' commands:
@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.
With 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:
This will be in Info, but not plain text.
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
Raw Formatter Commands
======================
Inside a region delineated by `@iftex' and `@end iftex', you can
embed some raw TeX commands. Info will ignore these commands since
they are only in that part of the file which is seen by TeX. 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, many features of plain TeX will not work, as they are
overridden by Texinfo features.
You can enter plain TeX completely, and use `\' in the TeX commands,
by delineating a region with the `@tex' and `@end tex' commands. (The
`@tex' command also causes Info to ignore the region, like the `@iftex'
command.) The sole exception is that the `@' character still
introduces a command, so that `@end tex' can be recognized properly.
For 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 (again, except that `@' is still the escape
character, so the `@end' command can be recognized.)
Analogously, 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, except that `@' is still the escape
character, so the `@end' command can be recognized.)
File: texinfo, Node: set clear value, Prev: Raw Formatter Commands, Up: Conditionals
`@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.
Brief descriptions:
`@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
`@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" is an identifier. In general, 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 how-much very, very, very
then the formatters transform
It is a @value{how-much} wet day.
into
It is a very, very, very wet day.
If you write
@clear how-much
then the formatters transform
It is a @value{how-much} wet day.
into
It is a {No value for "how-much"} wet day.
File: texinfo, Node: ifset ifclear, Next: value Example, Prev: set value, Up: set clear value
`@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
`@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 an example of this same principle can work with Automake
distributions, and full texts.
Here is an example 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: Internationalization, Next: Defining New Texinfo Commands, Prev: Conditionals, Up: Top
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
`@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
`@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, such as `ISO-8859-1'.
At present, this is used only in HTML output from `makeinfo'. If a
document encoding ENC is specified, it is used in a `' tag
included in the `' of the output:
File: texinfo, Node: Defining New Texinfo Commands, Next: Hardcopy, Prev: Internationalization, Up: Top
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:: Beyond basic macro usage.
* alias:: Command aliases.
* definfoenclose:: Customized highlighting.
File: texinfo, Node: Defining Macros, Next: Invoking Macros, Up: Defining New Texinfo Commands
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 with TeX, MACRONAME must consist entirely of
letters: no digits, hyphens, underscores, or other special characters.
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
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
Macro Details
=============
Due to unavoidable disparities in the TeX and `makeinfo'
implementations, Texinfo macros have the following limitations.
* All macros are expanded inside at least one TeX group. This means
that `@set' and other such commands will have no effect inside a
macro.
* 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.
* Commas in macro arguments, even if escaped by a backslash, don't
always work.
* The TeX implementation cannot construct macros that 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
* It is best to avoid comments inside macro definitions.
If some macro feature causes errors when producing the printed version
of a manual, try expanding the macros with `makeinfo' by invoking
`texi2dvi' with the `-E' option; see *Note Format with texi2dvi::.
File: texinfo, Node: alias, Next: definfoenclose, Prev: Macro Details, Up: Defining New Texinfo Commands
`@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 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.
File: texinfo, Node: definfoenclose, Prev: alias, Up: Defining New Texinfo Commands
`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
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.
File: texinfo, Node: Use TeX, Next: Format with tex/texindex, Up: Hardcopy
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
Format with `tex' and `texindex'
================================
Format the Texinfo file with the shell command `tex' followed by the
name of the Texinfo file. For example:
tex foo.texi
TeX will produce a "DVI file" as well as several auxiliary files
containing information for indices, cross references, etc. The DVI
file (for "DeVice Independent" file) can be printed on virtually any
device (see the following sections).
The `tex' formatting command itself does not sort the indices; it
writes an output file of unsorted index data. (The `texi2dvi' command
automatically generates indices; *note Format with `texi2dvi': Format
with texi2dvi..) To generate a printed index after running the `tex'
command, you first need a sorted index to work from. The `texindex'
command sorts indices. (The source file `texindex.c' comes as part of
the standard Texinfo distribution, among other places.)
The `tex' formatting command outputs unsorted index files under names
that obey a standard convention: the name of your main input file with
any `.tex' (or similar, *note tex invocation: (web2c)tex invocation.)
extension removed, followed by the two letter names of indices. For
example, the raw index output files for the input file `foo.texinfo'
would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.
Those are exactly the arguments to give to `texindex'.
Instead of specifying all the unsorted index file names explicitly,
you can use `??' as shell wildcards and give the command in this form:
texindex foo.??
This command will run `texindex' on all the unsorted index files,
including any that you have defined yourself using `@defindex' or
`@defcodeindex'. (You may execute `texindex foo.??' even if there are
similarly named files with two letter extensions that are not index
files, such as `foo.el'. The `texindex' command reports but otherwise
ignores such files.)
For each file specified, `texindex' generates a sorted index file
whose name is made by appending `s' to the input file name. The
`@printindex' command looks for a file with that name (*note Printing
Indices & Menus::). `texindex' does not alter the raw index output
file.
After you have sorted the indices, you need to rerun the `tex'
formatting command on the Texinfo file. This regenerates the DVI file,
this time with up-to-date index entries.
Finally, you may need to run `tex' one more time, to get the page
numbers in the cross-references correct.
To summarize, this is a five step process:
1. Run `tex' on your Texinfo file. This generates a DVI file (with
undefined cross-references and no indices), and the raw index files
(with two letter extensions).
2. Run `texindex' on the raw index files. This creates the
corresponding sorted index files (with three letter extensions).
3. Run `tex' again on your Texinfo file. This regenerates the DVI
file, this time with indices and defined cross-references, but
with page numbers for the cross-references from last time,
generally incorrect.
4. Sort the indices again, with `texindex'.
5. Run `tex' one last time. This time the correct page numbers are
written for the cross-references.
Alternatively, it's a one-step process: run `texi2dvi' (*note Format
with texi2dvi::).
You need not run `texindex' each time after you run `tex'. If you do
not, on the next run, the `tex' formatting command will use whatever
sorted index files happen to exist from the previous use of `texindex'.
This is usually ok while you are debugging.
Sometimes you may wish to print a document while you know it is
incomplete, or to print just one chapter of a document. In that case,
the usual auxiliary files that TeX creates and warnings TeX gives when
cross-references are not satisfied are just nuisances. You can avoid
them with the `@novalidate' command, which you must give _before_ the
`@setfilename' command (*note `@setfilename': setfilename.). Thus, the
beginning of your file would look approximately like this:
\input texinfo
@novalidate
@setfilename myfile.info
...
`@novalidate' also turns off validation in `makeinfo', just like its
`--no-validate' option (*note Pointer Validation::).
File: texinfo, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Hardcopy
Format with `texi2dvi'
======================
The `texi2dvi' command automatically runs both `tex' and `texindex'
as many times as necessary to produce a DVI file with sorted indices
and all cross-references resolved. It simplifies the
`tex'--`texindex'--`tex'--`tex' sequence described in the previous
section.
To run `texi2dvi' on an input file `foo.texi', do this (where
`prompt$ ' is your shell prompt):
prompt$ texi2dvi foo.texi
As shown in this example, the input filenames to `texi2dvi' must
include any extension (`.texi', `.texinfo', etc.). Under MS-DOS and
perhaps in other circumstances, you may need to run `sh texi2dvi
foo.texi' instead of relying on the operating system to invoke the
shell on the `texi2dvi' script.
Perhaps the most useful option to `texi2dvi' is `--texinfo=CMD'.
This inserts CMD on a line by itself after the `@setfilename' in a
temporary copy of the input file before running TeX. With this, you
can specify different printing formats, such as `@smallbook' (*note
smallbook::), `@afourpaper' (*note A4 Paper::), or `@pagesizes' (*note
pagesizes::), without actually changing the document source. (You can
also do this on a site-wide basis with `texinfo.cnf'; *note Preparing
for TeX: Preparing for TeX.).
For a list of other options, run `texi2dvi --help'.
File: texinfo, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Hardcopy
Shell Print Using `lpr -d'
==========================
The precise command to print a DVI file depends on your system
installation. Two common ones are `dvips foo.dvi -o' and `lpr -d
foo.dvi'.
For example, the following commands will (perhaps) suffice to sort the
indices, format, and print the `Bison Manual':
tex bison.texinfo
texindex bison.??
tex bison.texinfo
lpr -d bison.dvi
(Remember that the shell commands may be different at your site; but
these are commonly used versions.)
Using the `texi2dvi' shell script (see the previous section):
texi2dvi bison.texinfo
lpr -d bison.dvi
# or perhaps dvips bison.dvi -o
`lpr' is a standard program on Unix systems, but it is usually absent
on MS-DOS/MS-Windows. Some network packages come with a program named
`lpr', but these are usually limited to sending files to a print server
over the network, and generally don't support the `-d' option. If you
are unfortunate enough to work on one of these systems, you have
several alternative ways of printing DVI files:
* Find and install a Unix-like `lpr' program, or its clone. If you
can do that, you will be able to print DVI files just like
described above.
* Send the DVI files to a network printer queue for DVI files. Some
network printers have special queues for printing DVI files. You
should be able to set up your network software to send files to
that queue. In some cases, the version of `lpr' which comes with
your network software will have a special option to send a file to
specific queues, like this:
lpr -Qdvi -hprint.server.domain bison.dvi
* Convert the DVI file to a Postscript or PCL file and send it to
your local printer. *Note dvips invocation: (dvips)dvips
invocation, and the man pages for `dvilj', for detailed
description of these tools. Once the DVI file is converted to the
format your local printer understands directly, just send it to
the appropriate port, usually `PRN'.