texinfo (7.1)
This is texinfo.info, produced by texi2any version 7.1 from
texinfo.texi.
This manual is for GNU Texinfo (version 7.1, 18 October 2023), a
documentation system that can produce both online information and a
printed manual from a single source using semantic markup.
Copyright © 1988-2023 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.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
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.
* texi2any: (texinfo)Invoking texi2any. Translate Texinfo source.
* makeinfo: (texinfo)Invoking texi2any. Translate Texinfo source.
* pod2texi: (pod2texi)Invoking pod2texi. Translate Perl Pod to Texinfo.
* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
* pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
END-INFO-DIR-ENTRY
File: texinfo.info, Node: Inserting a Hashsign, Next: Inserting an Ampersand, Prev: Inserting a Backslash, Up: Special Characters
11.1.5 Inserting '#' with ‘@hashchar{}’
---------------------------------------
Ordinarily, a hash '#' is a normal character in Texinfo that can be
simply typed in your input where you need it. The result is to typeset
the hash character from the current font.
This character has many other names, varying by locale, such as
"number sign", "pound", and "octothorp". It is also sometimes called
"sharp" or "sharp sign" since it vaguely resembles the musical symbol by
that name. In situations where Texinfo is used, "hash" is the most
common in our experience.
However, Texinfo uses the hash character as a special character in
one restricted context: to introduce the so-called ‘#line’ directive and
variants (*note External Macro Processors::).
So, in order to typeset an actual hash character in such a place (for
example, in a program that needs documentation about ‘#line’), it's
necessary to use ‘@hashchar{}’ or some other construct. Here's an
example:
@hashchar{} 10 "example.c"
Although ‘@hashchar{}’ can be used nearly anywhere, there is no need
for it anywhere except this unusual case.
File: texinfo.info, Node: Inserting an Ampersand, Prev: Inserting a Hashsign, Up: Special Characters
11.1.6 Inserting '&' with ‘@&’ and ‘@ampchar{}’
-----------------------------------------------
Ordinarily, an ampersand '&' is a normal character in Texinfo that can
be simply typed in your input where you need it. The result is to
typeset the ampersand character.
However, the ampersand character is treated specially in just one
restricted context. In the argument to a definition command (*note
Definition Commands::), an ampersand followed by a series of letters may
be typeset specially when processing with TeX (1) (*note Def Cmd
Conventions::). For example:
@defun foo integer1 &optional integer2 &rest integers
@code{foo} described here.
@end defun
may have ‘&optional’ and ‘&rest’ formatted in bold, even without any
@-command involved.
So, in order to typeset an ampersand in such a context, it's
necessary to use ‘@&’ or some other construct. Here's an example of a
C++ function taking a reference as a parameter:
@deftypefn Function int foo (const std::vector<int>@& @var{bar})
Documentation of @code{foo}.
@end deftypefn
This gives the output
-- Function: int foo (const std::vector<int>& BAR)
Documentation of ‘foo’.
Although ‘@&’ and ‘@ampchar{}’ can be used nearly anywhere, there is
no need for them anywhere except this unusual case.
---------- Footnotes ----------
(1) This syntax is used for Emacs Lisp keywords. *Note (elisp)A
Sample Function Description::.
File: texinfo.info, Node: Inserting Quote Characters, Next: Inserting Space, Prev: Special Characters, Up: Insertions
11.2 Inserting Quote Characters
===============================
As explained in the early section on general Texinfo input conventions
(*note Conventions::), Texinfo source files use the ASCII character ‘`’
(96 decimal) to produce a left quote ('), and ASCII ‘'’ (39 decimal) to
produce a right quote ('). Doubling these input characters (‘``’ and
‘''’) produces double quotes (" and "). These are the conventions used
by TeX.
In examples of computer code, however, ‘`’ and ‘'’ produce typical
renderings for these ASCII characters: the backtick character
(standalone grave accent) and undirected single quote respectively. In
the past, directed glyphs were used by default in TeX output. Texinfo
provides these commands to choose between these alternate renderings:
‘@codequoteundirected ON-OFF’
Set to ‘off’ to output the ‘'’ character in code environments as
the right curly single quote.
‘@codequotebacktick ON-OFF’
Set to ‘off’ to output the ‘`’ character in code environments as
the left curly single quote.
If you want these settings for only part of the document,
‘@codequote... on’ will restore the normal behavior, as in
‘@codequoteundirected on’.
These settings affect ‘@code’, ‘@example’, ‘@kbd’, ‘@samp’, ‘@verb’,
and ‘@verbatim’. *Note Useful Highlighting::.
Unfortunately, some document viewers will mangle the directed quote
characters when copying and pasting. (The free PDF reader ‘xpdf’ works
fine, but other PDF readers, both free and nonfree, have problems.)
This feature can also be controlled by using ‘@set’ and ‘@clear’ on
the corresponding variables ‘txicodequoteundirected’ and
‘txicodequotebacktick’.
File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Inserting Quote Characters, Up: Insertions
11.3 Inserting Space
====================
The following sections describe commands that control spacing of various
kinds within and after sentences.
* Menu:
* Multiple Spaces:: Inserting multiple spaces.
* Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
* Ending a Sentence:: Sometimes it does.
* @frenchspacing:: Specifying end-of-sentence spacing.
* @dmn:: Formatting a dimension.
File: texinfo.info, Node: Multiple Spaces, Next: Not Ending a Sentence, Up: Inserting Space
11.3.1 Multiple Spaces
----------------------
Ordinarily, multiple whitespace characters (space, tab, and newline) are
collapsed into a single space.
Occasionally, you may want to produce several consecutive spaces,
either for purposes of example (e.g., 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., ‘@ ’,
‘TAB’ represents an actual tab character, and ‘@NL’ represents an ‘@’
character and end-of-line, i.e., when ‘@’ is the last character on a
line.)
For example,
Spacey@ @ @ @
example.
produces
Spacey example.
Do not follow any of these commands with braces.
To produce a non-breakable space, see *note @tie::.
File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Multiple Spaces, Up: Inserting Space
11.3.2 Not Ending a Sentence
----------------------------
When a period, exclamation point or question mark is at the end of a
sentence, slightly more space is inserted after it in a typeset manual.
Usually, Texinfo can determine automatically when a period ends a
sentence. However, special commands are needed in some circumstances.
Use the ‘@:’ command after a period, question mark, exclamation mark or
colon that should not be followed by extra space. This is necessary in
the following situations:
1. After a period that ends a lowercase abbreviation which is not at
the end of a sentence.
2. When a parenthetical remark in the middle of a sentence (like this
one!) ends with a period, exclamation point or question mark, ‘@:’
should be used after the right parenthesis. Similarly for right
brackets and right quotes (both single and double).
For example:
‘foo vs.@: bar (or?)@: baz’,
The first line below shows the output, and for comparison, the second
line shows the spacing when the ‘@:’ commands were not used.
foo vs. bar (or?) baz
foo vs. bar (or?) baz
It may help you to remember what ‘@:’ does by imagining that it
stands for an invisible lower-case character that stops a word ending in
a period.
A few Texinfo commands force normal interword spacing, so that you
don't have to insert ‘@:’ where you otherwise would. These are the
code-like highlighting commands, ‘@var’, ‘@abbr’, and ‘@acronym’ (*note
Useful Highlighting::). For example, in ‘@code{foo. bar}’ the period is
not considered to be the end of a sentence, and no extra space is
inserted.
‘@:’ has no effect on the HTML or DocBook output.
File: texinfo.info, Node: Ending a Sentence, Next: @frenchspacing, Prev: Not Ending a Sentence, Up: Inserting Space
11.3.3 Ending a Sentence
------------------------
As mentioned above, Texinfo normally inserts additional space after the
end of a sentence. It uses the same heuristic for this as TeX: a
sentence ends with a period, exclamation point, or question mark, either
preceded or followed by optional closing punctuation, and then
whitespace, and _not_ preceded by a capital letter.
Use ‘@.’ instead of a period, ‘@!’ instead of an exclamation point,
and ‘@?’ instead of a question mark at the end of a sentence that does
end with a capital letter. Do not put braces after any of these
commands. For 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.
The output follows. In printed output and Info, you can see the desired
extra whitespace after the ‘W’ in the first line.
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 other output formats, ‘@.’ is equivalent to a simple ‘.’; likewise
for ‘@!’ and ‘@?’.
The "closing punctuation" mentioned above is defined as a right
parenthesis (‘)’, right bracket (‘]’), or right quote, either single or
double (‘'’ and ‘''’; the many possible additional Unicode right quotes
are not included). These characters can be thought of as invisible with
respect to whether a given period ends a sentence. (This is the same
rule as TeX.) For instance, the periods in ‘foo.) Bar’ and ‘foo.'' Bar’
do end sentences.
The meanings of ‘@:’ and ‘@.’, etc. in Texinfo are designed to work
well with the Emacs sentence motion commands (*note (emacs)Sentences::).
It may help to imagine that the ‘@’ in ‘@.’, etc., is an invisible
lower-case letter 'a' which makes an upper-case letter before it
immaterial for the purposes of deciding whether the period ends the
sentence.
A few Texinfo commands are not considered as being an abbreviation,
even though they may end with a capital letter when expanded, so that
you don't have to insert ‘@.’ and companions. Notably, this is the case
for code-like highlighting commands, ‘@var’ arguments ending with a
capital letter, ‘@LaTeX’, and ‘@TeX’. For example, that sentence ended
with ‘... @code{@@TeX}.’; ‘@.’ was not needed. Similarly, in ‘...
@var{VARNAME}. Text’ the period after VARNAME ends the sentence; there
is no need to use ‘@.’.
File: texinfo.info, Node: @frenchspacing, Next: @dmn, Prev: Ending a Sentence, Up: Inserting Space
11.3.4 ‘@frenchspacing’ VAL: Control Sentence Spacing
-----------------------------------------------------
In American typography, it is traditional and correct to put extra space
at the end of a sentence. This is the default in Texinfo (implemented
in Info and printed output, not in other output formats). In French
typography (and others), this extra space is wrong; all spaces are
uniform.
Therefore Texinfo provides the ‘@frenchspacing’ command to control
the spacing after punctuation. It reads the rest of the line as its
argument, which must be the single word ‘on’ or ‘off’ (always these
words, regardless of the language of the document). Here is an example:
@frenchspacing on
This is text. Two sentences. Three sentences. French spacing.
@frenchspacing off
This is text. Two sentences. Three sentences. Non-French spacing.
produces:
This is text. Two sentences. Three sentences. French spacing.
This is text. Two sentences. Three sentences. Non-French spacing.
‘@frenchspacing’ also affects the output after ‘@.’, ‘@!’, and ‘@?’
(*note Ending a Sentence::).
‘@frenchspacing’ has no effect on the HTML or DocBook output.
File: texinfo.info, Node: @dmn, Prev: @frenchspacing, Up: Inserting Space
11.3.5 ‘@dmn’{DIMENSION}: Format a Dimension
--------------------------------------------
You can use the ‘@dmn’ command to format a dimension with just enough
space for proper typesetting inserted in printed output. In other
output formats, the formatting commands insert no space at all.
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'. In these cases, however, you need to use ‘@tie’ (*note
@tie::) or ‘@w’ (*note @w::) so that no line break can occur between the
number and the dimension. Also, if you write a period after an
abbreviation within a sentence (as with the 'in.' above), you should
write ‘@:’ after the period to avoid inserting extra whitespace in
printed output, as shown here. *Note Not Ending a Sentence::.
File: texinfo.info, Node: Inserting Accents, Next: Inserting Quotation Marks, Prev: Inserting Space, Up: Insertions
11.4 Inserting Accents
======================
Here is a table with the commands Texinfo provides for inserting
floating accents. They all need an argument, the character to accent,
which can either be given in braces as usual (‘@'{e}’), or, as a special
case, the braces can be omitted, in which case the argument is the next
character (‘@'e’). This is to make the source as convenient as possible
to type and read, since accented characters are very common in some
languages.
If the command is alphabetic, such as ‘@dotaccent’, then there must
be a space between the command name and argument if braces are not used.
If the command is non-alphabetic, such as ‘@'’, then there must _not_ be
a space; the argument is the very next character.
Exception: the argument to ‘@tieaccent’ must be enclosed in braces
(since it is two characters instead of one).
In Info and plain text output, accent constructs are output as the
true accented characters if the document encoding supports the required
characters, unless the option ‘--disable-encoding’ is given to
‘texi2any’ (*note @documentencoding::). ASCII transliterations are used
if the encoded characters are not output.
Command Output What
------------------------------------------------------
@"o ö umlaut accent
@'o ó acute accent
@,{c} ç cedilla accent
@=o ō macron/overbar accent
@^o ô circumflex accent
@`o ò grave accent
@~o õ tilde accent
@dotaccent{o} ȯ overdot accent
@H{o} ő long Hungarian umlaut
@ogonek{a} ą ogonek
@ringaccent{o} o̊ ring accent
@tieaccent{oo} o͡o tie-after accent
@u{o} ŏ breve accent
@ubaraccent{o} o̲ underbar accent
@udotaccent{o} ọ underdot accent
@v{o} ǒ caron/hacek/check 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{} å Å a,A with circle
@ae{} @AE{} æ Æ ae,AE ligatures
@dh{} @DH{} ð Ð Icelandic eth
@dotless{i} ı dotless i
@dotless{j} ȷ dotless j
@l{} @L{} ł Ł suppressed-L,l
@o{} @O{} ø Ø O,o with slash
@oe{} @OE{} œ Œ oe,OE ligatures
@ordf{} @ordm{} ª º Spanish ordinals
@ss{} ß es-zet or sharp S
@th{} @TH{} þ Þ Icelandic thorn
File: texinfo.info, Node: Inserting Quotation Marks, Next: Inserting Subscripts and Superscripts, Prev: Inserting Accents, Up: Insertions
11.5 Inserting Quotation Marks
==============================
Use doubled single-quote characters to begin and end quotations:
``...''. Two single quotes are converted to left- and right-hand
doubled quotation marks, "like this".
You may occasionally need to produce two consecutive single quotes;
for example, in documenting a computer language such as Maxima where ''
is a valid command. You can do this with the input '@w{}'; the empty
‘@w’ command stops the combination into the double-quote characters.
The left quote character (`, ASCII code 96) used in Texinfo is a
grave accent in ANSI and ISO character set standards. We use it as a
quote character because that is how TeX is set up, by default.
Texinfo supports several other quotation marks used in languages
other than English. Below is a table with the commands Texinfo provides
for inserting quotation marks.
Command Glyph Unicode name (point)
----------------------------------------------------------------------
@quotedblleft{} `` “ Left double quotation mark (U+201C)
@quotedblright{} '' ” Right double quotation mark (U+201D)
@quoteleft{} ` ‘ Left single quotation mark (U+2018)
@quoteright{} ' ’ Right single quotation mark (U+2019)
@quotedblbase{} „ Double low-9 quotation mark (U+201E)
@quotesinglbase{} ‚ Single low-9 quotation mark (U+201A)
@guillemetleft{} « Left-pointing double angle quotation
mark (U+00AB)
@guillemetright{} » Right-pointing double angle quotation
mark (U+00BB)
@guilsinglleft{} ‹ Single left-pointing angle quotation
mark (U+2039)
@guilsinglright{} › Single right-pointing angle quotation
mark (U+203A)
For the double angle quotation marks, Adobe and LaTeX glyph names are
also supported: ‘@guillemotleft’ and ‘@guillemotright’. These names are
incorrect; a "guillemot" is a bird species (a type of auk).
The standard TeX fonts support the usual quotation marks used in
English (the ones produced with single and doubled ASCII single quotes).
For the other quotation marks, TeX uses European Computer Modern (EC)
fonts (‘ecrm1000’ and other variants). These fonts are freely
available, of course; you can download them from
<http://ctan.org/pkg/ec>, among other places.
The free EC fonts are bitmap fonts created with Metafont. Especially
for on-line viewing, Type 1 (vector) versions of the fonts are
preferable; these are available in the CM-Super font package
(<http://ctan.org/pkg/cm-super>).
Both distributions include installation instructions.
Traditions for quotation mark usage vary to a great extent between
languages (<https://en.wikipedia.org/wiki/Quotation_mark>). Texinfo
does not provide commands or configurations for typesetting quotation
marks according to the numerous traditions. Therefore, you have to
choose the commands appropriate for the language of your manual.
Sometimes aliases (*note @alias::) can simplify the usage and make the
source code more readable. For example, in German, ‘@quotedblbase’ is
used for the left double quote, and the right double quote is the glyph
produced by ‘@quotedblleft’, which is counterintuitive. Thus, in this
case the following aliases would be convenient:
@alias lgqq = quotedblbase
@alias rgqq = quotedblleft
File: texinfo.info, Node: Inserting Subscripts and Superscripts, Next: Inserting Math, Prev: Inserting Quotation Marks, Up: Insertions
11.6 ‘@sub’ and ‘@sup’: Inserting Subscripts and Superscripts
=============================================================
You can insert subscripts and superscripts with the ‘@sub’ and ‘@sup’
commands. For example:
here@sub{below}@sup{above}
produces:
here_{below}^{above}
In Info and plain text, ‘@sub{TEXT}’ is currently output as ‘_{TEXT}’
and ‘@sup{TEXT}’ as ‘^{TEXT}’, including the literal braces (to mark the
beginning and end of the "script" text to the reader).
When the output format (and display program) permit (printed output,
HTML), the superscript is set above the subscript when both commands are
given consecutively.
For subscripts and superscripts in mathematical expressions, it is
better to use TeX's ‘_’ and ‘^’ characters. See the next section.
File: texinfo.info, Node: Inserting Math, Next: Glyphs for Text, Prev: Inserting Subscripts and Superscripts, Up: Insertions
11.7 ‘@math’ and ‘@displaymath’: Formatting Mathematics
=======================================================
You can write a mathematical expression, equation or formula using the
‘@math’ command. Write the TeX math notation between braces, like this:
@math{\partial_\alpha \partial^\alpha A^\beta = \mu_0 J^\beta}
‘@math’ is formatted inline when used inside a paragraph, like
\partial_\alpha \partial^\alpha A^\beta = \mu_0 J^\beta in this example.
The ‘@math’ command has no special effect on the Info output, merely
outputting the contents verbatim.
For printed output, ‘@math’ switches into TeX "math mode". In that
context, ‘\’ must be used instead of ‘@’ for plain TeX math control
sequences for symbols, functions, and so on.
By default, the HTML output is only emphasized. ‘texi2any’ provides
three options for displaying properly formatted mathematics for HTML.
You can select these with the ‘HTML_MATH’ variable (*note HTML
Customization Variables::). With ‘HTML_MATH’ set to ‘l2h’, ‘texi2any’
attempts to use the ‘latex2html’ program to produce image files for
mathematical material. With the ‘t4h’ setting, ‘texi2any’ attempts to
use the ‘tex4ht’ program. With the ‘mathjax’ setting, ‘texi2any’
inserts references in the output files to MathJax scripts to format the
material. The MathJax option requires JavaScript to be enabled in the
browser to work. See also *note MathJax Customization Variables::,
*note latex2html Customization Variables:: and *note tex4ht
Customization Variables::.
For displayed equations, you can use the ‘@displaymath’ command.
Example:
@displaymath
f(x) = {1\over\sigma\sqrt{2\pi}}
e^{-{1\over2}\left({x-\mu\over\sigma}\right)^2}
@end displaymath
which produces:
f(x) = {1\over\sigma\sqrt{2\pi}}
e^{-{1\over2}\left({x-\mu\over\sigma}\right)^2}
In general, the contents of ‘@math’ or ‘@displaymath’ should be plain
TeX only, with no interspersed Texinfo commands. If you do use any
Texinfo commands, then you should mark these with ‘@’ as usual, rather
than ‘\’ (e.g. ‘@var’ rather than ‘\var’), but we do not guarantee
which Texinfo commands will work.
Although ‘@sub’ and ‘@sup’ may work inside math mode in some
contexts, it is better to use TeX's ‘_’ and ‘^’ characters to denote
subscripts and superscripts within mathematical expressions.
LaTeX-specific code will only work when the output format is LaTeX,
and with the ‘HTML_MATH’ options (although ‘tex4ht’ needs
‘T4H_MATH_CONVERSION’ to be set to ‘latex’; *note tex4ht Customization
Variables::).
Due to the conflict with Texinfo's ‘@sup’ command, you can access the
plain TeX command ‘\sup’ as ‘\mathopsup’ instead, in the unlikely
occurrence that you want to do this (but only when processing with TeX,
not when outputting LaTeX nor with any of the ‘HTML_MATH’ options).
File: texinfo.info, Node: Glyphs for Text, Next: Glyphs for Programming, Prev: Inserting Math, Up: Insertions
11.8 Glyphs for Text
====================
Texinfo has support for a few additional glyphs that are commonly used
in printed text but not available in ASCII. Of course, there are many
thousands more. It is possible to use Unicode characters as-is as far
as ‘texi2any’ is concerned, but TeX is not so lucky.
* Menu:
* @TeX @LaTeX:: The TeX logos.
* @copyright:: The copyright symbol (c in a circle).
* @registeredsymbol:: The registered symbol (R in a circle).
* @dots:: How to insert ellipses: ... and ...
* @bullet:: How to insert a bullet: •
* @euro:: How to insert the euro currency symbol.
* @pounds:: How to insert the pounds currency symbol.
* @textdegree:: How to insert the degrees symbol.
* @minus:: How to insert a minus sign.
* @geq @leq:: How to insert greater/less-than-or-equal signs.
File: texinfo.info, Node: @TeX @LaTeX, Next: @copyright, Up: Glyphs for Text
11.8.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
other output formats, 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 other output formats, the result is just ‘LaTeX’.
The spelling of these commands is unusual for Texinfo, in that they
use both uppercase and lowercase letters.
File: texinfo.info, Node: @copyright, Next: @registeredsymbol, Prev: @TeX @LaTeX, Up: Glyphs for Text
11.8.2 ‘@copyright{}’ (©)
-------------------------
Use the ‘@copyright{}’ command to generate the copyright symbol, '©'.
Where possible, this is a ‘c’ inside a circle; otherwise this is ‘(C)’.
Legally, it's not necessary to use the copyright symbol; the English
word 'Copyright' suffices, according to international treaty.
File: texinfo.info, Node: @registeredsymbol, Next: @dots, Prev: @copyright, Up: Glyphs for Text
11.8.3 ‘@registeredsymbol{}’ (®)
--------------------------------
Use the ‘@registeredsymbol{}’ command to generate the registered symbol,
'®'. Where possible, this is an ‘R’ inside a circle; otherwise this is
‘(R)’.
File: texinfo.info, Node: @dots, Next: @bullet, Prev: @registeredsymbol, Up: Glyphs for Text
11.8.4 ‘@dots’ (...) and ‘@enddots’ (...)
-----------------------------------------
An “ellipsis” (a sequence of dots) would be spaced wrong when typeset as
a string of periods, so a special command is used in Texinfo: use the
‘@dots{}’ command to generate a normal ellipsis, which is three dots in
a row, appropriately spaced ... like so. To emphasize: do not simply
write three periods in the input file; that could work in some output
formats, but would produce the wrong amount of space between the periods
in printed manuals.
The ‘@enddots{}’ command generates an end-of-sentence ellipsis, which
also has three dots, but with different spacing afterwards, ... Look
closely to see the difference.
Here is an ellipsis: ... Here are three periods in a row: ...
In printed (and usually HTML) output, the three periods in a row are
much closer together than the dots in the ellipsis.
File: texinfo.info, Node: @bullet, Next: @euro, Prev: @dots, Up: Glyphs for Text
11.8.5 ‘@bullet’ (•)
--------------------
Use the ‘@bullet{}’ command to generate a large round dot, or the
closest possible thing to one. An asterisk can also be 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::).
File: texinfo.info, Node: @euro, Next: @pounds, Prev: @bullet, Up: Glyphs for Text
11.8.6 ‘@euro’ (€): Euro Currency Symbol
----------------------------------------
Use the ‘@euro{}’ command to generate '€'. Where possible, this is the
symbol for the Euro currency. Otherwise, the word ‘Euro’ is used.
The Euro symbol does not exist in the standard TeX fonts (which were
designed before the Euro was legislated into existence). Therefore, TeX
uses an additional font, named ‘feymr10’ (along with other variables).
It is freely available, of course; you can download it from
<http://ctan.org/pkg/eurosym>, among other places. The distribution
includes installation instructions.
File: texinfo.info, Node: @pounds, Next: @textdegree, Prev: @euro, Up: Glyphs for Text
11.8.7 ‘@pounds’ (£): Pounds Sterling
-------------------------------------
Use the ‘@pounds{}’ command to generate '£'. Where possible, this is
the symbol for the pounds sterling British currency. Otherwise, it is
‘#’.
File: texinfo.info, Node: @textdegree, Next: @minus, Prev: @pounds, Up: Glyphs for Text
11.8.8 ‘@textdegree’ (°): Degrees Symbol
----------------------------------------
Use the ‘@textdegree{}’ command to generate '°'. Where possible, this
is the normal symbol for degrees. Otherwise, it is an ‘o’.
File: texinfo.info, Node: @minus, Next: @geq @leq, Prev: @textdegree, Up: Glyphs for Text
11.8.9 ‘@minus’ (−): Inserting a Minus Sign
-------------------------------------------
Use the ‘@minus{}’ command to generate a minus sign. Where the
character encoding and font used in the output allow it, 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.
If you actually want to typeset some math that does a subtraction, it
is better to use ‘@math’, as in ‘@math{a-b}’ (*note Inserting Math::).
File: texinfo.info, Node: @geq @leq, Prev: @minus, Up: Glyphs for Text
11.8.10 ‘@geq’ (≥) and ‘@leq’ (≤): Inserting Relations
------------------------------------------------------
Use the ‘@geq{}’ and ‘@leq{}’ commands to generate greater-than-or-equal
and less-than-equal-signs, '≥' and '≤'. When those symbols are not
available, the ASCII sequences ‘>=’ and ‘<=’ are output.
File: texinfo.info, Node: Glyphs for Programming, Next: Inserting Unicode, Prev: Glyphs for Text, Up: Insertions
11.9 Glyphs for Programming
===========================
In Texinfo, code is often illustrated in examples that are delimited by
‘@example’ and ‘@end example’. 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, the location of point in an
editor, and GUI operation sequences.
The glyph-insertion commands do not need to be used within an
example, but most often they are. All glyph-insertion commands are
followed by empty braces.
* Menu:
* Glyphs Summary:: List of the glyph commands.
* @result:: How to show the result of expression.
* @expansion:: How to indicate an expansion.
* @print:: How to indicate generated output.
* @error:: How to indicate an error message.
* @equiv:: How to indicate equivalence.
* @point:: How to indicate the location of point.
* Click Sequences:: Inserting GUI usage sequences.
File: texinfo.info, Node: Glyphs Summary, Next: @result, Up: Glyphs for Programming
11.9.1 Glyphs Summary
---------------------
Here is a summary of the glyph commands:
⇒
‘@result{}’ indicates the result of an expression.
↦
‘@expansion{}’ indicates the results of a macro expansion.
⊣
‘@print{}’ indicates printed output.
error→
‘@error{}’ indicates the following text is an error message.
≡
‘@equiv{}’ indicates the exact equivalence of two forms.
⋆
‘@point{}’ shows the location of point.
A → B
‘@clicksequence{A @click{} B}’ indicates a GUI operation sequence:
first A, then clicking B, or choosing B from a menu, or otherwise
selecting it.
File: texinfo.info, Node: @result, Next: @expansion, Prev: Glyphs Summary, Up: Glyphs for Programming
11.9.2 ‘@result{}’ (⇒): Result of an Expression
-----------------------------------------------
Use the ‘@result{}’ command to indicate the result of evaluating an
expression.
The ‘@result{}’ command is displayed as ‘⇒’, either a double stemmed
arrow or (when that is not available) the ASCII sequence ‘=>’.
Thus, the following,
(cdr '(1 2 3))
⇒ (2 3)
may be read as "‘(cdr '(1 2 3))’ evaluates to ‘(2 3)’".
File: texinfo.info, Node: @expansion, Next: @print, Prev: @result, Up: Glyphs for Programming
11.9.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 ‘↦’, either a long arrow
with a flat base or (when that is not available) the ASCII sequence
‘==>’.
For example, the following
@example lisp
(third '(a b c))
@expansion{} (car (cdr (cdr '(a b c))))
@result{} c
@end example
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.info, Node: @print, Next: @error, Prev: @expansion, Up: Glyphs for Programming
11.9.4 ‘@print{}’ (⊣): Indicating Generated Output
--------------------------------------------------
Sometimes an expression will generate output during its execution. You
can indicate such displayed output with the ‘@print{}’ command.
The ‘@print{}’ command is displayed as ‘⊣’, either a horizontal dash
butting against a vertical bar or (when that is not available) the ASCII
sequence ‘-|’.
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:
@example lisp
(progn (print 'foo) (print 'bar))
@print{} foo
@print{} bar
@result{} bar
@end example
File: texinfo.info, Node: @error, Next: @equiv, Prev: @print, Up: Glyphs for Programming
11.9.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→’, either the word
'error' in a box in the printed output, the word error followed by an
arrow in other formats or (when no arrow is available) ‘error-->’.
Thus,
@example lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end example
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
The word ‘error→’ itself is not part of the error message.
File: texinfo.info, Node: @equiv, Next: @point, Prev: @error, Up: Glyphs for Programming
11.9.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 ‘≡’, either a standard mathematical
equivalence sign (three parallel horizontal lines) or (when that is not
available) as the ASCII sequence ‘==’.
Thus,
@example lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end example
produces
(make-sparse-keymap) ≡ (list 'keymap)
This indicates that evaluating ‘(make-sparse-keymap)’ produces identical
results to evaluating ‘(list 'keymap)’.
File: texinfo.info, Node: @point, Next: Click Sequences, Prev: @equiv, Up: Glyphs for Programming
11.9.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 ‘⋆’, either a pointed star or
(when that is not available) the ASCII sequence ‘-!-’.
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.info, Node: Click Sequences, Prev: @point, Up: Glyphs for Programming
11.9.8 Click Sequences
----------------------
When documenting graphical interfaces, it is necessary to describe
sequences such as 'Click on ‘File’, then choose ‘Open’, then ...'.
Texinfo offers commands ‘@clicksequence’ and ‘click’ to represent this,
typically used like this:
... @clicksequence{File @click{} Open} ...
which produces:
... File → Open ...
The ‘@click’ command produces a right arrow by default; this glyph is
also available independently via the command ‘@arrow{}’.
You can change the glyph produced by ‘@click’ with the command
‘@clickstyle’, which takes a command name as its single argument on the
rest of the line, much like ‘@itemize’ and friends (*note @itemize::).
The command should produce a glyph, and the usual empty braces ‘{}’ are
omitted. Here's an example:
@clickstyle @result
... @clicksequence{File @click{} Open} ...
now produces:
... File ⇒ Open ...
File: texinfo.info, Node: Inserting Unicode, Prev: Glyphs for Programming, Up: Insertions
11.10 Inserting Unicode: ‘@U’
=============================
The command ‘@U{HEX}’ inserts a representation of the Unicode character
U+HEX. For example, ‘@U{0132}’ inserts the Dutch 'IJ' ligature ('IJ').
The HEX value should be at least four hex digits; leading zeros are
_not_ added. In general, HEX must specify a valid normal Unicode
character; e.g., U+10FFFF (the very last code point) is invalid by
definition, and thus cannot be inserted this way.
‘@U’ is useful for inserting occasional glyphs for which Texinfo has
no dedicated command, while allowing the Texinfo source to remain purely
7-bit ASCII for maximum portability.
This command has many limitations--the same limitations as inserting
Unicode characters in UTF-8 or another binary form. First and most
importantly, TeX knows nothing about most of Unicode. Supporting
specific additional glyphs upon request is possible, but it's not viable
for ‘texinfo.tex’ to support whole additional scripts (Japanese, Urdu,
...). The ‘@U’ command does nothing to change this. If the specified
character is not supported in TeX, an error is given. LaTeX output has
more possibilities regarding UTF-8, but could require extra code to load
fonts and declare how UTF-8 characters are output. (*Note
@documentencoding::.)
In HTML and DocBook, the output from ‘@U’ is always an entity
reference of the form ‘&#xHEX;’, as in ‘IJ’ for the example above.
This should work even when an HTML document uses some other encoding
(say, Latin 1) and the given character is not supported in that
encoding.
In Info and plain text, if the output encoding is not UTF-8, the
output is the ASCII sequence ‘U+HEX’, as in the six ASCII characters
‘U+0132’ for the example above.
File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
12 Forcing and Preventing Breaks
********************************
Line and page breaks can sometimes occur in the 'wrong' place in one or
another form of output. It's up to you to ensure that text looks right
in all the output formats.
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
normally occur.
You can use the break, break prevention, or pagination commands to
fix problematic line and page breaks.
* Menu:
* Break Commands:: Summary of break-related commands.
* Line Breaks:: Forcing line breaks.
* @- @hyphenation:: Helping TeX with hyphenation points.
* @allowcodebreaks:: Controlling line breaks within @code text.
* @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.info, Node: Break Commands, Next: Line Breaks, Up: Breaks
12.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 other
output formats do not have pages.
‘@page’
Start a new page.
‘@group’
Hold text together that must appear on one page.
‘@need MILS’
Start a new page if not enough space on this one.
File: texinfo.info, Node: Line Breaks, Next: @- @hyphenation, Prev: Break Commands, Up: Breaks
12.2 ‘@*’ and ‘@/’: Generate and Allow Line Breaks
==================================================
The ‘@*’ command forces a line break in all output formats. The ‘@/’
command allows a line break (printed manual only).
Here is an example with ‘@*’:
This sentence is broken @*into two lines.
produces
This sentence is broken
into two lines.
The ‘@/’ command can be useful within long URLs or other identifiers
where TeX can't find a good place to break. TeX will automatically
break URLs at the natural places (*note URL Line Breaking::), so only
use ‘@/’ if you need it. ‘@/’ has no effect on the other output
formats.
File: texinfo.info, Node: @- @hyphenation, Next: @allowcodebreaks, Prev: Line Breaks, Up: Breaks
12.3 ‘@-’ and ‘@hyphenation’: Hyphenation in Printed Output
===========================================================
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
specify hyphenation points explicitly. Texinfo supports two commands
for this:
‘@-’
Insert a discretionary hyphen, i.e., a place where a word can be
broken across lines with a hyphen. This is especially useful when
you notice that 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}’
Give hyphenation points for certain words. For example:
@hyphenation{man-u-script man-u-scripts}
As shown, you put a ‘-’ at each hyphenation point. TeX only uses
the specified hyphenation points when the words match exactly, so
give all necessary variants, such as plurals.
Non-printed output is not hyphenated, so none of these commands have
any effect in other output formats.
File: texinfo.info, Node: @allowcodebreaks, Next: @w, Prev: @- @hyphenation, Up: Breaks
12.4 ‘@allowcodebreaks’: Control Line Breaks in ‘@code’
=======================================================
Ordinarily, TeX considers breaking lines at ‘-’ and ‘_’ characters
within ‘@code’ and related commands (*note @code::), more or less as if
they were "empty" hyphenation points.
This is necessary since many manuals, especially for Lisp-family
languages, must document very long identifiers. On the other hand, some
manuals don't have this problem, and you may not wish to allow a line
break at the underscore in, for example, ‘SIZE_MAX’, or even worse,
after any of the four underscores in ‘__typeof__’.
So Texinfo provides this command:
@allowcodebreaks false
to prevent from breaking at ‘-’ or ‘_’ within ‘@code’. You can go back
to allowing such breaks with ‘@allowcodebreaks true’. Write these
commands on lines by themselves.
These commands can be given anywhere in the document. For example,
you may have just one problematic paragraph where you need to turn off
the breaks, but want them in general, or vice versa.
This command has no effect except in TeX output.
File: texinfo.info, Node: @w, Next: @tie, Prev: @allowcodebreaks, Up: Breaks
12.5 ‘@w’{TEXT}: Prevent Line Breaks
====================================
‘@w{TEXT}’ outputs TEXT, while prohibiting line breaks within TEXT.
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 manual indenting. However, usually you want a normal
interword space that does stretch and shrink (in the printed output);
for that, see the ‘@tie’ command in the next section.
In printed output, you can also use the ‘@w’ command to prevent a
long name or phrase being automatically hyphenated, for example if it
happens to fall near the end of a line.
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$’. This trick isn't effective for output files in some
output formats, though.
File: texinfo.info, Node: @tie, Next: @sp, Prev: @w, Up: Breaks
12.6 ‘@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.info, Node: @sp, Next: @page, Prev: @tie, Up: Breaks
12.7 ‘@sp’ N: Insert Blank Lines
================================
A line beginning with and containing only ‘@sp N’ generates N blank
lines of space. ‘@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.info, Node: @page, Next: @group, Prev: @sp, Up: Breaks
12.8 ‘@page’: Start a New Page
==============================
A line containing only ‘@page’ starts a new page in a printed manual.
In other formats, without the concept of pages, it starts a new
paragraph. A ‘@page’ command is often used in the ‘@titlepage’ section
of a Texinfo file to start the copyright page.
File: texinfo.info, Node: @group, Next: @need, Prev: @page, Up: Breaks
12.9 ‘@group’: Prevent Page Breaks
==================================
The ‘@group’ command is used to hold an example together on one page.
Use it inside an ‘@example’ or similar construct to begin an
unsplittable vertical group, which will appear entirely on one page in
the printed output. Terminate the group by a line containing only ‘@end
group’. This command has an effect in TeX output only.
The ‘@group’ and ‘@end group’ commands need to be inside the
‘@example’ and ‘@end example’ commands, thus:
@example
@group
...
@end group
@end example
Although ‘@group’ would make sense conceptually in a wide variety of
contexts, its current implementation works 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.)
File: texinfo.info, Node: @need, Prev: @group, Up: Breaks
12.10 ‘@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 other output formats since they are not paginated.
This paragraph is preceded by a ‘@need’ command that starts a new
page in printed output 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.info, Node: Definition Commands, Next: Internationalization, Prev: Breaks, Up: Top
13 Definition Commands
**********************
The ‘@deffn’ command and the other “definition commands” enable you to
describe functions, variables, macros, commands, user options, special
forms and other entities in a uniform format.
In the output, the name of the entity is shown with any arguments,
along with the entity category --'Function', 'Variable', or whatever.
Underneath, the body of the definition is indented. The name of the
entity is also entered into the appropriate index.
All the definition commands follow a similar format. This chapter
starts by describing ‘@deffn’ before detailing all the other 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.
* No Space After Definition Name:: How to omit space after name.
* @deffnx:: Group two or more 'first' lines.
* Def Cmds in Detail:: Reference for all the definition commands.
* Generic Definition Commands:: Without automatic index entries.
* Def Cmd Conventions:: Conventions for writing definitions.
* Sample Function Definition:: An example.
File: texinfo.info, Node: Def Cmd Template, Next: Def Cmd Continuation Lines, Up: Definition Commands
13.1 The Template for a Definition
==================================
@deffn CATEGORY NAME ARGUMENTS...
BODY-OF-DEFINITION
@end deffn
The ‘@deffn’ command is used for definitions of entities that resemble
functions--entities that may take arguments. 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.
Finally, end the definition with an ‘@end deffn’ command written on a
line of its own.
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 command 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. This may also be necessary if the text contains commands,
for example, ‘{declaraci@'on}’ if you are writing in Spanish.
The category is output in a different location for different output
formats. For example, in the Info file, the category appears at the
beginning of the first line of the definition. With TeX output, the
category is printed next to the right margin.
‘@deffn’ enters names into the index of functions.
Three predefined, specialized variations of ‘@deffn’ (‘@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.
File: texinfo.info, Node: Def Cmd Continuation Lines, Next: Optional Arguments, Prev: Def Cmd Template, Up: Definition Commands
13.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, in the same way; put
an ‘@’ at the end of each line to be continued.
In general, any number of spaces or tabs before the ‘@’ continuation
character 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'.
To avoid this, elide the unwanted whitespace in your input, or put the
continuation ‘@’ outside braces.
‘@’ does not 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.info, Node: Optional Arguments, Next: No Space After Definition Name, Prev: Def Cmd Continuation Lines, Up: Definition Commands
13.3 Optional and Repeated Arguments
====================================
Some entities take optional or repeated arguments. One convention for
indicating these uses square brackets and ellipses: an argument enclosed
within square brackets is optional, and an argument followed by an
ellipsis is optional and may be repeated more than once.
Thus, [OPTIONAL-ARG] means that OPTIONAL-ARG is optional and
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 definition line of an example of an imaginary
(complicated) 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:
@defspec foobar (var [from to [inc]]) body@dots{}
File: texinfo.info, Node: No Space After Definition Name, Next: @deffnx, Prev: Optional Arguments, Up: Definition Commands
13.4 Omitting the Space After a Definition Name
===============================================
As a matter of style or as demanded by the syntax of a programming
language, you may wish to omit any space after a name in a definition,
occurring before an opening bracket. To do this, set the
‘txidefnamenospace’ flag (*note @set @value::). For example, this input
@set txidefnamenospace
@deffn Builtin index (string, substring)
@dots{}
@end deffn
produces the following:
-- Builtin: index(string, substring)
...
File: texinfo.info, Node: @deffnx, Next: Def Cmds in Detail, Prev: No Space After Definition Name, Up: Definition Commands
13.5 ‘@deffnx’, et al.: 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’.
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.info, Node: Def Cmds in Detail, Next: Generic Definition Commands, Prev: @deffnx, Up: Definition Commands
13.6 The Definition Commands
============================
This section describes all the definition commands of Texinfo.
* Menu:
* Functions Commands:: Commands for functions and similar entities.
* Typed Functions:: Commands for functions in typed languages.
* Variables Commands:: Commands for variables and similar entities.
* 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.info, Node: Functions Commands, Next: Typed Functions, Up: Def Cmds in Detail
13.6.1 Functions and Similar Entities
-------------------------------------
This section describes the commands for describing functions and similar
entities with simple arguments:
‘@deffn CATEGORY NAME ARGUMENTS...’
The ‘@deffn’ command is the general definition command for
functions, interactive commands, and similar entities that may take
simple 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.
Where the output format allows, ‘@deffn’ uses a typewriter font for
NAME, and a slanted font for the rest of the ARGUMENTS, as would be
produced by ‘@var’.
Within the text of the description, 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 extremely unusual case when an argument name contains ‘--’,
or another character sequence which is treated specially (*note
Conventions::), use ‘@code’ around the special characters. This
avoids the conversion to typographic en-dashes and em-dashes.
‘@defun NAME ARGUMENTS...’
The ‘@defun’ command is the definition command for functions with
simple arguments. ‘@defun’ is equivalent to ‘@deffn Function ...’.
Terminate the definition with ‘@end defun’ on a line of its own.
‘@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
(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.info, Node: Typed Functions, Next: Variables Commands, Prev: Functions Commands, Up: Def Cmds in Detail
13.6.2 Functions in Typed Languages
-----------------------------------
The ‘@deftypefn’ command and its variants are generic commands for
describing functions. They are particularly suitable for 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
could be 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, information on 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
produces:
-- 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’).
‘Library Function’ has to be enclosed in braces to make it a single
argument.
When using ‘@deftypefn’ command and variations, you should mark
parameter names with ‘@var’ to distinguish these from data type
names, keywords, and other parts of the literal syntax of the
programming language. Where the output format allows, all output
on the definition line is in a typewriter font by default. ‘@var’
uses an appropriate font where it occurs.
If you are describing a procedure in a language that has packages,
such as Ada, you might consider using ‘@deftypefn’ in the following
manner:
@deftypefn stacks private push @
(@var{s}:in out stack; @
@var{n}:in integer)
...
@end deftypefn
(In these examples the ‘@deftypefn’ arguments are shown using
continuations (*note Def Cmd Continuation Lines::), but could be on
a single line.)
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.) Output:
-- stacks: private push (S:in out stack; N:in integer)
...
‘@deftypefn’ and variants could be used when it is convenient to
interpret the arguments list as literal computer code, marking
argument names with ‘@var’. It is not necessary for any type names
to appear, and you can give an empty return type as ‘{}’.
The information on return values may be used to name the return
variables. For example, in Perl, returned scalars may be given the
$RESULT and $STATUS name in the following manner:
@deftypefn {Sub} {(@var{$result}, @var{$status} =)} @
process (@var{$input})
... Set @var{$status} to 0 in case of failure ...
@end deftypefn
to get output like
-- Sub: ($RESULT, $STATUS) = process ($INPUT)
... Set $STATUS to 0 in case of failure ...
‘@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. The command is equivalent to ‘@deftypefn Function ...’.
‘@deftypefun’ creates an entry in the index of functions for NAME.
Ordinarily, the return type is printed on the same line as the
function name and arguments, as shown above. In source code, GNU style
for typed functions is to put the return type on a line by itself. So
Texinfo provides an option to do that: ‘@deftypefnnewline on’.
This affects the generic functions only--not untyped functions with
simple arguments such as ‘@deffn’, not typed variables, etc.
Specifically, it affects the commands in this section, and the analogous
commands for object-oriented languages, namely ‘@deftypeop’ and
‘@deftypemethod’ (*note Object-Oriented Methods::).
Specifying ‘@deftypefnnewline off’ reverts to the default.
File: texinfo.info, Node: Variables Commands, Next: Typed Variables, Prev: Typed Functions, Up: Def Cmds in Detail
13.6.3 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.
We recommend capitalizing 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.
‘@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
‘@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 (emacs)Variables::). ‘@defopt’ is
equivalent to ‘@defvr {User Option} ...’.
File: texinfo.info, Node: Typed Variables, Next: Data Types, Prev: Variables Commands, Up: Def Cmds in Detail
13.6.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:
-- Global Flag: int enable
...
‘@deftypevar DATA-TYPE NAME’
The ‘@deftypevar’ command is the specialized definition command for
variables in typed languages. ‘@deftypevar’ is equivalent to
‘@deftypevr Variable ...’.
These commands create entries in the index of variables.
File: texinfo.info, Node: Data Types, Next: Abstract Objects, Prev: Typed Variables, Up: Def Cmds in Detail
13.6.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
‘@deftp’ creates an entry in the index of data types.
File: texinfo.info, Node: Abstract Objects, Prev: Data Types, Up: Def Cmds in Detail
13.6.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.info, Node: Object-Oriented Variables, Next: Object-Oriented Methods, Up: Abstract Objects
13.6.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.
@deftypecv {Class Option} Window 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.
@deftypeivar Window int border-pattern
...
@end deftypeivar
produces:
-- Instance Variable of Window: int border-pattern
...
‘@deftypeivar’ creates an entry in the index of variables.
File: texinfo.info, Node: Object-Oriented Methods, Prev: Object-Oriented Variables, Up: Abstract Objects
13.6.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 definition command for these
method-like entities with simple arguments.
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.
‘@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 generic definition command for
operations in object-oriented programming. It is particularly
suitable for typed object-oriented languages. It is similar to
‘@defop’ with the addition of the DATA-TYPE parameter to specify
information on the return value of the method, for example the
return type.
‘@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 languages, in particular for typed languages
such as C++ and Java. It is similar to the ‘@defmethod’ command
with the addition of the DATA-TYPE parameter to specify information
on the return value of the method, for example the return type.
The commands with information on return values are affected by the
‘@deftypefnnewline’ option (*note Functions in Typed Languages: Typed
Functions.).
File: texinfo.info, Node: Generic Definition Commands, Next: Def Cmd Conventions, Prev: Def Cmds in Detail, Up: Definition Commands
13.7 Generic Definition Commands
================================
Texinfo provides commands for definitions that do not produce automatic
index entries.
You create a generic definition environment with ‘@defblock’ paired
with ‘@end defblock’. Within this environment, use a ‘@defline’ or
‘@deftypeline’ line for each symbol you document. For example:
@defblock
@defline Macro mac (arg1, arg2)
Description of mac.
@deftypeline Builtin int foo (int @var{bar})
Description of foo.
@end defblock
This produces the output:
-- Macro: mac (arg1, arg2)
Description of mac.
-- Builtin: int foo (int BAR)
Description of foo.
The syntax of ‘@defline’ is similar to that of ‘@deffn’. The first
argument gives a category for the definition. Follow this with the
symbol name, followed by any parameters. You should surround any
arguments containing spaces with braces.
You use ‘@deftypeline’ in a similar way to ‘@deftypefn’, following
the category with a data type, and marking any parameters with ‘@var’.
(*Note Typed Functions::).)
To share the same description for multiple symbols, you can put
several ‘@defline’ lines together. For example:
@defblock
@defline Function set-var (value)
@defline {Settable Variable} var
Description of set-var and var.
@end defblock
This produces the output:
-- Function: set-var (value)
-- Settable Variable: var
Description of set-var and var.
It may be useful to define line macros (*note Line Macros::) in
combination with these commands.
File: texinfo.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Generic Definition Commands, Up: Definition Commands
13.8 Conventions for Writing Definitions
========================================
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.
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.
_Fonts._ As Texinfo is a semantic language, you should nearly never
need to specify font styles with explicit font commands in definitions
(*note Fonts::). However, you may be need to work around problems for
particular output formats and/or constructs. Here are some
possibilities:
• Explicitly marking a Lisp keyword like ‘&KEYWORD’ with
‘@r{&keyword}’, producing &keyword.
Note such keywords in definition arguments are (at present)
rendered in roman in TeX, but this formatting is not done in any
other output format.
• ‘@r{@slanted{argument}}’, producing argument, similar to ‘@var’ but
avoiding upper-casing its argument in Info output.
In this and the previous point, ‘@r’ resets the font from that
being used in the definition line context (slanted or typewriter)
to a roman, upright style.
• You could use ‘@t’ (or even ‘@r{@t{...’, using ‘@r’ to reset font
styles) to mark literal syntax on a definition line where text
would otherwise be output in the slanted roman style. ‘@code’
would be inappropriate here as it adds quotation marks in Info
output.
Some degree of trial and error may be needed to get the result you
want. As ever, how nested font commands combine depends on the output
format, so should be avoided where possible.
Hopefully, such usages are kept to a minimum. One possibility is to
wrap these in ‘@macro’ (*note Defining New Texinfo Commands::), allowing
these usages to be easily changed in the future.
File: texinfo.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands
13.9 A Sample Function Definition
=================================
Here is a definition from *note (elisp)Calling Functions::, using the
‘@defun’ command. The name of the function, ‘apply’, follows
immediately after the ‘@defun’ command and it is followed, on the same
line, by the parameter list.
-- 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 should look like this:
@defun apply function @r{&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’.
File: texinfo.info, Node: Internationalization, Next: Conditionals, Prev: Definition Commands, Up: Top
14 Internationalization
***********************
Texinfo has some support for writing in languages other than English,
although this area still needs considerable work. (If you are the one
helping to translate the fixed strings written to documents, *note
Internationalization of Document Strings::.)
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.info, Node: @documentlanguage, Next: @documentencoding, Up: Internationalization
14.1 ‘@documentlanguage LL[_CC]’: Set the Document Language
===========================================================
The ‘@documentlanguage’ command declares the current document locale.
Write it on a line by itself, near the beginning of the file.
@documentlanguage LL[_CC]
Include a two-letter ISO 639-2 language code (LL) following the
command name, optionally followed by an underscore and two-letter
ISO 3166 two-letter country code (CC). 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_US’ for US English.
As with GNU Gettext (*note (gettext)Top::), if the country code is
omitted, the main dialect is assumed where possible. For example, ‘de’
is equivalent to ‘de_DE’ (German as spoken in Germany).
For Info and other online output, this command changes the
translation of various “document strings” such as "see" in
cross-references (*note Cross References::), "Function" in defuns (*note
Definition Commands::), and so on. Some strings, such as "Node:",
"Next:", "Menu:", etc., are keywords in Info output, so are not
translated there; they are translated in other output formats. In
DocBook output ‘@documentlanguage’ sets the language for following
sections.
For LaTeX, this command causes code to load the ‘babel’ package to be
output in the preamble, and ‘\selectlanguage’ to be output.
For TeX, this command causes a file ‘txi-LOCALE.tex’ to be read (if
it exists). If ‘@documentlanguage’ argument contains the optional ‘_CC’
suffix, this is tried first. For example, with ‘@documentlanguage
de_DE’, TeX first looks for ‘txi-de_DE.tex’, then ‘txi-de.tex’.
Such a ‘txi-*’ file is intended to redefine the various English words
used in TeX output, such as 'Chapter', 'See', and so on. We are aware
that individual words like these cannot always be translated in
isolation, and that a very different strategy would be required for
ideographic (among other) scripts. Help in improving Texinfo's language
support is welcome.
‘@documentlanguage’ also changes TeX's current hyphenation patterns,
if the TeX program being run has the necessary support included. This
will generally not be the case for ‘tex’ itself, but will usually be the
case for up-to-date distributions of the extended TeX programs ‘etex’
(DVI output) and ‘pdftex’ (PDF output). ‘texi2dvi’ will use the
extended TeXs if they are available (*note Format with texi2dvi::).
Since the lists of language codes and country codes are updated
relatively frequently, we don't attempt to list them here. The valid
language codes are on the official home page for ISO 639,
<http://www.loc.gov/standards/iso639-2/>. The country codes and the
official web site for ISO 3166 can be found via
<https://en.wikipedia.org/wiki/ISO_3166>.
File: texinfo.info, Node: @documentencoding, Prev: @documentlanguage, Up: Internationalization
14.2 ‘@documentencoding ENC’: Set Input Encoding
================================================
In the default case, the input and output document encoding are assumed
to be UTF-8, the vast global character encoding, expressed in 8-bit
bytes. UTF-8 is compatible with 7-bit ASCII. It is recommended to use
UTF-8 encoding for Texinfo manuals.
The ‘@documentencoding’ command declares the input document encoding,
and also affects the encoding of the output. Write it on a line by
itself, with a valid encoding specification following, near the
beginning of the file if your document encoding is not the default
encoding.
@documentencoding ENC
UTF-8 should always be the best choice for the encoding. Texinfo
still supports additional encodings, mainly for compatibility with older
manuals(1):
‘US-ASCII’
Character encoding based on the English alphabet.
‘ISO-8859-1’
‘ISO-8859-15’
‘ISO-8859-2’
These specify the pre-UTF-8 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>.
‘koi8-r’
This was a commonly used encoding for the Russian language before
UTF-8.
‘koi8-u’
This was a commonly used encoding for the Ukrainian language before
UTF-8.
In Info output, a so-called 'Local Variables' section (*note
(emacs)File Variables::) is output including the output encoding. This
allows Info readers to set the encoding appropriately. It looks like
this:
Local Variables:
coding: UTF-8
End:
By default, for Info and plain text output, ‘texi2any’ outputs accent
constructs and special characters (such as ‘@'e’) as the actual UTF-8
sequence or 8-bit character in the output encoding where possible. If
this is not possible, or if the option ‘--disable-encoding’ is given, an
ASCII transliteration is used instead.
In HTML output, a ‘<meta>’ tag is output, in the ‘<head>’ section of
the HTML, that specifies the output encoding. Web servers and browsers
cooperate to use this information so the correct encoding is used to
display the page, if supported by the system. That looks like this:
<meta http-equiv="Content-Type" content="text/html;
charset=utf-8">
In HTML and LaTeX output, if ‘OUTPUT_CHARACTERS’ is set (*note Other
Customization Variables::), accent constructs and special characters,
such as ‘@'e’ or ‘``’, are output as the actual UTF-8 sequence or 8-bit
character in the output encoding where possible. Otherwise, HTML
entities are used for those characters in HTML, and LaTeX macros are
used in LaTeX.
In DocBook output, if the encoding is different from UTF-8, an
‘encoding’ attribute is added to the XML declaration. If
‘OUTPUT_CHARACTERS’ is set (*note Other Customization Variables::),
accent constructs such as ‘@'e’ are output as the actual 8-bit or UTF-8
character in the output encoding where possible. Otherwise XML entities
are used for those constructs.
In TeX output, the characters which are supported in the standard
Computer Modern fonts are output accordingly. For example, this means
using constructed accents rather than precomposed glyphs. Using a
missing character generates a warning message, as does specifying an
unimplemented encoding.
Although modern TeX systems support nearly every script in use in the
world, this wide-ranging support is not available in ‘texinfo.tex’, and
it's not feasible to duplicate or incorporate all that effort.
In LaTeX output, code loading the ‘inputenc’ package is output based
on the encoding. This, by itself, does not ensures that all the
characters from the input document can be subsequently output. The
fonts used in the default case should cover the specific Texinfo glyphs,
but not all the possible encoded characters. You may need to load
different fonts in the preamble and use ‘\DeclareUnicodeCharacter’ with
a UTF-8 encoding. For example:
@latex
\DeclareUnicodeCharacter{017B}{\.Z}
@end latex
Cross-references between Info files in different character encodings
with non-ASCII characters in node names fail. We strongly recommend
using UTF-8 only as the encoding for manuals with non-ASCII characters
in the destinations of cross-references.
---------- Footnotes ----------
(1) ‘texi2any’ supports more encodings for Texinfo manuals,
potentially all the encodings supported by both Perl and iconv (*note
(libc)Generic Charset Conversion::). The support in output formats may
be lacking, however, especially for LaTeX output.
File: texinfo.info, Node: Conditionals, Next: Defining New Texinfo Commands, Prev: Internationalization, Up: Top
15 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 _excluding_ a given one
(e.g., not Info, not TeX, ...).
• 'Raw' formatter text for any output format, passed straight through
with minimal (but not zero) 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.
* Inline Conditionals:: Brace-delimited conditional text.
* @set @clear @value:: Variable tests and substitutions.
* Testing for Texinfo Commands:: Testing if a Texinfo command is available.
* Conditional Nesting:: Using conditionals inside conditionals.
File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals
15.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 when not
producing Info output, in particular in printed 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.
‘@iflatex ... @end iflatex’
Text to appear only in the LaTeX 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. The newlines following the commands are
(more or less) treated as whitespace, so that the conditional text is
flowed normally into a surrounding paragraph.
The ‘@if...’ constructs are intended to conditionalize normal Texinfo
source; *note Raw Formatter Commands::, for using underlying format
commands directly.
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
@iflatex
Moreover, this text will only appear in @LaTeX{}.
@end iflatex
@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.
In complex documents, you may want Texinfo to issue an error message
in some conditionals that should not ever be processed. The
‘@errormsg{TEXT}’ command will do this; it takes one argument, the text
of the error message.
We mention ‘@errormsg{}’ here even though it is not strictly related
to conditionals, since in practice it is most likely to be useful in
that context. Technically, it can be used anywhere. *Note External
Macro Processors::, for a caveat regarding the line numbers which
‘@errormsg’ emits in TeX.
File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals
15.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
@ifnotlatex ... @end ifnotlatex
@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.info, Node: Raw Formatter Commands, Next: Inline Conditionals, Prev: Conditional Not Commands, Up: Conditionals
15.3 Raw Formatter Commands
===========================
The ‘@if...’ conditionals just described must be used only with normal
Texinfo source. For instance, most features of plain TeX will not work
within ‘@iftex’. The purpose of ‘@if...’ is to provide conditional
processing for Texinfo source, not provide access to underlying
formatting features. For that, Texinfo provides so-called “raw
formatter commands”. They should only be used when truly required (most
documents do not need them).
The first raw formatter command is ‘@tex’. 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 a ‘@tex’ region. The sole exception
is that the ‘@’ character still introduces a command, so that ‘@end tex’
can be recognized. Texinfo processors will not output material in 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. If you need to make several
definitions, you may wish to set ‘\globaldefs=1’ (its value will be
restored to zero as usual when the group ends at ‘@end tex’, so it won't
cause problems with the rest of the document).
As an example, here is a displayed equation 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 a format not generated by TeX, you will not see the
equation that appears in the printed manual.
Analogously, you can use ‘@html ... @end html’ for a region of raw
HTML, ‘@docbook ... @end docbook’ for a region of raw DocBook, ‘@latex
... @end latex’ for a region of raw LaTeX, and ‘@xml ... @end xml’ for a
region of raw XML.
The behavior of newlines in raw regions is unspecified.
In all cases, in raw processing, ‘@’ retains the same meaning as in
the remainder of the document. Thus, the Texinfo processors must
recognize and even execute, to some extent, the contents of the raw
regions, regardless of the final output format. Therefore, specifying
changes that globally affect the document inside a raw region leads to
unpredictable and generally undesirable behavior. For example, using
the ‘@kbdinputstyle’ command inside a raw region is undefined. The
remedy is simple: don't do that.
File: texinfo.info, Node: Inline Conditionals, Next: @set @clear @value, Prev: Raw Formatter Commands, Up: Conditionals
15.4 Inline Conditionals: ‘@inline’, ‘@inlineifelse’, ‘@inlineraw’
==================================================================
Texinfo provides a set of conditional commands with arguments given
within braces:
‘@inlinefmt{FORMAT, TEXT}’
Process the Texinfo TEXT if FORMAT output is being generated.
‘@inlinefmtifelse{FORMAT, THEN-TEXT, ELSE-TEXT}’
Process the Texinfo THEN-TEXT if FORMAT output is being generated;
otherwise, process ELSE-TEXT.
‘@inlineraw{FORMAT, TEXT}’
Similar, but for raw TEXT (*note Raw Formatter Commands::).
The supported FORMAT names are:
docbook html info latex plaintext tex xml
For example,
@inlinefmt{html, @emph{HTML-only text}}
is nearly equivalent to
@ifhtml
@emph{HTML-only text}
@end ifhtml
except that no whitespace is added, as happens in the latter
(environment) case.
In these commands, whitespace is ignored after the comma separating
the arguments, as usual, but is _not_ ignored at the end of TEXT.
To insert a literal at sign, left brace, or right brace in one of the
arguments, you must use the alphabetic commands ‘@atchar{}’ (*note
Inserting an Atsign::), and ‘@lbracechar{}’ or ‘@rbracechar{}’ (*note
Inserting Braces::), or the parsing will become confused.
With ‘@inlinefmtifelse’, it is also necessary to use ‘@comma{}’ to
avoid mistaking a ‘,’ in the text for the delimiter. With ‘@inlinefmt’
and ‘@inlineraw’, ‘@comma{}’ is not required (though it's fine to use
it), since these commands always have exactly two arguments.
For TeX, the processed TEXT cannot contain newline-delimited
commands. Text to be ignored (i.e., for non-TeX) can, though.
Two other ‘@inline...’ conditionals complement the ‘@ifset’ and
‘@ifclear’ commands; see the next section.
File: texinfo.info, Node: @set @clear @value, Next: Testing for Texinfo Commands, Prev: Inline Conditionals, Up: Conditionals
15.5 Flags: ‘@set’, ‘@clear’, conditionals, 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 is a summary:
‘@set FLAG [VALUE]’
Set the variable FLAG, to the optional VALUE if specified.
‘@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.
‘@inlineifset{FLAG, TEXT}’
Brace-delimited version of ‘@ifset’.
‘@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.
‘@inlineifclear{FLAG, TEXT}’
Brace-delimited version of ‘@ifclear’.
* Menu:
* @set @value:: Expand a flag variable to a string.
* @ifset @ifclear:: Format a region if a flag is set.
* @inlineifset @inlineifclear:: Brace-delimited flag conditionals.
* @value Example:: An easy way to update edition information.
File: texinfo.info, Node: @set @value, Next: @ifset @ifclear, Up: @set @clear @value
15.5.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”) name is an identifier starting with an
alphanumeric, ‘-’, or ‘_’. Subsequent characters, if any, may not be
whitespace, ‘@’, braces, angle brackets, or any of ‘~`^+|’; other
characters, such as ‘%’, may work. However, it is best to use only
letters and numerals in a flag name, not ‘-’ or ‘_’ or others--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 processors then replace a ‘@value{FLAG}’ command with the
string to which FLAG is set. Thus, when ‘foo’ is set as shown above,
the Texinfo processors convert this:
@value{foo}
to this:
This is a string.
You can write a ‘@value’ command within a paragraph; but you must
write a ‘@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 processors transform
It is a @value{howmuch} wet day.
into
It is a very, very, very wet day.
If you write
@clear howmuch
then the processors transform
It is a @value{howmuch} wet day.
into
It is a {No value for "howmuch"} wet day.
‘@value’ cannot be reliably used as the argument to an accent command
(*note Inserting Accents::). For example, this fails:
@set myletter a
@'@value{myletter}
File: texinfo.info, Node: @ifset @ifclear, Next: @inlineifset @inlineifclear, Prev: @set @value, Up: @set @clear @value
15.5.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 the 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; 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 a ‘@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.info, Node: @inlineifset @inlineifclear, Next: @value Example, Prev: @ifset @ifclear, Up: @set @clear @value
15.5.3 ‘@inlineifset’ and ‘@inlineifclear’
------------------------------------------
‘@inlineifset’ and ‘@inlineifclear’ provide brace-delimited alternatives
to the ‘@ifset’ and ‘@ifclear’ forms, similar to the other ‘@inline...’
Commands (*note Inline Conditionals::). The same caveats about argument
parsing given there apply here too.
‘@inlineifset{VAR, TEXT}’
Process the Texinfo TEXT if the flag VAR is defined.
‘@inlineifclear{VAR, TEXT}’
Process the Texinfo TEXT if the flag VAR is not defined.
Except for the syntax, their general behavior and purposes is the
same as with ‘@ifset’ and ‘@ifclear’, described in the previous section.
File: texinfo.info, Node: @value Example, Prev: @inlineifset @inlineifclear, Up: @set @clear @value
15.5.4 ‘@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 (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
This is Edition @value{EDITION},
last updated @value{UPDATED},
of @cite{The GNU Make Manual},
for @code{make}, version @value{VERSION}.
@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.info, Node: Testing for Texinfo Commands, Next: Conditional Nesting, Prev: @set @clear @value, Up: Conditionals
15.6 Testing for Texinfo Commands: ‘@ifcommanddefined’, ‘@ifcommandnotdefined’
==============================================================================
Occasionally, you may want to arrange for your manual to test if a given
Texinfo command is available and (presumably) do some sort of fallback
formatting if not. There are conditionals ‘@ifcommanddefined’ and
‘@ifcommandnotdefined’ to do this. For example:
@ifcommanddefined node
Good, @samp{@@node} is defined.
@end ifcommanddefined
will output the expected 'Good, ‘@node’ is defined.'.
This conditional will also consider any new commands defined by the
document via ‘@macro’, ‘@alias’, ‘@definfoenclose’, and
‘@def(code)index’ (*note Defining New Texinfo Commands::) to be true.
Caveat: the TeX implementation reports internal TeX commands, in
addition to all the Texinfo commands, as being "defined"; the ‘texi2any’
implementation is reliable in this regard, however.
You can check the ‘NEWS’ file in the Texinfo source distribution and
linked from the Texinfo home page
(<http://www.gnu.org/software/texinfo>) to see when a particular command
was added.
These command-checking conditionals themselves were added in
Texinfo 5.0, released in 2013--decades after Texinfo's inception. In
order to test if they themselves are available, the predefined flag
‘txicommandconditionals’ can be tested, like this:
@ifset txicommandconditionals
@ifcommandnotdefined foobarnode
(Good, @samp{@@foobarnode} is not defined.)
@end ifcommandnotdefined
@end ifset
Since flags (see the previous section) were added early in the
existence of Texinfo, there is no problem with assuming they are
available.
We recommend avoiding these tests whenever possible--which is usually
the case. For many software packages, it is reasonable for all
developers to have a given version of Texinfo (or newer) installed, and
thus no reason to worry about older versions. (It is straightforward
for anyone to download and install the Texinfo source; it does not have
any problematic dependencies.)
The issue of Texinfo versions does not generally arise for end users.
With properly distributed packages, users need not process the Texinfo
manual simply to build and install the package; they can use
preformatted Info (or other) output files. This is desirable in
general, to avoid unnecessary dependencies between packages (*note
(standards)Releases::).
File: texinfo.info, Node: Conditional Nesting, Prev: Testing for Texinfo Commands, Up: Conditionals
15.7 Conditional Nesting
========================
Texinfo requires that for a failing conditional, the ignored text must
be properly nested with respect to that failing conditional. 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
If ‘somevar’ is not set, the whole block is skipped.
To allow the processors to reliably determine which commands to
consider for nesting purposes, all conditional commands must be on lines
by themselves, with no text (even spaces) before or after.
File: texinfo.info, Node: Defining New Texinfo Commands, Next: Include Files, Prev: Conditionals, Up: Top
16 Defining New Texinfo Commands
********************************
Texinfo provides several ways to define new commands (in all cases, it's
not recommended to try redefining existing 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 area of the
manual (*note Def Cmd Template::).
• ‘@linemacro’ allows you to define a macro whose arguments extend to
the end of the line and are separated by spaces.
• ‘@alias’ defines a new name for an existing command.
• ‘@definfoenclose’ allows you to define new commands with customized
output for some non-printed output formats. This command is
deprecated.
Most generally of all (not just for defining new commands), it is
possible to invoke any external macro processor and have Texinfo
recognize so-called ‘#line’ directives for error reporting.
If you want to do simple text substitution, ‘@set’ and ‘@value’ is
the simplest approach (*note @set @clear @value::).
* 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.
* Line Macros:: Macros using whole line for arguments.
* @definfoenclose:: Customized highlighting.
* External Macro Processors:: ‘#line’ directives.
File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Up: Defining New Texinfo Commands
16.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).
In principle, MACRONAME should consist of alphanumerics, and (except
as the first character) ‘-’. The ‘_’ character is excluded so that
macros can be called inside ‘@math’ without a following space (*note
Inserting Math::). However, for a macro to work consistently with TeX,
MACRONAME must consist entirely of letters: no digits, hyphens, or other
special characters. So, we recommend using only letters. Texinfo
commands should not be redefined as macros.
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 macro invocations. However, 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 newline characters 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.info, Node: Invoking Macros, Next: Macro Details, Prev: Defining Macros, Up: Defining New Texinfo Commands
16.2 Invoking Macros
====================
After a macro is defined (see the previous section), you can “invoke”
(use) it in your document like this:
@MACRONAME {ARG1, ARG2, ...}
and the result will be more or less 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 even when the macro
takes no arguments, consistent with other Texinfo commands. For
example:
@macro argless {}
No arguments here.
@end macro
@argless{}
produces:
No arguments here.
Passing macro arguments containing commas requires care, since commas
also separate the arguments. To include a comma character in an
argument, the most reliable method is to use the ‘@comma{}’ command.
Another method is to surround the argument with ‘@asis{...}’. For
‘texi2any’, you can also prepend a backslash character, as in ‘\,’, but
this does not work with TeX.
It's not always necessary to worry about commas. To facilitate use
of macros, two rules for “automatic quoting” are implemented:
1. If a macro takes only one argument, all commas in its invocation
are quoted by default. For example:
@macro TRYME{text}
@strong{TRYME: \text\}
@end macro
@TRYME{A nice feature, though it can be dangerous.}
will produce the following output
*TRYME: A nice feature, though it can be dangerous.*
And indeed, it can. Namely, there is no control on the number of
arguments passed to one-argument macros, so be careful when you
invoke them.
2. If a macro invocation includes another command (including a
recursive invocation of itself), any commas in the nested command
invocation(s) are quoted by default. For example, in
@say{@strong{Yes, I do}, person one}
the comma after ‘Yes’ is implicitly quoted. Here's another
example, with a recursive macro:
@rmacro cat{a,b}
\a\\b\
@end rmacro
@cat{@cat{foo, bar}, baz}
will produce the string ‘foobarbaz’.
3. Otherwise, a comma should be explicitly quoted, as above, for it to
be treated as a part of an argument.
The backslash itself can be quoted in macro arguments with another
backslash. For example:
@MACNAME {\\bleh}
will pass the argument ‘\bleh’ to MACNAME.
‘texi2any’ also recognizes ‘\{’ and ‘\}’ sequences for curly braces,
but these are not recognized by the implementation in TeX. There
should, however, rarely be a need for these, as they are only needed
when a macro argument contains unbalanced braces.
If a macro is defined to take exactly one argument, it can be invoked
without any braces, taking all of the line after the macro name as the
argument. For example:
@macro bar {p}
Twice: \p\ & \p\.
@end macro
@bar aah
produces:
Twice: aah & aah.
In these arguments, there is no escaping of special characters, so each
‘\’ stands for itself.
If a macro is defined to take more than one argument, but is called
with only one (in braces), the remaining arguments are set to the empty
string, and no error is given. For example:
@macro addtwo {p, q}
Both: \p\\q\.
@end macro
@addtwo{a}
produces simply:
Both: a.
File: texinfo.info, Node: Macro Details, Next: @alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands
16.3 Macro Details and Caveats
==============================
By design, macro expansion should not happen in the following contexts:
• ‘@macro’ and ‘@unmacro’ lines;
• ‘@if...’ lines, including ‘@ifset’ and similar;
• ‘@set’, ‘@clear’, ‘@value’;
• ‘@clickstyle’ lines;
• ‘@end’ lines when there is no macro expansion in the block command.
Unfortunately, TeX may do some expansion in these situations, possibly
yielding errors.
Also, quite a few macro-related constructs cause problems with TeX;
some of the caveats are listed below. Thus, if you get macro-related
errors when producing the printed version of a manual, you might try
expanding the macros with ‘texi2any’ by invoking ‘texi2dvi’ with the
‘-E’ option (*note Format with texi2dvi::). Or, more reliably, eschew
Texinfo macros altogether and use a language designed for macro
processing, such as M4 (*note External Macro Processors::).
• 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 large
and open-ended set of names, and the possible resulting errors are
unpredictable.
• Arguments to macros taking more than one argument cannot cross
lines.
• 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.
Similarly, macros containing line-oriented commands or text, such
as ‘@example’ environments, may behave unpredictably in TeX.
• Texinfo commands in the expansion of a macro in the text of an
index entry may end up being typeset as literal text (including an
"@" sign), instead of being interpreted with their intended
meaning.
• White space is ignored at the beginnings of lines.
• Macros can't be reliably used in the argument to accent commands
(*note Inserting Accents::).
• The backslash escape for commas in macro arguments does not work;
‘@comma{}’ must be used.
• Ending a macro body with ‘@c’ may cause text following the macro
invocation to be ignored as a comment in ‘texi2any’. This is not
the case when processing with TeX. This was often done to "comment
out" an unwanted newline at the end of a macro body, but this is
not necessary any more, as the final newline before ‘@end macro’ is
not included in the macro body anyway.
• In general, you can't arbitrarily substitute a macro (or ‘@value’)
call for Texinfo command arguments, even when the text is the same.
Texinfo is not M4 (or even plain TeX). 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
This looks equivalent to ‘@headings off’, but for TeXnical reasons,
it fails with a mysterious error message (namely, ‘Paragraph ended
before @headings was complete’).
• Expanding macros in a math context may lead to poor spacing in TeX
output. For example:
@iftex
@macro atan
\\mathop{\\rm atan}
@end macro
@end iftex
@math{@atan{}(x)}
The braces following ‘@atan’ are treated by TeX as a subformula,
leading to extra space before the opening parenthesis. You can
work around this by defining a raw TeX macro instead:
@tex
\gdef\atan#1{\mathop{\rm atan}}
@end tex
The ‘#1’ in this definition absorbs the braces, so that the spacing
is as expected for the ‘\mathop’ object.
• If you have problems using conditionals within a macro, an
alternative is to use separate macro definitions inside conditional
blocks. For example, instead of
@macro Mac
@iftex
text for TeX output
@end iftex
@ifnottex
text for not TeX output
@end ifnottex
@end macro
you can do the following instead:
@iftex
@macro Mac
text for TeX output
@end macro
@end iftex
@ifnottex
@macro Mac
text for not TeX output
@end macro
@end ifnottex
• 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 following limitations are by design:
• If you want to pass an argument with the Texinfo command ‘@,’ (to
produce a cedilla, see *note Inserting Accents::), you have to use
‘@value’ or another workaround. Otherwise, the comma may be taken
as separating the arguments. With ‘texi2any’, the comma can be
escaped by a backslash. With TeX another workaround need to be
used, therefore we recommend using such a workaround.
For example,
@macro mactwo{argfirst, argsecond}
\argfirst\+\argsecond\.
@end macro
@set fc Fran@,cois
@mactwo{@value{fc},}
produces:
François+.
• ‘@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 incompletely 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 that nested definition outside the macro.
In the ‘makeinfo’ implementation before Texinfo 5.0, ends of lines
from expansion of a ‘@macro’ definition did not end an @-command
line-delimited argument (‘@chapter’, ‘@center’, etc.). This is no
longer the case. For example:
@macro twolines{}
aaa
bbb
@end macro
@center @twolines{}
In the current ‘texi2any’, this is equivalent to:
@center aaa
bbb
with just ‘aaa’ as the argument to ‘@center’. In the earlier
implementation, it would have been parsed as this:
@center aaa bbb
File: texinfo.info, Node: @alias, Next: Line Macros, Prev: Macro Details, Up: Defining New Texinfo Commands
16.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 additional 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 optional and ignored if present. 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.
Unfortunately, it's not possible to alias Texinfo environments; for
example, ‘@alias lang=example’ is an error.
Aliases must not be recursive, directly or indirectly.
It is not advisable to redefine any TeX primitive, plain TeX, or
Texinfo command name as an alias. Unfortunately this is a very large
set of names, and the possible resulting errors from TeX are
unpredictable.
Alias identifiers should be the same as for macro names, that is
alphanumerics and (except as the first character) ‘-’. However, with
TeX, letters only should be used. So, we recommend using only letters.
File: texinfo.info, Node: Line Macros, Next: @definfoenclose, Prev: @alias, Up: Defining New Texinfo Commands
16.5 Line Macros
================
You can also define a macro using the ‘@linemacro’ command. The syntax
for line macro definitions is similar to that for ‘@macro’.
However, the syntax for using a macro defined this way is different.
The macro call uses the rest of the line, with arguments separated by
spaces. The line macro facility is mainly intended to allow you to
define commands that operate similarly to the builtin commands for
providing definitions (*note Definition Commands::).
For example:
@linemacro defbuiltin {name, args}
@defline {Builtin} \name\ \args\
@end linemacro
The above macro may be used as
@defblock
@defbuiltin foo (bar)
Explanation
@end defblock
This produces the following result:
-- Builtin: foo (bar)
Explanation
Here the first argument is ‘foo’, and is substituted where ‘\name\’
appears in the macro body. Likewise, ‘(bar)’ is substituted for
‘\args\’.
You can include spaces in a macro argument by surrounding the
argument by braces. Any pair of braces enclosing an argument is removed
before substitution. Any empty arguments (including the last one) must
be given as ‘{}’. Additionally, non-initial spaces may appear in the
final argument in the argument list without surrounding braces (as in
the example below).
If an argument line for a line macro ends in a ‘@’ character, then
this character together with the following newline are included in a
macro argument, and the following line in the input file is also used to
get the arguments for the macro. Note that any substitution of the
‘@<NEWLINE>’ sequence must be in a valid context, such as a definition
line (*note Def Cmd Continuation Lines::).
Another example:
@linemacro deffunc {type, name, args}
@findex \name\
@deftypeline {Func} {\type\} \name\ \args\
@end linemacro
@defblock
@deffunc {long int} F (int @var{one}, int @var{two}, @
int @var{three}, int @var{four}, int @var{five})
Explanation
@end defblock
Note how braces are needed around ‘\type\’ in the macro body in case the
‘type’ argument contains a space. This example produces the output
below and enters an index entry for ‘F’.
-- Func: long int F (int ONE, int TWO, int THREE, int FOUR, int FIVE)
Explanation
Line macros produce a whole number of lines of output in their
expansion. There may be better compatibility between the Texinfo
processors (‘texi2any’ and TeX with ‘texinfo.tex’) for macros defined
with ‘@linemacro’ than for those defined with ‘@macro’.
File: texinfo.info, Node: @definfoenclose, Next: External Macro Processors, Prev: Line Macros, Up: Defining New Texinfo Commands
16.6 ‘@definfoenclose’: Customized Highlighting
===============================================
An ‘@definfoenclose’ command may be used to define a highlighting
command for online output formats. A command defined using
‘@definfoenclose’ marks text by enclosing it in strings that precede and
follow the text.
In practice, there is little use for this command, and we do not
recommend you use it. Support for ‘@definfoenclose’ may be removed in
future releases of Texinfo.
Write a ‘@definfoenclose’ command at the beginning of a line followed
by three comma-separated arguments. The first argument to
‘@definfoenclose’ is the @-command name (without the ‘@’); the second
argument is the start delimiter string; and the third argument is the
end delimiter string. The latter two arguments enclose the highlighted
text in the output.
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 end delimiter string you intended will naturally be
(mis)interpreted as the start delimiter string.
An enclosure command defined this way takes one argument in braces,
since it 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 and
HTML formatting command that inserts '//' before and '\\' after the
argument to ‘@phoo’. You can then write ‘@phoo{bar}’ wherever you want
'//bar\\' highlighted in Info and HTML.
For TeX formatting, you could write
@iftex
@alias 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 online formats. The TeX definitions need to be in ‘@iftex’.
‘@definfoenclose’ command need not be within ‘@ifinfo’ unless you want
to use different definitions for different online output formats.
‘@definfoenclose’ defined commands have no effect in DocBook and LaTeX
output, their argument is output as-is. An ‘@alias’ could also be used
for these formats.
‘@definfoenclose’ definitions must not be recursive, directly or
indirectly.
File: texinfo.info, Node: External Macro Processors, Prev: @definfoenclose, Up: Defining New Texinfo Commands
16.7 External Macro Processors: Line Directives
===============================================
Texinfo macros (and its other text substitution facilities) work fine in
straightforward cases. If your document needs unusually complex
processing, however, their fragility and limitations can be a problem.
In this case, you may want to use a different macro processor
altogether, such as M4 (*note (m4)Top::) or CPP (*note (cpp)Top::).
With one exception, Texinfo does not need to know whether its input
is "original" source or preprocessed from some other source file.
Therefore, you can arrange your build system to invoke whatever programs
you like to handle macro expansion or other preprocessing needs.
Texinfo does not offer built-in support for any particular preprocessor,
since no one program seemed likely to suffice for the requirements of
all documents.
The one exception is line numbers in error messages. In that case,
the line number should refer to the original source file, whatever it
may be. There's a well-known mechanism for this: the so-called ‘#line’
directive. Texinfo supports this.
* Menu:
* #line Directive::
* #line and TeX::
* #line Syntax Details::
File: texinfo.info, Node: #line Directive, Next: #line and TeX, Up: External Macro Processors
16.7.1 ‘#line’ Directive
------------------------
An input line such as this:
#line 100 "foo.ptexi"
indicates that the next line was line 100 of the file ‘foo.ptexi’, and
so that's what an error message should refer to. Both M4 (*note
(m4)Preprocessor features::) and CPP (*note (cpp)Line Control::, and
*note (cpp)Preprocessor Output::) can generate such lines.
The ‘texi2any’ program recognizes these lines by default, except
within ‘@verbatim’ blocks (*note @verbatim::). Their recognition can be
turned off completely with ‘CPP_LINE_DIRECTIVES’ (*note Other
Customization Variables::), though there is normally no reason to do so.
For those few programs (M4, CPP, Texinfo) which need to document
‘#line’ directives and therefore have examples which would otherwise
match the pattern, the command ‘@hashchar{}’ can be used (*note
Inserting a Hashsign::). The example line above looks like this in the
source for this manual:
@hashchar{}line 100 "foo.ptexi"
The ‘@hashchar’ command was added to Texinfo in 2013. If you don't
want to rely on it, you can also use ‘@set’ and ‘@value’ to insert the
literal ‘#’:
@set hash #
@value{hash}line 1 "example.c"
Or, if suitable, a ‘@verbatim’ environment can be used instead of
‘@example’. As mentioned above, ‘#line’-recognition is disabled inside
verbatim blocks.
File: texinfo.info, Node: #line and TeX, Next: #line Syntax Details, Prev: #line Directive, Up: External Macro Processors
16.7.2 ‘#line’ and TeX
----------------------
As mentioned, ‘texi2any’ recognizes the ‘#line’ directives described in
the previous section. However, ‘texinfo.tex’ does not and cannot.
Therefore, such a line will be incorrectly typeset verbatim if TeX sees
it. The solution is to use ‘texi2any’'s macro expansion options before
running TeX. There are three approaches:
• If you run ‘texi2dvi’ or its variants (*note Format with
texi2dvi::), you can pass ‘-E’ and ‘texi2dvi’ will run ‘texi2any’
first to expand macros and eliminate ‘#line’.
• If you run ‘texi2any’, you can specify ‘--no-ifinfo --iftex -E
somefile.out’, and then give ‘somefile.out’ to ‘texi2dvi’ in a
separate command.
• Or you can run ‘texi2any --dvi --Xopt -E’. (Or ‘--pdf’ instead of
‘--dvi’.) ‘texi2any’ will then call ‘texi2dvi -E’.
One last caveat regarding use with TeX: since the ‘#line’ directives
are not recognized, the line numbers emitted by the ‘@errormsg{}’
command (*note Conditional Commands::), or by TeX itself, are the
(incorrect) line numbers from the derived file which TeX is reading,
rather than the preprocessor-specified line numbers.
File: texinfo.info, Node: #line Syntax Details, Prev: #line and TeX, Up: External Macro Processors
16.7.3 ‘#line’ Syntax Details
-----------------------------
Syntax details for the ‘#line’ directive: the ‘#’ character can be
preceded or followed by whitespace, the word ‘line’ is optional, and the
file name can be followed by a whitespace-separated list of integers
(these are so-called "flags" output by CPP in some cases). For those
who like to know the gory details, the actual (Perl) regular expression
which is matched is this:
/^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/
As far as we've been able to tell, the trailing integer flags only
occur in conjunction with a file name, so that is reflected in the
regular expression.
As an example, the following is a syntactically valid ‘#line’
directive, meaning line 1 of ‘/usr/include/stdio.h’:
# 1 "/usr/include/stdio.h" 2 3 4
Unfortunately, the quoted file name (‘"..."’) has to be optional,
because M4 (especially) can often generate ‘#line’ directives within a
single file. Since the ‘line’ is also optional, the result is that
lines might match which you wouldn't expect, e.g.,
# 1
The possible solutions are described above (*note #line Directive::).
File: texinfo.info, Node: Include Files, Next: Hardcopy with TeX, Prev: Defining New Texinfo Commands, Up: Top
17 Include Files
****************
When a Texinfo processor sees an ‘@include’ command in a Texinfo file,
it processes the contents of the file named by the ‘@include’ and
incorporates them into the output files being created. Include files
thus let you keep a single large document as a collection of
conveniently small parts.
* Menu:
* Using Include Files:: How to use the ‘@include’ command.
* Sample Include File:: A sample outer file with included files within
it; and a sample included file.
* @verbatiminclude:: Including a file verbatim.
File: texinfo.info, Node: Using Include Files, Next: Sample Include File, Up: Include Files
17.1 How to Use Include Files
=============================
To include another file within a Texinfo file, write the ‘@include’
command at the beginning of a line and follow it on the same line by the
name of a file to be included. For example:
@include buffers.texi
‘@value{VAR}’ references are expanded on the ‘@include’ line. Other
than that, the only @-commands allowed are ‘@@’, ‘@{’, ‘@}’ and
associated @-commands such as ‘@atchar{}’.
An included file should simply be a segment of text that you expect
to be included as is into the overall or “outer” Texinfo file; it should
not contain the standard beginning and end parts of a Texinfo file. In
particular, you should not start an included file with a line saying
‘\input texinfo’; if you do, that text is inserted into the output file
literally. Likewise, you should not end an included file with a ‘@bye’
command; nothing after ‘@bye’ is formatted.
In the long-ago past, you were required to write an ‘@setfilename’
line at the beginning of an included file, but no longer. Now, it does
not matter whether you write such a line. If an ‘@setfilename’ line
exists in an included file, it is ignored.
GNU Emacs Texinfo mode provides ‘texinfo-multiple-files-update’ to
update node pointers and master menu with multiple include files. *Note
Update Multiple Files::.
File: texinfo.info, Node: Sample Include File, Next: @verbatiminclude, Prev: Using Include Files, Up: Include Files
17.2 Sample File with ‘@include’
================================
Here is an example of an outer Texinfo file with ‘@include’ files within
it:
\input texinfo @c -*-texinfo-*-
@settitle Include Example
@node Top
@top Include Example
@include foo.texi
@include bar.texi
@include concept-index.texi
@bye
An included file, such as ‘foo.texi’, might look like this:
@node First
@chapter First Chapter
Contents of first chapter ...
The full contents of ‘concept-index.texi’ might be as simple as this:
@node Concept Index
@unnumbered Concept Index
@printindex cp
The outer Texinfo source file for ‘The GNU Emacs Lisp Reference
Manual’ is named ‘elisp.texi’. This outer file has already contained a
master menu with 417 entries and a list of 41 ‘@include’ files.
File: texinfo.info, Node: @verbatiminclude, Prev: Sample Include File, Up: Include Files
17.3 ‘@verbatiminclude’ FILE: Include a File Verbatim
=====================================================
You can include the exact contents of a file in the document with the
‘@verbatiminclude’ command:
@verbatiminclude FILENAME
The contents of FILENAME is printed in a verbatim environment (*note
@verbatim::). Generally, the file is printed exactly as it is, with all
special characters and white space retained. No indentation is added;
if you want indentation, enclose the ‘@verbatiminclude’ within
‘@example’ (*note @example::).
‘@value{VAR}’ references are expanded on the ‘@verbatiminclude’ line.
This makes it possible to include files in other directories within a
distribution, for instance:
@verbatiminclude @value{top_srcdir}/NEWS
(You still have to get ‘top_srcdir’ defined in the first place.)
Other than that, the only @-commands allowed are ‘@@’, ‘@{’, ‘@}’ and
associated @-commands such as ‘@atchar{}’.
For a method on printing the file contents in a smaller font size,
see the end of the section on ‘@verbatim’.
File: texinfo.info, Node: Hardcopy with TeX, Next: Generic Translator texi2any, Prev: Include Files, Up: Top
18 Formatting and Printing with TeX
***********************************
Running the ‘texi2dvi’ or ‘texi2pdf’ command is the simplest way to
create printable output. These commands are installed as part of the
Texinfo package.
In more detail, typesetting and printing a Texinfo file is a
multi-step process in which you use the TeX program to create a file for
printing (called a DVI or PDF file), and then print the file.
Optionally, you may also create indices using the ‘texindex’ command
after first running TeX; and then you must run TeX again. ‘texi2dvi’
takes care of all of this, running TeX and ‘texindex’ as needed (*note
Format with texi2dvi::).
When you use the shell commands, you can either work directly in the
operating system shell or work within a shell inside GNU Emacs (or some
other computing environment). You can give formatting and printing
commands from a shell within GNU Emacs, just like any other shell
command. To create a shell within Emacs, type ‘M-x shell’ (*note
(emacs)Shell::). If you are using GNU Emacs, you can also use commands
provided by Texinfo mode instead of shell commands. *Note Printing with
Emacs::.
For specifing details of the printed output such as paper size, see
*note Global Document Commands::.
* Menu:
* Use TeX:: Use TeX to format for hardcopy.
* Format with texi2dvi or texi2pdf:: The simplest way to format.
* Format with tex/texindex:: Formatting with explicit shell commands.
* Print with lpr:: How to print.
* Preparing for TeX:: What to do before you use TeX.
* Overfull hboxes:: What are and what to do with overfull hboxes.
File: texinfo.info, Node: Use TeX, Next: Format with texi2dvi or texi2pdf, Up: Hardcopy with TeX
18.1 Use TeX
============
The typesetting program called TeX is used to format a Texinfo document
for printable output. TeX is a very powerful typesetting program and,
when used correctly, does an exceptionally good job. It is not included
in the Texinfo package, being a vast suite of software in itself.
TeX is a document formatter that is used by the FSF for its
documentation. It is the easiest way to get printed output (e.g., PDF
and PostScript) for Texinfo manuals. TeX is freely redistributable, and
you can get it over the Internet or on physical media. See
<http://tug.org/texlive>.
File: texinfo.info, Node: Format with texi2dvi or texi2pdf, Next: Format with tex/texindex, Prev: Use TeX, Up: Hardcopy with TeX
18.2 Format with ‘texi2dvi’ or ‘texi2pdf’
=========================================
The ‘texi2dvi’ program takes care of all the steps for producing a TeX
DVI file from a Texinfo document. Similarly, ‘texi2pdf’ produces a PDF
file(1).
To run ‘texi2dvi’ or ‘texi2pdf’ on an input file ‘foo.texi’, do this
(where ‘prompt$ ’ is your shell prompt):
prompt$ texi2dvi foo.texi
prompt$ texi2pdf foo.texi
As shown in this example, the file names given to ‘texi2dvi’ and
‘texi2pdf’ must include any extension, such as ‘.texi’.
For a list of all the options, run ‘texi2dvi --help’. Some of the
options are discussed below.
With the ‘--pdf’ option, ‘texi2dvi’ produces PDF output instead of
DVI, by running ‘pdftex’ instead of ‘tex’. Alternatively, the command
‘texi2pdf’ is an abbreviation for running ‘texi2dvi --pdf’. The command
‘pdftexi2dvi’ is also provided as a convenience for AUC-TeX (*note
(auctex)Top::), as it prefers to merely prepend ‘pdf’ to DVI producing
tools to have PDF producing tools.
With the ‘--dvipdf’ option, ‘texi2dvi’ produces PDF output by running
TeX and then a DVI-to-PDF program: if the ‘DVIPDF’ environment variable
is set, that value is used, else the first program extant among
‘dvipdfmx’, ‘dvipdfm’, ‘dvipdf’, ‘dvi2pdf’, ‘dvitopdf’. This method
generally supports CJK typesetting better than ‘pdftex’.
With the ‘--ps’ option, ‘texi2dvi’ produces PostScript instead of
DVI, by running ‘tex’ and then ‘dvips’ (*note (dvips)Top::). (Or the
value of the ‘DVIPS’ environment variable, if set.)
‘texi2dvi’ can also be used to process LaTeX files. Normally
‘texi2dvi’ is able to guess the input file language by its contents and
file name extension; however, if it guesses wrong you can explicitly
specify the input language using ‘--language=LANG’ command line option,
where LANG is either ‘latex’ or ‘texinfo’.
One useful option to ‘texi2dvi’ is ‘--command=CMD’. This inserts CMD
on a line by itself at the start of the file 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::).
The option ‘-E’ (equivalently, ‘-e’ and ‘--expand’) does Texinfo
macro expansion using ‘texi2any’ instead of the TeX implementation
(*note Macro Details::). Each implementation has its own limitations
and advantages.
‘texi2dvi’ takes the ‘--build=MODE’ option to specify where the TeX
compilation takes place, and, as a consequence, how auxiliary files are
treated. The build mode can also be set using the environment variable
‘TEXI2DVI_BUILD_MODE’. The valid values for MODE are:
‘local’
Compile in the current directory, leaving all the auxiliary files
around. This is the traditional TeX use.
‘tidy’
Compile in a local ‘*.t2d’ directory, where the auxiliary files are
left. Output files are copied back to the original file.
Using the ‘tidy’ mode brings several advantages:
- the current directory is not cluttered with plethora of
temporary files.
- clutter can be even further reduced using ‘--build-dir=dir’:
all the ‘*.t2d’ directories are stored there.
- clutter can be reduced to zero using, e.g.,
‘--build-dir=/tmp/\$USER.t2d’ or ‘--build-dir=\$HOME/.t2d’.
- the output file is updated after every successful TeX run, for
sake of concurrent visualization of the output. In a ‘local’
build the viewer stops during the whole TeX run.
- if the compilation fails, the previous state of the output
file is preserved.
- PDF and DVI compilation are kept in separate subdirectories
preventing any possibility of auxiliary file incompatibility.
On the other hand, because ‘tidy’ compilation takes place in
another directory, occasionally TeX won't be able to find some
files (e.g., when using ‘\graphicspath’): in that case, use ‘-I’ to
specify the additional directories to consider.
‘clean’
Same as ‘tidy’, but remove the auxiliary directory afterwards.
Every compilation therefore requires the full cycle.
‘texi2dvi’ will use ‘etex’ if it is available, because it runs faster
in some cases, and provides additional tracing information when
debugging ‘texinfo.tex’. Nevertheless, this extended version of TeX is
not required, and the DVI output is identical.
‘texi2dvi’ attempts to detect auxiliary files output by TeX, either
by using the ‘-recorder’ option, or by scanning for ‘\openout’ in the
log file that a run of TeX produces. You may control how ‘texi2dvi’
does this with the ‘TEXI2DVI_USE_RECORDER’ environment variable. Valid
values are:
‘yes’
use the ‘-recorder’ option, no checks.
‘no’
scan for ‘\openout’ in the log file, no checks.
‘yesmaybe’
check whether ‘-recorder’ option is supported, and if yes use it,
otherwise check for tracing ‘\openout’ in the log file is
supported, and if yes use it, else it is an error.
‘nomaybe’
same as ‘yesmaybe’, except that the ‘\openout’ trace in log file is
checked first.
The default is ‘nomaybe’. This environment variable is provided for
troubleshooting purposes, and may change or disappear in the future.
---------- Footnotes ----------
(1) “PDF” stands for 'Portable Document Format'. It was invented by
Adobe Systems for document interchange, based on their PostScript
language.
File: texinfo.info, Node: Format with tex/texindex, Next: Print with lpr, Prev: Format with texi2dvi or texi2pdf, Up: Hardcopy with TeX
18.3 Format with ‘tex’/‘texindex’
=================================
You can do the basic formatting of a 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,
perhaps after a further conversion (see the previous section).
The ‘tex’ formatting command itself does not sort the indices; it
writes an output file of unsorted index data. To generate a printed
index after running the ‘tex’ command, you first need a sorted index to
work from. The ‘texindex’ command sorts indices. (‘texi2dvi’,
described in the previous section, runs ‘tex’ and ‘texindex’ as
necessary.)
‘tex’ outputs unsorted index files under names following a standard
convention: the name of your main input file with any ‘.texi’ or similar
extension replaced by the two letter index name. For example, the raw
index output files for the input file ‘foo.texi’ would be, by default,
‘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,
it's typical to 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 two letter indices that you have defined yourself using
‘@defindex’ or ‘@defcodeindex’. You can safely run ‘texindex foo.??’
even if there are 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; for example,
‘foo.cps’ is made from ‘foo.cp’. The ‘@printindex’ command looks for a
file with that name (*note Printing Indices & Menus::). TeX does not
read the raw index output file, and ‘texindex’ does not alter it.
After you have sorted the indices, you need to rerun ‘tex’ on the
Texinfo file. This regenerates the output 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. (Alternatively, it's a
one-step process: run ‘texi2dvi’; see the previous section.)
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 the previous run,
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.
To generate PDF, you can run the ‘pdftex’ program instead of plain
‘tex’. That is, run ‘pdftex foo.texi’ instead of ‘tex foo.texi’ in the
examples above.
* Menu:
* Formatting Partial Documents::
* Details of texindex::
File: texinfo.info, Node: Formatting Partial Documents, Next: Details of texindex, Up: Format with tex/texindex
18.3.1 Formatting Partial Documents
-----------------------------------
Sometimes you may wish to print a document while you know it is
incomplete, or to print just one chapter of a document. In such a case,
the usual auxiliary files that TeX creates and warnings TeX gives about
undefined cross-references are just nuisances. You can avoid them with
the ‘@novalidate’ command, which you must give _before_ any sectioning
or cross-reference commands.
Thus, the beginning of your file would look approximately like this:
\input texinfo
@novalidate
...
‘@novalidate’ also turns off validation in ‘texi2any’, just like its
‘--no-validate’ option (*note Invoking texi2any::).
Furthermore, you need not run ‘texindex’ each time after you run
‘tex’. The ‘tex’ formatting command simply uses whatever sorted index
files happen to exist from a previous use of ‘texindex’. If those are
out of date, that is usually ok while you are creating or debugging a
document.
File: texinfo.info, Node: Details of texindex, Prev: Formatting Partial Documents, Up: Format with tex/texindex
18.3.2 Details of ‘texindex’
----------------------------
In Texinfo version 6, released in 2015, the ‘texindex’ program was
completely reimplemented. The principal functional difference is that
index entries beginning with a left brace or right brace (‘{’ resp. ‘}’)
can work properly. For example, these simple index entries are
processed correctly, including the "index initial" shown in the index:
@cindex @{
@cindex @}
...
@printindex cp
Although not a matter of functionality, readers may be interested to
know that the new ‘texindex’ is a literate program
(<https://en.wikipedia.org/wiki/Literate_programming>) using Texinfo for
documentation and (portable) ‘awk’ for code. A single source file,
‘texindex/ti.twjr’ in this case, produces the runnable program, a
printable document, and an online document.
The system is called TexiWeb Jr. and was created by Arnold Robbins,
who also wrote the new ‘texindex’. Not coincidentally, he is also the
long-time maintainer of ‘gawk’ (GNU Awk, *note (gawk)Top::). The file
‘texindex/Makefile.am’ shows example usage of the system.
File: texinfo.info, Node: Print with lpr, Next: Preparing for TeX, Prev: Format with tex/texindex, Up: Hardcopy with TeX
18.4 Print with ‘lpr’ from Shell
================================
The way to print a DVI file depends on your system installation. Two
common ones are ‘dvips foo.dvi -o’ to make a PostScript file first and
then print that, and ‘lpr -d foo.dvi’ to print a DVI file directly.
For example, the following commands will (probably) suffice to sort
the indices, format, and print this manual using the ‘texi2dvi’ shell
script (*note Format with texi2dvi::).
texi2dvi texinfo.texi
dvips texinfo.dvi -o
lpr texinfo.ps
Depending on the ‘lpr’ setup on your machine, you might be able to
combine the last two steps into ‘lpr -d texinfo.dvi’.
You can also generate a PDF file by running ‘texi2dvi’ instead of
‘texi2dvi’; a PDF is often directly printable. Or you can generate a
PCL file by using ‘dvilj’ instead of ‘dvips’, if you have a printer that
prefers that format.
‘lpr’ is a standard program on Unix systems, but it is usually absent
on MS-DOS/MS-Windows. If so, just create a PostScript or PDF or PCL
file, whatever is most convenient, and print that in the usual way for
your machine (e.g., by sending to the appropriate port, usually ‘PRN’).
File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Print with lpr, Up: Hardcopy with TeX
18.5 Preparing for TeX
======================
TeX needs to find the ‘texinfo.tex’ file that the ‘\input texinfo’
command on the first line reads. The ‘texinfo.tex’ file tells TeX how
to handle @-commands; it is included in all standard GNU distributions.
The latest version released for general use is available from the usual
GNU servers and mirrors:
<http://ftp.gnu.org/gnu/texinfo/texinfo.tex>
<http://ftpmirror.gnu.org/texinfo/texinfo.tex>
The latest development version is available from the Texinfo source
repository:
<http://git.savannah.gnu.org/cgit/texinfo.git/plain/doc/texinfo.tex>
‘texinfo.tex’ is essentially a standalone file, so, if you need or
want to try a newer version than came with your system, it nearly always
suffices to download it and put it anywhere that TeX will find it. You
can replace any existing ‘texinfo.tex’ with a newer version (of course
saving the original in case of disaster).
Also, you should install ‘epsf.tex’, if it is not already installed
from another distribution. More details are at the end of the
description of the ‘@image’ command (*note Images::).
To use quotation marks other than those used in English, you'll need
to have the European Computer Modern fonts (e.g., ‘ecrm1000’) and (for
PDF output) CM-Super fonts (*note Inserting Quotation Marks::).
To use the ‘@euro’ command, you'll need the ‘feym*’ fonts (e.g.,
‘feymr10’). *Note @euro::.
All of the above files should be installed by default in a reasonable
TeX installation.
Optionally, you may create a file ‘texinfo.cnf’ for site
configuration. When processing a Texinfo file, TeX looks for this file
in its search path, which includes the current directory and standard
installation directories. You can use this file for local conventions.
For example, if ‘texinfo.cnf’ contains the line ‘@afourpaper’ (*note A4
Paper::), then all Texinfo documents will be processed with that page
size in effect. If you have nothing to put in ‘texinfo.cnf’, you do not
need to create it.
You can set the ‘TEXINPUTS’ environment variable to allow TeX to find
‘texinfo.cnf’. (This also works for ‘texinfo.tex’ and any other file
TeX might read). For example, if you are using a Bourne
shell-compatible shell (‘sh’, ‘bash’, ‘ksh’, ...), your ‘.profile’ file
could contain the lines:
TEXINPUTS=.:/home/me/mylib:
export TEXINPUTS
These settings would cause TeX first to look for an ‘\input’ file in the
current directory, indicated by the ‘.’, then in a hypothetical user
‘me’'s ‘mylib’ directory, and finally in the system directories. (A
leading, trailing, or doubled ‘:’ indicates searching the system
directories at that point.)
File: texinfo.info, Node: Overfull hboxes, Prev: Preparing for TeX, Up: Hardcopy with TeX
18.6 Overfull "hboxes"
======================
TeX is sometimes unable to typeset a line within the normal margins.
This most often occurs when TeX comes upon what it interprets as a long
word that it cannot hyphenate, such as an electronic mail network
address or a very long identifier. When this happens, TeX prints an
error message like this:
Overfull @hbox (20.76302pt too wide)
(In TeX, lines are in "horizontal boxes", hence the term, "hbox".
‘@hbox’ is a TeX primitive not used in the Texinfo language.)
TeX also provides the line number in the Texinfo source file and the
text of the offending line, which is marked at all the places that TeX
considered hyphenation. *Note Debugging with TeX::, for more
information about typesetting errors.
If the Texinfo file has an overfull hbox, you can rewrite the
sentence so the overfull hbox does not occur, or you can decide to leave
it. A small excursion into the right margin often does not matter and
may not even be noticeable.
If you have many overfull boxes and/or an antipathy to rewriting, you
can coerce TeX into greatly increasing the allowable interword spacing,
thus (if you're lucky) avoiding many of the bad line breaks, like this:
@tex
\global\emergencystretch = .9\hsize
@end tex
(You should adjust the fraction as needed.) This huge value for
‘\emergencystretch’ cannot be the default, since then the typeset output
would generally be of noticeably lower quality; its default value is
‘.15\hsize’. ‘\hsize’ is the TeX dimension containing the current line
width.
For any overfull boxes you do have, TeX will print a large, ugly,
black rectangle beside the line that contains the overfull hbox unless
told otherwise. This is so you will notice the location of the problem
if you are correcting a draft.
To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
before the ‘@titlepage’ command:
@finalout
File: texinfo.info, Node: Generic Translator texi2any, Next: Creating and Installing Info Files, Prev: Hardcopy with TeX, Up: Top
19 ‘texi2any’: The Translator for Texinfo
*****************************************
‘texi2any’ is the generic translator for Texinfo that can produce
different output formats and is highly customizable. It supports these
formats:
Info (by default, or with ‘--info’),
HTML (with ‘--html’),
EPUB 3 (with ‘--epub3’),
plain text (with ‘--plaintext’),
LaTeX (with ‘--latex’),
DocBook (with ‘--docbook’),
Texinfo XML (with ‘--xml’).
‘makeinfo’ is an alias for ‘texi2any’. By default, both ‘texi2any’
and ‘makeinfo’ generate Info output; indeed, there are no differences in
behavior based on the name.
Beside these default formats, command line options to ‘texi2any’ can
change many aspects of the output. Beyond that, initialization files
provide even more control over the final output--nearly anything not
specified in the Texinfo input file. Initialization files are written
in Perl, like the main program, and anything which can be specified on
the command line can also be specified within a initialization file.
* Menu:
* Invoking texi2any:: Running the translator from a shell.
* texi2any Environment Variables:: Control over output format and XS use.
* texi2any Printed Output:: Calling ‘texi2dvi’.
* Customization Variables:: Configuring ‘texi2any’.
* Internationalization of Document Strings:: Translating program-inserted
text.
* Invoking pod2texi:: Translating Perl Pod to Texinfo.
* texi2html:: An ancestor of ‘texi2any’.
File: texinfo.info, Node: Invoking texi2any, Next: texi2any Environment Variables, Up: Generic Translator texi2any
19.1 Invoking ‘texi2any’ from a Shell
=====================================
To process a Texinfo file, invoke ‘texi2any’ followed by the name of the
Texinfo file. Also select the format you want to output with the
appropriate command line option (default is Info). Thus, to create the
Info file for Bison, type the following to the shell:
texi2any --info bison.texi
You can specify more than one input file name; each is processed in
turn. If an input file name is ‘-’, standard input is read.
The ‘texi2any’ program accepts many options. Perhaps the most basic
are those that change the output format. By default, ‘texi2any’ outputs
Info.
Each command line option is either a long name preceded by ‘--’ or a
single letter preceded by ‘-’. You can use abbreviations for the long
option names as long as they are unique.
For example, you could use the following shell command to create an
Info file for ‘bison.texi’ in which lines are filled to only 68 columns:
texi2any --fill-column=68 bison.texi
You can write two or more options in sequence, like this:
texi2any --no-split --fill-column=70 ...
(This would keep the Info file together as one possibly very long file
and would also set the fill column to 70.)
The options are (approximately in alphabetical order):
‘--commands-in-node-names’
This option now does nothing, but remains for compatibility. (It
used to ensure that @-commands in node names were expanded
throughout the document, especially ‘@value’. This is now done by
default.)
‘--conf-dir=DIR’
Prepend DIR to the directory search list for finding customization
files that may be loaded with ‘--init-file’ (see below). The DIR
value can be a single directory, or a list of several directories
separated by the usual path separator character (‘:’ on Unix-like
systems, ‘;’ on Windows).
‘--css-include=FILE’
When producing HTML, literally include the contents of FILE, which
should contain Cascading Style Sheets specifications, in the
‘<style>’ block of the HTML output. If FILE is ‘-’, read standard
input. *Note HTML CSS::.
‘--css-ref=URL’
When producing HTML, add a ‘<link>’ tag to the output which
references a cascading style sheet at URL. This allows using
standalone style sheets.
‘-D VAR’
‘-D 'VAR VALUE'’
Cause the Texinfo variable VAR to be defined. This is equivalent
to ‘@set VAR’ in the Texinfo file (*note @set @clear @value::).
The argument to the option is always one word to the shell; if it
contains internal whitespace, the first word is taken as the
variable name and the remainder as the value. For example, ‘-D
'myvar someval'’ is equivalent to ‘@set myvar someval’.
‘--docbook’
Generate DocBook output (rather than Info).
‘--document-language=LANG’
Use LANG to translate Texinfo keywords which end up in the output
document. The default is the locale specified by the
‘@documentlanguage’ command if there is one, otherwise English
(*note @documentlanguage::).
‘--dvi’
Generate a TeX DVI file using ‘texi2dvi’, rather than Info (*note
texi2any Printed Output::).
‘--dvipdf’
Generate a PDF file using ‘texi2dvi --dvipdf’, rather than Info
(*note texi2any Printed Output::).
‘--enable-encoding’
‘--disable-encoding’
By default, or with ‘--enable-encoding’, output accented and
special characters in Info and plain text output based on the
document encoding. With ‘--disable-encoding’, 7-bit ASCII
transliterations are output. Also obeyed in other output formats
for index keys sorting and for some plain text output.
‘--epub3’
Generate EPUB 3 output.
‘--error-limit=LIMIT’
‘-e LIMIT’
Report LIMIT errors before aborting (on the assumption that
continuing would be useless); default 100.
‘--fill-column=WIDTH’
‘-f WIDTH’
Specify the maximum number of columns in a line; this is the
right-hand edge of a line. Paragraphs that are filled will be
filled to this width. (Filling is the process of breaking up and
connecting lines so that lines are the same length as or shorter
than the number specified as the fill column. Lines are broken
between words.) The default value is 72.
‘--footnote-style=STYLE’
‘-s STYLE’
Set the footnote style to STYLE: either ‘end’ for the end node
style (the default) or ‘separate’ for the separate node style. The
value set by this option overrides the value set in a Texinfo file
by a ‘@footnotestyle’ command (*note Footnote Styles::).
In Info, when the footnote style is ‘separate’, ‘texi2any’ makes a
new node containing the footnotes found in the current node. When
the footnote style is ‘end’, ‘texi2any’ places the footnote
references at the end of the current node.
In HTML, when the footnote style is ‘end’, or if the output is not
split, footnotes are put at the end of the output. If set to
‘separate’, and the output is split, they are placed in a separate
file.
‘--force’
‘-F’
Ordinarily, if the input file has errors, the output files are not
created. With this option, they are preserved.
‘--help’
‘-h’
Print a message with available options and basic usage, then exit
successfully.
‘--html’
Generate HTML output (rather than Info). By default, the HTML
output is split into one output file per node, and the split output
is written into a subdirectory based on the name of the input file.
*Note Generating HTML::.
‘-I DIR’
Append DIR to the directory search list for finding files that are
included using the ‘@include’ command. By default, ‘texi2any’
searches only the current directory. If DIR is not given, the
current directory is appended. The DIR value can be a single
directory or a list of several directories separated by the usual
path separator character (‘:’ on Unix-like systems, ‘;’ on
Windows).
‘--ifdocbook’
‘--ifhtml’
‘--ifinfo’
‘--iflatex’
‘--ifplaintext’
‘--iftex’
‘--ifxml’
For the given format, process ‘@ifFORMAT’ and ‘@FORMAT’ commands,
and do not process ‘@ifnotFORMAT’, regardless of the format being
output. For instance, if ‘--iftex’ is given, then ‘@iftex’ and
‘@tex’ blocks will be read, and ‘@ifnottex’ blocks will be ignored.
‘--no-ifdocbook’
‘--no-ifhtml’
‘--no-ifinfo’
‘--no-iflatex’
‘--no-ifplaintext’
‘--no-iftex’
‘--no-ifxml’
For the given format, do not process ‘@ifFORMAT’ and ‘@FORMAT’
commands, and do process ‘@ifnotFORMAT’, regardless of the format
being output. For instance, if ‘--no-ifhtml’ is given, then
‘@ifhtml’ and ‘@html’ blocks will not be read, and ‘@ifnothtml’
blocks will be.
‘--info’
Generate Info output. By default, if the output file contains more
than about 300,000 bytes, it is split into shorter subfiles of
about that size. The name of the output file and any subfiles is
determined by the input file name, or by ‘@setfilename’, if present
(*note Setting the Output File Name::). *Note Tag and Split
Files::.
‘--init-file=FILE’
Load FILE as code to modify the behavior and output of the
generated manual. It is customary to use the ‘.pm’ or the ‘.init’
extensions for these customization files, but that is not enforced;
the FILE name can be anything. The ‘--conf-dir’ option (see above)
can be used to add to the list of directories in which these
customization files are searched for.
‘--internal-links=FILE’
In HTML mode, output a tab-separated file containing three columns:
the internal link to an indexed item or item in the table of
contents, the name of the index (or table of contents) in which it
occurs, and the term which was indexed or entered. The items are
in the natural sorting order for the given element. This dump can
be useful for post-processors.
‘--latex’
Generate LaTeX output.
‘--macro-expand=FILE’
‘-E FILE’
Output the Texinfo source, with all Texinfo macros expanded, to
FILE. Normally, the result of macro expansion is used internally
by ‘texi2any’ and then discarded.
‘--no-headers’
Do not include menus or node separator lines in the output.
When generating Info, this is the same as using ‘--plaintext’,
resulting in a simple plain text file. Furthermore, output is to
standard output unless overridden with ‘-o’. (This behavior is for
backward compatibility.)
When generating HTML, and output is split, also output navigation
links only at the beginning of each file. If output is not split,
do not include navigation links at the top of each node at all.
*Note Generating HTML::.
‘--node-files’
‘--no-node-files’
With ‘--node-files’, when generating HTML, create redirection files
for anchors and any nodes not already output with the file name
corresponding to the node name (*note HTML Xref Node Name
Expansion::). This makes it possible for section- and
chapter-level cross-manual references to succeed (*note HTML Xref
Configuration::).
If the output is split, this is enabled by default. If the output
is not split, ‘--node-files’ enables the creation of the
redirection files, in addition to the monolithic main output file.
‘--no-node-files’ suppresses the creation of redirection files in
any case. This option has no effect with any output format other
than HTML. *Note Generating HTML::.
‘--no-validate’
‘--no-pointer-validate’
Suppress the pointer-validation phase of ‘texi2any’--a dangerous
thing to do. This can also be done with the ‘@novalidate’ command
(*note Formatting Partial Documents::).
If you do not suppress pointer validation, ‘texi2any’ will check
the validity of cross-references and menu entries in the Texinfo
file, as well as node pointers if they are given explicitly.
‘--no-warn’
Suppress warning messages (but not error messages).
‘--number-footnotes’
‘--no-number-footnotes’
With ‘--no-number-footnotes’, suppress automatic footnote
numbering. By default, footnotes are numbered sequentially within
a node, i.e., the current footnote number is reset to 1 at the
start of each node.
‘--number-sections’
‘--no-number-sections’
With ‘--number-sections’ (the default), output chapter, section,
and appendix numbers as in printed manuals. This works only with
hierarchically structured manuals. You should specify
‘--no-number-sections’ if your manual is not normally structured.
‘--output=FILE’
‘-o FILE’
Specify that the output should be directed to FILE. This overrides
any file name specified in a ‘@setfilename’ command found in the
Texinfo source. If neither ‘@setfilename’ nor this option are
specified, the input file name is used to determine the output
name. *Note Setting the Output File Name::.
If FILE is ‘-’, output goes to standard output and ‘--no-split’ is
implied.
If FILE is a directory or ends with a ‘/’ the usual rules are used
to determine the output file name (namely, use ‘@setfilename’ or
the input file name) but the files are written to the FILE
directory. For example, ‘texi2any -o bar/ foo.texi’, with or
without ‘--no-split’, will write ‘bar/foo.info’, and possibly other
files, under ‘bar/’.
When generating HTML and output is split, FILE is used as the name
for the directory into which all files are written. For example,
‘texi2any -o bar --html foo.texi’ will write ‘bar/index.html’,
among other files.
When generating EPUB a container directory for the files and
directories needed for the EPUB format is created, as well as the
EPUB output file. If FILE corresponds to a directory, the
container directory is placed within FILE. The EPUB output file is
never put in this directory. If FILE corresponds to a file, it is
used for the EPUB output file name.
‘--output-indent=VAL’
This option now does nothing, but remains for compatibility. (It
used to alter indentation in XML/DocBook output.)
‘-P PATH’
Prepend PATH to the directory search list for ‘@include’. If PATH
is not given, the current directory is prepended. See ‘-I’ above.
‘--paragraph-indent=INDENT’
‘-p INDENT’
Set the paragraph indentation style to INDENT. The value set by
this option overrides the value set in a Texinfo file by an
‘@paragraphindent’ command (*note @paragraphindent::). The value
of INDENT is interpreted as follows:
‘asis’
Preserve any existing indentation (or lack thereof) at the
beginnings of paragraphs.
‘0’ or ‘none’
Delete any existing indentation.
NUM
Indent each paragraph by NUM spaces.
The default is to indent by two spaces, except for paragraphs
following a section heading, which are not indented.
‘--pdf’
Generate a PDF file using ‘texi2dvi --pdf’, rather than Info (*note
texi2any Printed Output::).
‘--plaintext’
Output a plain text file (rather than Info): do not include menus
or node separator lines in the output. This results in a
straightforward plain text file that you can (for example) send in
email without complications, or include in a distribution (for
example, an ‘INSTALL’ file).
With this option the output goes to standard output by default,
instead of to a file with a name based on the input file name or
‘@setfilename’; this can be overridden with ‘-o’.
‘--ps’
Generate a PostScript file using ‘texi2dvi --ps’, rather than Info
(*note texi2any Printed Output::).
‘--set-customization-variable VAR=VALUE’
‘-c VAR=VALUE’
Set the customization variable VAR to VALUE. The ‘=’ is optional,
but both VAR and VALUE must be quoted to the shell as necessary so
the result is a single word. Many aspects of ‘texi2any’ behavior
and output may be controlled by customization variables, beyond
what can be set in the document by @-commands and with other
command line switches. *Note Customization Variables::.
‘--split=HOW’
‘--no-split’
When generating Info, by default large output files are split into
smaller subfiles, of approximately 300k bytes. When generating
HTML, by default each output file contains one node (*note
Generating HTML::). ‘--no-split’ suppresses this splitting of the
output.
Alternatively, ‘--split=HOW’ may be used to specify at which level
the HTML output should be split. The possible values for HOW are:
‘chapter’
The output is split at ‘@chapter’ and other sectioning
@-commands at this level (‘@appendix’, etc.).
‘section’
The output is split at ‘@section’ and similar.
‘node’
The output is split at every node. This is the default.
Plain text output can be split similarly to HTML. This may be
useful for extracting sections from a Texinfo document and making
them available as separate files.
‘--split-size=NUM’
Keep Info files to at most NUM characters if possible; default is
300,000. (However, a single node will never be split across Info
files.)
‘--transliterate-file-names’
Enable transliteration of non-ASCII characters in node names for
the purpose of file name creation. *Note HTML Xref 8-bit Character
Expansion::.
‘-U VAR’
Cause VAR to be undefined. This is equivalent to ‘@clear VAR’ in
the Texinfo file (*note @set @clear @value::).
‘--verbose’
Cause ‘texi2any’ to display messages saying what it is doing.
Normally, ‘texi2any’ only outputs messages if there are errors or
warnings.
‘--version’
‘-V’
Print the version number, then exit successfully.
‘--Xopt STR’
Pass STR (a single shell word) to ‘texi2dvi’; may be repeated
(*note texi2any Printed Output::).
‘--xml’
Generate Texinfo XML output (rather than Info).
File: texinfo.info, Node: texi2any Environment Variables, Next: texi2any Printed Output, Prev: Invoking texi2any, Up: Generic Translator texi2any
19.2 Environment Variables Recognized by ‘texi2any’
===================================================
‘texi2any’ also reads the environment variable ‘TEXINFO_OUTPUT_FORMAT’
to determine the output format, if not overridden by a command line
option. The value should be one of:
docbook dvi dvipdf epub3 html info latex pdf plaintext ps xml
If not set or otherwise specified, Info output is the default.
‘TEXINFO_OUTPUT_FORMAT’ may take some other special values, which do
not correspond to any command-line settable output format (*note
Customization Variables and Options::).
The customization variable of the same name is also read; if set,
that overrides an environment variable setting, but not a command-line
option. *Note Customization Variables and Options::.
You can control ‘texi2any’'s use of Perl extension modules by setting
the ‘TEXINFO_XS’ environment variable. These modules are compiled
native code that the interpreted Perl code can use. Ideally, these
extension modules should just work, and the only noticeable difference
they should make is that ‘texi2any’ finishes running sooner. However,
you can use this environment variable for the purposes of
troubleshooting: for example, if you have problems with the output of
‘texi2any’ varying depending on whether the extension modules are in
use.
The following values of ‘TEXINFO_XS’ are recognized by ‘texi2any’:
‘default’
The default behavior. Try to load extension modules, and silently
fall back to the interpreted Perl implementations if this fails.
‘warn’
Try to load extension modules, and if this fails, give a warning
message before falling back to the interpreted Perl
implementations.
‘debug’
Try to load extension modules, printing many messages while doing
so.
‘omit’
Do not use extension modules.
Set ‘TEXINFO_XS_PARSER’ to ‘0’ to disable the use of the native code
implementation of the parser module. This is the part of ‘texi2any’
that converts Texinfo input into an internal tree format used for
further processing into output formats. This may be useful for working
around bugs or incompatibilities between the native code implementation
and the implementation in pure Perl code.
File: texinfo.info, Node: texi2any Printed Output, Next: Customization Variables, Prev: texi2any Environment Variables, Up: Generic Translator texi2any
19.3 ‘texi2any’ Printed Output
==============================
To justify the name Texinfo-to-_any_, ‘texi2any’ has basic support for
creating printed output in the various formats: TeX DVI, PDF, and
PostScript. This is done via the simple method of executing the
‘texi2dvi’ program when those output formats are requested, after
checking the validity of the input to give users the benefit of
‘texi2any’'s error checking. If you don't want such error checking,
perhaps because your manual plays advanced TeX tricks together with
‘texinfo.tex’, just invoke ‘texi2dvi’ directly.
The output format options for this are ‘--dvi’, ‘--dvipdf’, ‘--pdf’,
and ‘--ps’. *Note Format with texi2dvi::, for more details on these
options and general ‘texi2dvi’ operation. In addition, the ‘--verbose’,
‘--silent’, and ‘--quiet’ options are passed on if specified; the ‘-I’
and ‘-o’ options are likewise passed on with their arguments, and
‘--debug’ without its argument.
The only option remaining that is related to the ‘texi2dvi’
invocation is ‘--Xopt’. Here, just the argument is passed on and
multiple ‘--Xopt’ options accumulate. This provides a way to construct
an arbitrary command line for ‘texi2dvi’. For example, running
texi2any --Xopt -t --Xopt @a4paper --pdf foo.texi
is equivalent to running
texi2dvi -t @a4paper --pdf foo.texi
except for the validity check.
Although one might wish that other options to ‘texi2any’ would take
effect, they don't. For example, running ‘texi2any --no-number-sections
--dvi foo.texi’ still results in a DVI file with numbered sections.
(Perhaps this could be improved in the future, if requests are
received.)
The actual name of the command that is invoked is specified by the
‘TEXI2DVI’ customization variable (*note Other Customization
Variables::). As you might guess, the default is ‘texi2dvi’.
‘texi2any’ itself does not generate any normal output when it invokes
‘texi2dvi’, only diagnostic messages.
File: texinfo.info, Node: Customization Variables, Next: Internationalization of Document Strings, Prev: texi2any Printed Output, Up: Generic Translator texi2any
19.4 Customization Variables
============================
Warning: These customization variable names and meanings may change
in any Texinfo release. We always try to avoid incompatible
changes, but we cannot absolutely promise, since needs change over
time.
Many aspects of the behavior and output of ‘texi2any’ may be modified
by modifying so-called “customization variables”. These fall into a few
general categories:
• Those associated with @-commands; for example, ‘@documentlanguage’.
• Those associated with command-line options; for example, the
customization variable ‘SPLIT’ is associated with the ‘--split’
command-line option, and ‘TEXINFO_OUTPUT_FORMAT’ allows specifying
the output format.
• Those associated with customizing the HTML output.
• Other ad hoc variables.
Customization variables may set on the command line using
‘--set-customization-variable 'VAR VALUE'’ (quoting the variable/value
pair to the shell) or ‘--set-customization-variable VAR=VALUE’ (using
‘=’). A special VALUE is ‘undef’, which sets the variable to this
special "undefined" Perl value.
The sections below give the details for each of these.
* Menu:
* Commands: Customization Variables for @-Commands.
* Options: Customization Variables and Options.
* HTML: HTML Customization Variables.
* MathJax: MathJax Customization Variables.
* latex2html: latex2html Customization Variables.
* tex4ht: tex4ht Customization Variables.
* LaTeX: LaTeX Customization Variables.
* Other: Other Customization Variables.
File: texinfo.info, Node: Customization Variables for @-Commands, Next: Customization Variables and Options, Up: Customization Variables
19.4.1 Customization Variables for @-Commands
---------------------------------------------
Each of the following @-commands has an associated customization
variable with the same name (minus the leading ‘@’):
@afivepaper @afourpaper @afourlatex
@afourwide @allowcodebreaks @bsixpaper
@contents @clickstyle @codequotebacktick
@codequoteundirected @deftypefnnewline @documentdescription
@documentencoding @documentlanguage @evenfooting
@evenfootingmarks @evenheading @evenheadingmarks
@everyfooting @everyfootingmarks @everyheading
@everyheadingmarks @exampleindent @firstparagraphindent
@fonttextsize @footnotestyle @frenchspacing
@headings @kbdinputstyle @microtype
@novalidate @oddfooting @oddfootingmarks
@oddheading @oddheadingmarks @pagesizes
@paragraphindent @setfilename @setchapternewpage
@shortcontents @smallbook @summarycontents
@urefbreakstyle @xrefautomaticsectiontitle
Setting such a customization variable to a value ‘foo’ is similar to
executing ‘@CMD foo’. It is not exactly the same, though, since any
side effects of parsing the Texinfo source are not redone. Also, some
variables do not take Texinfo code when generating particular formats,
but an argument that is already formatted. This is the case, for
example, for HTML for ‘documentdescription’.
Note that if ‘texi2any’ is invoked to process the file with TeX
(e.g., with the ‘--pdf’ option), then these customization variables may
not be passed on to TeX.
File: texinfo.info, Node: Customization Variables and Options, Next: HTML Customization Variables, Prev: Customization Variables for @-Commands, Up: Customization Variables
19.4.2 Customization Variables and Options
------------------------------------------
The following table gives the customization variables associated with
some command line options. *Note Invoking texi2any::, for the meaning
of the options.
Option Variable
--------------------------------------------------------------------------
‘--enable-encoding’ ‘ENABLE_ENCODING’
‘--document-language’ ‘documentlanguage’
‘--error-limit’ ‘ERROR_LIMIT’
‘--fill-column’ ‘FILLCOLUMN’
‘--footnote-style’ ‘footnotestyle’
‘--force’ ‘FORCE’
‘--internal-links’ ‘INTERNAL_LINKS’
‘--macro-expand’ ‘MACRO_EXPAND’
‘--headers’ ‘HEADERS’, ‘FORMAT_MENU’
‘--no-warn’ ‘NO_WARN’
‘--no-validate’ ‘novalidate’
‘--number-footnotes’ ‘NUMBER_FOOTNOTES’
‘--number-sections’ ‘NUMBER_SECTIONS’
‘--node-files’ ‘NODE_FILES’
‘--output’ ‘OUTFILE’, ‘SUBDIR’
‘--paragraph-indent’ ‘paragraphindent’
‘--silent’ ‘SILENT’
‘--split’ ‘SPLIT’
‘--split-size’ ‘SPLIT_SIZE’
‘--transliterate-file-names’ ‘TRANSLITERATE_FILE_NAMES’
‘--verbose’ ‘VERBOSE’
Setting such a customization variable to a value ‘foo’ is essentially
the same as specifying the ‘--OPT=foo’ if the option takes an argument,
or ‘--OPT’ if not.
In addition, the customization variable ‘TEXINFO_OUTPUT_FORMAT’
allows specifying what ‘texi2any’ outputs, either one of the usual
output formats that can be specified with options, or various other
forms:
‘docbook’
‘dvi’
‘dvipdf’
‘epub3’
‘html’
‘info’
‘pdf’
‘plaintext’
‘ps’
‘xml’
These correspond to the command-line options (and
‘TEXINFO_OUTPUT_FORMAT’ environment variable values) of the same
name. *Note Invoking texi2any::.
‘debugtree’
Instead of generating a regular output format, output a text
representation of the tree obtained by parsing the input texinfo
document.
‘parse’
Do only Texinfo source parsing; there is no output.
‘plaintexinfo’
Output the Texinfo source with all the macros, ‘@include’ and
‘@value{}’ expanded. This is similar to setting ‘--macro-expand’,
but instead of being output in addition to the normal conversion,
output of Texinfo is the main output.
‘rawtext’
Output raw text, with minimal formatting. For example, footnotes
are ignored and there is no paragraph filling. This is used by the
parser for file names and copyright text in HTML comments, for
example.
‘structure’
Do only Texinfo source parsing and determination of the document
structure; there is no output.
‘texinfosxml’
Output the document in TexinfoSXML representation, a syntax for
writing XML data using Lisp S-expressions.
‘textcontent’
Output the text content only, stripped of commands; this is useful
for spell checking or word counting, for example. The trivial
‘detexinfo’ script setting this is in the ‘util’ directory of the
Texinfo source as an example. It's one line:
exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent "$@"
File: texinfo.info, Node: HTML Customization Variables, Next: MathJax Customization Variables, Prev: Customization Variables and Options, Up: Customization Variables
19.4.3 HTML Customization Variables
-----------------------------------
This table gives the customization variables which apply to HTML output
only. A few other customization variables apply to both HTML and other
output formats; see *note Other Customization Variables::.
‘AVOID_MENU_REDUNDANCY’
If set, and the menu entry and menu description are the same, then
do not print the menu description; default false.
‘AFTER_BODY_OPEN’
If set, the corresponding text will appear at the beginning of each
HTML file; default unset.
‘AFTER_SHORT_TOC_LINES’
‘AFTER_TOC_LINES’
If set, the corresponding text is output after the short table of
contents for ‘AFTER_SHORT_TOC_LINES’ and after the table of
contents for ‘AFTER_TOC_LINES’; otherwise, a default string is
used. At the time of writing, a ‘</div>’ element is closed.
In general, you should set ‘BEFORE_SHORT_TOC_LINES’ if
‘AFTER_SHORT_TOC_LINES’ is set, and you should set
‘BEFORE_TOC_LINES’ if ‘AFTER_TOC_LINES’ is set.
‘BASEFILENAME_LENGTH’
The maximum length of a base file name; default 245. Changing this
would make cross-manual references to such long node names invalid
(*note HTML Xref Link Basics::).
‘BEFORE_SHORT_TOC_LINES’
‘BEFORE_TOC_LINES’
If set, the corresponding text is output before the short table of
contents for ‘BEFORE_SHORT_TOC_LINES’ and before the table of
contents for ‘BEFORE_TOC_LINES’, otherwise a default string is
used. At the time of writing, a ‘<div ...>’ element is opened.
In general you should set ‘AFTER_SHORT_TOC_LINES’ if
‘BEFORE_SHORT_TOC_LINES’ is set, and you should set
‘AFTER_TOC_LINES’ if ‘BEFORE_TOC_LINES’ is set.
‘BIG_RULE’
Rule used after and before the top element and before special
elements, but not for footers and headers; default ‘<hr>’.
‘BODYTEXT’
The text appearing in ‘<body>’. By default, sets the HTML ‘lang’
attribute to the document language (*note @documentlanguage::).
‘CASE_INSENSITIVE_FILENAMES’
Construct output file names as if the filesystem were case
insensitive (*note HTML Splitting::); default false.
‘CHAPTER_HEADER_LEVEL’
Header formatting level used for chapter level sectioning commands;
default ‘2’.
‘CHECK_HTMLXREF’
Check that manuals which are the target of external
cross-references (*note Four and Five Arguments::) are present in
‘htmlxref.cnf’ (*note HTML Xref Configuration::); default false.
‘COMPLEX_FORMAT_IN_TABLE’
If set, use tables for indentation of complex formats; default
false.
‘CONTENTS_OUTPUT_LOCATION’
If set to ‘after_top’, output the contents at the end of the ‘@top’
section. If set to ‘inline’, output the contents where the
‘@contents’ and similar @-commands are located. If set to
‘separate_element’ output the contents in separate elements, either
at the end of the document if not split, or in a separate file. If
set to ‘after_title’ the tables of contents are output after the
title; default ‘after_top’.
‘CONVERT_TO_LATEX_IN_MATH’
If set, try to convert any Texinfo @-commands inside ‘@math’ and
‘@displaymath’ to LaTeX, before converting the ‘@math’ or
‘@displaymath’ to HTML. Default ‘undef’. If undefined, set if
‘HTML_MATH’ is set.
‘COPIABLE_LINKS’
If set, output copiable links for the definition commands (*note
Definition Commands::) and table commands (*note Two-column
Tables::) where an index entry is defined. A link appears as a '¶'
sign that appears when you hover the mouse pointer over the heading
text.
‘DATE_IN_HEADER’
Put the document generation date in the header; off by default.
‘DEF_TABLE’
If set, a ‘<table>’ construction for ‘@deffn’ and similar
@-commands is used (looking more like the TeX output), instead of
definition lists; default false.
‘DEFAULT_RULE’
Rule used between element, except before and after the top element,
and before special elements, and for footers and headers; default
‘<hr>’.
‘DO_ABOUT’
If set to 0 never do an About special element; if set to 1 always
do an About special element; default 0.
‘EXTERNAL_CROSSREF_SPLIT’
For cross-references to other manuals, this determines if the other
manual is considered to be split or monolithic. By default, it is
set based on the value of ‘SPLIT’. *Note HTML Xref::, and *note
HTML Xref Configuration::.
‘EXTERNAL_DIR’
Base directory for external manuals; default none. It is better to
use the general external cross-reference mechanism (*note HTML Xref
Configuration::) than this variable.
‘EXTERNAL_CROSSREF_EXTENSION’
File extension for cross-references to other manuals. If unset,
based on ‘EXTENSION’.
‘EXTRA_HEAD’
Additional text appearing within ‘<head>’; default unset.
‘FOOTNOTE_END_HEADER_LEVEL’
Header formatting level used for the footnotes header with the
'end' footnotestyle; default ‘4’. *Note Footnote Styles::.
‘FOOTNOTE_SEPARATE_HEADER_LEVEL’
Header formatting level used for the footnotes header with the
'separate' footnotestyle; default ‘4’. *Note Footnote Styles::.
‘FRAMES’
If set, a file describing the frame layout is generated, together
with a file with the short table of contents; default false.
‘FRAMESET_DOCTYPE’
Same as DOCTYPE, but for the file containing the frame description.
‘HEADER_IN_TABLE’
Use tables for header formatting rather than a simple ‘<div>’
element; default false.
‘HTML_MATH’
Method to use to render ‘@math’. This can be unset, set to
‘mathjax’ (*note MathJax Customization Variables::), set to ‘l2h’,
which uses ‘latex2html’ (*note latex2html Customization
Variables::), or set to ‘t4h’, which uses ‘tex4ht’ (*note tex4ht
Customization Variables::). In the default case, setting
‘HTML_MATH’ also sets ‘CONVERT_TO_LATEX_IN_MATH’.
‘HTML_ROOT_ELEMENT_ATTRIBUTES’
Use that string for the ‘<html>’ HTML document root element.
Default undefined.
‘HTMLXREF_FILE’
Set the file name used for cross-references to other manuals. If
not defined, ‘htmlxref.cnf’ is used (*note HTML Xref
Configuration::). Not defined in the default case. If ‘TEST’ is
set, ‘HTMLXREF_MODE’ is set to the default and ‘HTMLXREF_FILE’ is
not defined, information on cross-references to other manuals is
not used.
If ‘HTMLXREF_MODE’ is set to ‘file’ the file name is directly used
as the source of information, otherwise the file name is searched
for in directories, and all the files found are used (*note HTML
Xref Configuration::).
‘HTMLXREF_MODE’
How cross-references to other manuals information is determined.
If set to ‘none’, no information is used. If set to ‘file’, the
information is determined from a file path, ‘htmlxref.cnf’ in the
default case, or the value of ‘HTMLXREF_FILE’. If not defined (the
default) or set to any other value, search in directories and use
all the files (*note HTML Xref Configuration::).
‘ICONS’
Use icons for the navigation panel; default false.
‘IMAGE_LINK_PREFIX’
If set, the associated value is prepended to the image file links;
default unset.
‘INDEX_ENTRY_COLON’
Symbol used between the index entry and the associated node or
section; default ‘:’.
‘INFO_JS_DIR’
(Experimental.) Add a JavaScript browsing interface to the manual.
The value of the variable is the directory to place the code for
this interface, so you would run the program as e.g. ‘texi2any
--html -c INFO_JS_DIR=js MANUAL.texi’ to place files in a ‘js’
directory under the output. This provides some of the
functionality of the Info browsers in a web browser, such as
keyboard navigation and index lookup. This only works with
non-split HTML output.
The interface should provide an acceptable fallback in
functionality if JavaScript or web browser features are not
available. However, please be cautious when using this option, in
case you do make your documentation harder to access for some of
your users.
‘IGNORE_REF_TO_TOP_NODE_UP’
Ignore references to ‘TOP_NODE_UP’, the up node for the Top node.
‘INLINE_CSS_STYLE’
Put CSS directly in HTML elements rather than at the beginning of
the output; default false.
‘JS_WEBLABELS’
‘JS_WEBLABELS_FILE’
Specify how to use a “JavaScript license web labels” page to give
licensing information and source code for any JavaScript used in
the HTML files for the manual. (See
<https://www.gnu.org/licenses/javascript-labels.html>).
With the value ‘generate’ (the default), generate a labels page at
‘JS_WEBLABELS_FILE’, and link to it in the HTML output files. Only
do this if actually referencing JavaScript files (either with
‘HTML_MATH’ set to ‘mathjax’, or when using the experimental JS
browsing interface when ‘INFO_JS_DIR’ is set). With this setting,
‘JS_WEBLABELS_FILE’ must be a relative file name.
With the value ‘reference’, link to the labels file given by
‘JS_WEBLABELS_FILE’ in the output, and do not generate a labels
file. This setting is useful if you separately maintain a single
labels file for a larger website that includes your manual.
With ‘omit’, neither generate nor link to a labels file.
‘MAX_HEADER_LEVEL’
Maximum header formatting level used (higher header formatting
level numbers correspond to lower sectioning levels); default ‘4’.
‘MENU_ENTRY_COLON’
Symbol used between the menu entry and the description; default
‘:’.
‘MENU_SYMBOL’
Symbol used in front of menu entries when node names are used for
menu entries formatting; default is undefined and set to ‘•’
if ‘USE_NUMERIC_ENTITY’ is not set, and to ‘’’ if set.
‘MONOLITHIC’
Output only one file including the table of contents. Set by
default, but only relevant when the output is not split.
‘NO_CSS’
Do not use CSS; default false. *Note HTML CSS::.
‘NO_CUSTOM_HTML_ATTRIBUTE’
Do not output HTML with custom attributes in elements; default
false.
‘NO_NUMBER_FOOTNOTE_SYMBOL’
Symbol used for footnotes if ‘NUMBER_FOOTNOTES’ is false. Default
is ‘*’.
‘NODE_NAME_IN_INDEX’
If true, use node names in index entries, otherwise prefer section
names. If undefined, use ‘USE_NODES’ value in HTML. Default is
undefined.
‘PRE_BODY_CLOSE’
If set, the given text will appear at the footer of each HTML file;
default unset.
‘PROGRAM_NAME_IN_ABOUT’
Used when an About element is output. If set, output the program
name and miscellaneous related information in About special
element; default false.
‘PROGRAM_NAME_IN_FOOTER’
If set, output the program name and miscellaneous related
information in the page footers; default false.
‘SECTION_NAME_IN_TITLE’
If set, when output is split, use the argument of the chapter
structuring command (e.g., ‘@chapter’ or ‘@section’) in the
‘<title>’ instead of the argument to ‘@node’.
‘SHORT_TOC_LINK_TO_TOC’
If set, the cross-references in the Short table of contents links
to the corresponding Table of Contents entries, if a Table of
Contents is output; default true.
‘SHOW_BUILTIN_CSS_RULES’
Output the built-in default CSS rules on the standard output and
exit.
‘SHOW_TITLE’
If set, output the title at the beginning of the document; default
‘undef’. If set to ‘undef’, setting ‘NO_TOP_NODE_OUTPUT’ also sets
‘SHOW_TITLE’ for HTML.
‘SIMPLE_MENU’
If set, use a simple preformatted style for the menu, instead of
breaking down the different parts of the menu; default false.
*Note Menu Parts::.
‘TOC_LINKS’
If set, links from headings to toc entries are created; default
false.
‘TOP_FILE’
This file name may be used for the top-level file. The extension
is set appropriately, if necessary. This is used to override the
default, and is, in general, only taken into account when output is
split, and for HTML.
‘TOP_NODE_FILE_TARGET’
File name used for the Top node in cross-references; default is
‘index.html’.
‘TOP_NODE_UP_URL’
A URL used for Top node up references; the default is ‘undef’, in
that case no Top node Up reference is generated. For more about
the Top node pointers, *note First Node::. For overriding the Up
pointer name in case ‘TOP_NODE_UP_URL’ is set and for other
formats, see ‘TOP_NODE_UP’ in *note Other Customization
Variables::.
‘USE_ACCESSKEY’
Use ‘accesskey’ in cross-references; default true.
‘USE_ISO’
Use entities for doubled single-quote characters (*note Inserting
Quotation Marks::), and ‘---’ and ‘--’ (*note Conventions::);
default true.
‘USE_LINKS’
Generate ‘<link>’ elements in the HTML ‘<head>’ output; default
true.
‘USE_NEXT_HEADING_FOR_LONE_NODE’
If set, a node not associated to a sectioning command but followed
by a heading command not usually associated to node such as
‘@heading’ before other formatted contents do not have its name
output as a heading, under the assumption that the command found
provides the heading. Default true.
‘USE_NODE_DIRECTIONS’
If true, use nodes to determine where next, up and prev link to in
node headers. If false, use sections. If undefined, use
‘USE_NODES’ value. Default is undefined. Note that this setting
does not determine the link string only where the links points to,
see *note xrefautomaticsectiontitle: Three Arguments. for the link
string customization. If nodes and sections are systematically
associated, this customization has no practical effect.
‘USE_REL_REV’
Use ‘rel’ in cross-references; default true.
‘USE_TITLEPAGE_FOR_TITLE’
Use the full ‘@titlepage’ as the title, not a simple title string;
default true. Only relevant if ‘SHOW_TITLE’ is set.
‘USE_XML_SYNTAX’
Use XML/XHTML compatible syntax.
‘VERTICAL_HEAD_NAVIGATION’
If set, a vertical navigation panel is used; default false.
‘WORDS_IN_PAGE’
When output is split by nodes, specifies the approximate minimum
page length at which a navigation panel is placed at the bottom of
a page. To avoid ever having the navigation buttons at the bottom
of a page, set this to a sufficiently large number. The default is
300.
‘XREF_USE_FLOAT_LABEL’
If set, for the float name in cross-references, use the float label
instead of the type followed by the float number (*note @float::).
The default is off.
‘XREF_USE_NODE_NAME_ARG’
Only relevant for cross-reference commands with no cross reference
name (second argument). If set to 1, use the node name (first)
argument in cross-reference @-commands for the text displayed as
the hyperlink. If set to 0, use the node name if ‘USE_NODES’ is
set, otherwise the section name. If set to ‘undef’, use the first
argument in preformatted environments, otherwise use the node name
or section name depending on ‘USE_NODES’. The default is ‘undef’.
File: texinfo.info, Node: MathJax Customization Variables, Next: latex2html Customization Variables, Prev: HTML Customization Variables, Up: Customization Variables
19.4.4 MathJax Customization Variables
--------------------------------------
This table lists the customization variables which can be used when
MathJax is being used, which will be the case when ‘HTML_MATH’ is set to
‘mathjax’.
‘MATHJAX_SCRIPT’
URL of the MathJax component file (e.g. ‘tex-svg.js’) you are
using. ‘texi2any’ provides a default value for this variable, but
you are encouraged to host this file yourself on your website so
that you are not dependent on others' hosting.
‘MATHJAX_SOURCE’
A URL of the full source code in its preferred form for
modification, or instructions for obtaining such source code, for
the component file named by ‘MATHJAX_SCRIPT’. 'Preferred form for
modification' means that this should not be in a 'minified' form.
Used in the license labels page (*note HTML Customization
Variables::, under ‘JS_WEBLABELS’).
Again, ‘texi2any’ provides a default value for this variable, but
you are encouraged to host the source code for MathJax and its
dependencies yourself. This is in order to make the source code
available reliably, and to reduce you and your users' dependence on
others' distribution systems.
File: texinfo.info, Node: latex2html Customization Variables, Next: tex4ht Customization Variables, Prev: MathJax Customization Variables, Up: Customization Variables
19.4.5 ‘latex2html’ Customization Variables
-------------------------------------------
This table lists the customization variables which can be used when
‘latex2html’ is being used to convert ‘@math’, ‘@displaymath’, ‘@latex’
and ‘@tex’ sections for HTML. These customization variables are
relevant only if ‘HTML_MATH’ is set to ‘l2h’.
To actually convert ‘@tex’ sections, ‘--iftex’ should be used, and to
actually convert ‘@latex’ sections, ‘--iflatex’ should be used.
‘L2H_CLEAN’
If set, the intermediate files generated in relation with
‘latex2html’ are removed; default true.
‘L2H_FILE’
If set, the given file is used as ‘latex2html’'s init file; default
unset.
‘L2H_HTML_VERSION’
The HTML version used in the ‘latex2html’ call; default unset.
‘L2H_L2H’
The program invoked as ‘latex2html’; default is ‘latex2html’.
‘L2H_SKIP’
If set to a true value, the actual call to ‘latex2html’ is skipped;
previously generated content is reused instead. If set to 0, the
cache is not used at all. If set to ‘undef’, the cache is used for
as many TeX fragments as possible and for any remaining the command
is run. The default is ‘undef’.
‘L2H_TMP’
Set the directory used for temporary files. None of the file name
components in this directory name may start with ‘.’; otherwise,
‘latex2html’ will fail (because of ‘dvips’). The default is the
empty string, which means the current directory.
File: texinfo.info, Node: tex4ht Customization Variables, Next: LaTeX Customization Variables, Prev: latex2html Customization Variables, Up: Customization Variables
19.4.6 ‘tex4ht’ Customization Variables
---------------------------------------
This table lists the customization variables which can be used when
‘tex4ht’ is being used to convert ‘@math’, ‘@displaymath’, ‘@tex’ and
‘@latex’ sections for HTML. These customization variables are relevant
only if ‘HTML_MATH’ is set to ‘t4h’.
To actually convert ‘@tex’ sections, ‘--iftex’ should be used, and to
actually convert ‘@latex’ sections, ‘--iflatex’ should be used.
‘T4H_LATEX_CONVERSION’
If set, the conversion type used for ‘@latex’ sections.
Possibilities are ‘latex’, ‘tex’ and ‘texi’. Set to ‘latex’ if not
defined.
‘T4H_MATH_CONVERSION’
If set, the conversion type used for ‘@math’ and ‘@displymath’.
Possibilities are ‘latex’, ‘tex’ and ‘texi’. Set to ‘tex’ if not
defined.
‘T4H_TEX_CONVERSION’
If set, the conversion type used for ‘@tex’ sections.
Possibilities are ‘latex’, ‘tex’ and ‘texi’. Set to ‘tex’ if not
defined.
File: texinfo.info, Node: LaTeX Customization Variables, Next: Other Customization Variables, Prev: tex4ht Customization Variables, Up: Customization Variables
19.4.7 LaTeX Customization Variables
------------------------------------
warning: LaTeX output customization is experimental. Nothing is
decided, everything can change, and we would welcome any feedback.
This table gives the customization variables which apply to LaTeX
output only.
‘CLASS_BEGIN_USEPACKAGE’
If set, the corresponding text will replace the LaTeX
‘\documentclass’, package imports that are always output and are
output right after ‘\documentclass’, and package imports that
depend on the document encoding setting the input and font encoding
(‘inputenc’ and ‘fontenc’).
The text replaced is along:
\documentclass{book}
\usepackage{amsfonts}
\usepackage{amsmath}
\usepackage[gen]{eurosym}
\usepackage{textcomp}
\usepackage{graphicx}
\usepackage{etoolbox}
\usepackage{titleps}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
‘END_USEPACKAGE’
If set, the corresponding text will replace the package imports
that depend on the Texinfo commands used, and the last packages
imports that are always output and output after all the other
packages imports. The last package imports corresponds to
‘\usepackage[hidelinks]{hyperref}’.
Here is an example of the corresponding text for a document with
indices, ‘@need’, ‘@multitable’, definition commands, ‘@cartouche’,
lists, and ‘@float’:
\usepackage{imakeidx}
\usepackage{needspace}
\usepackage{array}
\usepackage{embrac}
\usepackage{expl3}
\usepackage{tabularx}
\usepackage[framemethod=tikz]{mdframed}
\usepackage{enumitem}
\usepackage{float}
\usepackage[hidelinks]{hyperref}
File: texinfo.info, Node: Other Customization Variables, Prev: LaTeX Customization Variables, Up: Customization Variables
19.4.8 Other Customization Variables
------------------------------------
This table gives the remaining customization variables, which apply to
multiple formats, or affect global behavior, or otherwise don't fit into
the categories of the previous sections.
‘ASCII_DASHES_AND_QUOTES’
For Info output, when set, use plain ASCII characters to represent
quotation marks, hyphens and dashes when these are given in the
Texinfo source as ‘-’, ‘--’, ‘---’, ‘`’, ‘``’, ‘'’, and ‘''’,
rather than UTF-8 directional quotation marks, en dashes, vel sim.
On by default.
‘ASCII_GLYPH’
For Info output, use ASCII output for glyph commands such as the
copyright sign (‘@copyright{}’, becoming ‘(C)’), and the bullet
symbol (‘@bullet{}’, becoming ‘*’), rather than other Unicode
sequences. Off by default.
‘ASCII_PUNCTUATION’
Avoid any unncessary or gratuitious non-ASCII, UTF-8 sequences in
the output. Implies both ‘ASCII_DASHES_AND_QUOTES’ and
‘ASCII_GLYPH’ and additionally affects the output of commands such
as ‘@samp’ which output quotation marks.
‘AUTO_MENU_DESCRIPTION_ALIGN_COLUMN’
For Info output, column at which to start a menu entry description
provided by ‘@nodedescription’ or ‘@nodedescriptionblock’.
Undefined by default, in which case 45% of the fill column value is
used (*note Invoking texi2any::).
‘AUTO_MENU_MAX_WIDTH’
Maximum number of columns in a menu entry line in Info when adding
a description from ‘@nodedescription’ or ‘@nodedescriptionblock’.
Undefined by default, in which case 10% more than the fill column
value is used (*note Invoking texi2any::).
‘CHECK_MISSING_MENU_ENTRY’
When a ‘@menu’ block occurs in a node, check if there is a menu
entry for all subordinate nodes in the document sectioning
structure. On by default.
‘CHECK_NORMAL_MENU_STRUCTURE’
Warn if the node pointers (either explicitly or automatically set)
are not consistent with the order of node menu entries. This is a
more thorough structure check than that provided by
‘CHECK_MISSING_MENU_ENTRY’. Off by default.
‘CLOSE_QUOTE_SYMBOL’
When a closing quote is needed, e.g. for ‘@samp’ output, use this
character; default ‘’’ in DocBook. Undefined in the default
case in HTML and set to ‘’’ if ‘USE_NUMERIC_ENTITY’ is not
set, to ‘’’ if set, and to a quote character if
‘OUTPUT_CHARACTERS’ is set and the output encoding includes that
character.
The default for Info is set the same as for ‘OPEN_QUOTE_SYMBOL’,
except that the Unicode code is a closing quote (see below).
‘CLOSE_DOUBLE_QUOTE_SYMBOL’
When a closing double quote is needed, for ‘@dfn’ in Info, use this
character. The default for Info is set the same as for
‘OPEN_DOUBLE_QUOTE_SYMBOL’, except that the Unicode code is a
closing double quote (see below).
‘COMMAND_LINE_ENCODING’
Encoding used to decode command-line arguments. Default is based
on the locale encoding. This may affect file names inserted into
output files or error messages printed by the program.
Note that some file and directory names from the command line may
not be decoded immediately, and may not be decoded at all.
‘CPP_LINE_DIRECTIVES’
Recognize ‘#line’ directives in a "preprocessing" pass (*note
External Macro Processors::); on by default.
‘DEBUG’
If set, debugging output is generated; default is off (zero).
‘DOC_ENCODING_FOR_INPUT_FILE_NAME’
If set, use the input Texinfo document encoding information for the
encoding of input file names, such as file names specified as
‘@include’ or ‘@verbatiminclude’ arguments. If unset, use the
locale encoding instead. Default is set, except on MS-Windows
where the locale encoding is used by default.
Note that this is for file names only; the default encoding or
‘@documentencoding’ is always used for the encoding of file content
(*note @documentencoding::).
The ‘INPUT_FILE_NAME_ENCODING’ variable overrides this variable.
‘DOC_ENCODING_FOR_OUTPUT_FILE_NAME’
If set, use the input Texinfo document encoding information for the
encoding of output file names, such as files specified with
‘--output’. If unset, use the locale encoding instead. Default is
unset, so files names are encoded using the current locale.
Note that this is for file names only; ‘OUTPUT_ENCODING_NAME’ is
used for the encoding of file content.
The ‘OUTPUT_FILE_NAME_ENCODING’ variable overrides this variable.
‘DOCTYPE’
For DocBook, HTML, XML. Specifies the ‘SystemLiteral’, the
entity's system identifier. This is a URI which may be used to
retrieve the entity, and identifies the canonical DTD for the
document. The default value is different for each of HTML, DocBook
and XML.
‘DUMP_TEXI’
For debugging. If set, no conversion is done, only parsing and
macro expansion. If the option ‘--macro-expand’ is set, the
Texinfo source is also expanded to the corresponding file. Default
false.
‘DUMP_TREE’
For debugging. If set, the tree constructed upon parsing a Texinfo
document is output to standard error; default false.
‘EPUB_CREATE_CONTAINER_FILE’
If set to 0, do not generate the EPUB output file. Default is set
to 1.
‘EPUB_KEEP_CONTAINER_FOLDER’
If set, keep the directory containing the directories and files
needed for EPUB. The EPUB output file is a ZIP archive of this
directory. Default is not defined. Set if not defined and ‘TEST’
or ‘DEBUG’ is set. *Note EPUB Output File and Directory::.
‘EXTENSION’
The extension added to the output file name. The default is
different for each output format.
‘FORMAT_MENU’
If set to ‘menu’, output Texinfo menus. This is the default for
Info. ‘sectiontoc’ is the default setting for HTML, where instead
of the contents of ‘@menu’ blocks being output, a list of
subordinate sections is output in each node. If set to ‘nomenu’,
do not output menus.
This variable is set to ‘nomenu’ when generating DocBook, or when
‘--no-headers’ is specified.
‘HIGHLIGHT_SYNTAX’
If set, ‘@example’ blocks with language information as first
argument are highlighted in the HTML output. It is also possible
to specify a default for the language with
‘HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE’. Syntax highlighting requires
an external program to generate the highlighted HTML. The
‘HIGHLIGHT_SYNTAX’ value allows to select a specific program. The
possibilities are ‘highlight’, ‘pygments’, any other value standing
for ‘source-highlight’ (*note Syntax Highlighting::).
‘HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE’
The default language used for syntax highlighting when there is no
language information.
‘IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME’
If set, spaces are ignored after an @-command that takes braces.
Default true, matching the TeX behavior.
‘INDEX_SPECIAL_CHARS_WARNING’
If set, warn about ‘:’ in index entry, as not all Info readers may
be able to process these. For Info and plaintext only. Default
false, because parsing problems there don't prevent navigation;
readers can still relatively easily find their way to the node in
question.
‘INFO_SPECIAL_CHARS_QUOTE’
If set, whenever there are problematic characters for Info output
in places such as node names or menu items, surround the part of
the construct where they appear with quoting characters, as
described in *note Info Format Specification::. Default is set for
Info and unset for plaintext. *Note Node Line Requirements::.
‘INFO_SPECIAL_CHARS_WARNING’
If set, warn about problematic constructs for Info output (such as
the string ‘::’) in node names, menu items, and cross-references.
If not defined, set unless ‘INFO_SPECIAL_CHARS_QUOTE’ is set.
Default is set for Info and not defined for plaintext. Similar
warnings in index entries are covered by
‘INDEX_SPECIAL_CHARS_WARNING’.
‘INPUT_FILE_NAME_ENCODING’
Encoding used for input file names. This variable overrides any
encoding from the document or current locale. Normally, you do not
need to set this variable, but it can be used if file names are in
a certain character encoding on a filesystem. An alternative is to
set ‘DOC_ENCODING_FOR_INPUT_FILE_NAME’ to ‘0’ to use the locale
encoding. See also ‘OUTPUT_FILE_NAME_ENCODING’.
‘LOCALE_ENCODING’
Locale encoding obtained from the system. You should not need to
explicitly set this variable.
‘MAX_MACRO_CALL_NESTING’
The maximal number of recursive calls of @-commands defined through
‘@rmacro’; default 100000. The purpose of this variable is to
avoid infinite recursions.
‘MESSAGE_ENCODING’
Encoding used to encode messages output by ‘texi2any’. Default is
based on the locale encoding.
It is also used for command-line argument passed to commands called
from ‘texi2any’. For example, ‘latex2html’ will be called from
‘texi2any’ if ‘HTML_MATH’ is set to ‘l2h’.
‘NO_TOP_NODE_OUTPUT’
If set do not output the Top node content. The Top node is still
parsed, but the content is discarded. Not set in the default case
for HTML. Set in the default case for EPUB. If ‘SHOW_TITLE’ is
‘undef’, setting ‘NO_TOP_NODE_OUTPUT’ also sets ‘SHOW_TITLE’ for
HTML.
Setting ‘NO_TOP_NODE_OUTPUT’, which removes the Top node and adds a
title page corresponds more to the formatting of a book. Setting
‘NO_TOP_NODE_OUTPUT’ to false, with ‘SHOW_TITLE’ remaining ‘undef’,
and false, corresponds more to a document setup for browsing, with
a direct access to the information at the Top node.
For DocBook, ‘NO_TOP_NODE_OUTPUT’ is set to true. Setting
‘NO_TOP_NODE_OUTPUT’ to false causes the Top node content to be
output. It is not recommended to output the Top node in DocBook as
the title and copying informations are always output. This option
is kept for DocBook for compatibility, as before 2022 the Top node
was output in DocBook. It could be removed in the future.
‘NO_USE_SETFILENAME’
If set, do not use ‘@setfilename’ to set the document name;
instead, base the output document name only on the input file name.
The default is false.
‘NODE_NAME_IN_MENU’
If set, use node names in menu entries, otherwise prefer section
names; default true.
‘OPEN_QUOTE_SYMBOL’
When an opening quote is needed, e.g., for ‘@samp’ output, use the
specified character; default ‘‘’ for DocBook. Undefined in
the default case in HTML and set to ‘‘’ if
‘USE_NUMERIC_ENTITY’ is not set, to ‘’’ if set, and to a
quote character if ‘OUTPUT_CHARACTERS’ is set and the output
encoding includes that character.
For Info, the default depends on the enabled document encoding. If
‘--disable-encoding’ is set or the document encoding is not UTF-8,
‘'’ is used. This character usually appears as an undirected
single quote on modern systems. Otherwise, the Info output uses a
Unicode left quote.
‘OPEN_DOUBLE_QUOTE_SYMBOL’
When an opening double quote is needed, for ‘@dfn’ output in Info,
use the specified character. If ‘--disable-encoding’ is set or the
document encoding is not UTF-8, ‘"’ is used. Otherwise, the Info
output uses a Unicode left double quote.
‘OUTPUT_CHARACTERS’
If not set, the default, output accented and special characters in
HTML, XML and DocBook using XML entities, and in LaTeX using
macros. If set, output accented characters in HTML, XML, DocBook
and LaTeX output and special characters in HTML and LaTeX output
based on the document encoding. *Note @documentencoding::, and
*note Inserting Accents::.
‘OUTPUT_ENCODING_NAME’
Normalized encoding name used for output files. Should be a usable
charset name in HTML, typically one of the preferred IANA encoding
names. By default, if an input encoding is set (typically through
‘@documentencoding’), this information is used to set the output
encoding name, otherwise the output encoding is based on the
default encoding. *Note @documentencoding::.
‘OUTPUT_FILE_NAME_ENCODING’
Encoding used for output file names. This variable overrides any
encoding from the document or current locale.
Normally, you do not need to set this variable, but it can be used
if file names should be created in a certain character encoding on
a filesystem. See also ‘INPUT_FILE_NAME_ENCODING’.
‘PACKAGE’
‘PACKAGE_VERSION’
‘PACKAGE_AND_VERSION’
‘PACKAGE_URL’
‘PACKAGE_NAME’
The implementation's short package name, package version, package
name and version concatenated, package URL, and full package name,
respectively. By default, these variables are all set through
Autoconf, Automake, and ‘configure’.
‘PREFIX’
The output file prefix, which is prepended to some output file
names. By default it is set by ‘@setfilename’ or from the input
file (*note Setting the Output File Name::). How this value is
used depends on the value of other customization variables or
command line options, such as whether the output is split. The
default is unset.
‘PROGRAM’
Name of the program used. By default, it is set to the name of the
program launched, with a trailing ‘.pl’ removed.
‘SORT_ELEMENT_COUNT’
If set, the name of a file to which a list of elements (nodes or
sections, depending on the output format) is dumped, sorted by the
number of lines they contain after removal of @-commands; default
unset. This is used by the program ‘texi-elements-by-size’ in the
‘util/’ directory of the Texinfo source distribution (*note
texi-elements-by-size::).
‘SORT_ELEMENT_COUNT_WORDS’
When dumping the elements-by-size file (see preceding item), use
word counts instead of line counts; default false.
‘TEST’
If set to true, some variables which are normally dynamically
generated anew for each run (date, program name, version) are set
to fixed and given values. This is useful to compare the output to
a reference file, as is done for the tests. The default is false.
‘TEXI2DVI’
Name of the command used to produce PostScript, PDF, and DVI;
default ‘texi2dvi’. *Note texi2any Printed Output::.
‘TEXI2HTML’
Generate HTML and try to be as compatible as possible with
‘texi2html’; default false.
‘TEXINFO_DTD_VERSION’
For XML. Version of the DTD used in the XML output preamble. The
default is set based on a variable in ‘configure.ac’.
‘TEXTCONTENT_COMMENT’
For stripped text content output (i.e., when
‘TEXINFO_OUTPUT_FORMAT’ is set to ‘textcontent’). If set, also
output comments. Default false.
‘TOP_NODE_UP’
Up node for the Top node; default ‘(dir)’. This node name is
supposed to be already formatted for the output format. In HTML
can be used in attribute, so should not contain any element. Used
for HTML output only if ‘TOP_NODE_UP_URL’ is set to override the
URL, see ‘TOP_NODE_UP_URL’ in *note HTML Customization Variables::.
‘TREE_TRANSFORMATIONS’
The associated value is a comma separated list of transformations
that can be applied to the Texinfo tree prior to outputting the
result. If more than one is specified, the ordering is irrelevant;
each is always applied at the necessary point during processing.
By default, the tree transformations
‘move_index_entries_after_items’ and
‘relate_index_entries_to_table_entries’ are executed for HTML and
DocBook output. Here's an example of updating the master menu in a
document:
texi2any \
-c TREE_TRANSFORMATIONS=regenerate_master_menu \
-c TEXINFO_OUTPUT_FORMAT=plaintexinfo \
mydoc.texi \
-o /tmp/out
(Caveat: Since ‘plaintexinfo’ output expands Texinfo macros and
conditionals, it's necessary to remove any such differences before
installing the updates in the original document. This may be
remedied in a future release.)
The following transformations are currently supported (many are
used in the ‘pod2texi’ utility distributed with Texinfo; *note
Invoking pod2texi::):
‘complete_tree_nodes_menus’
Add menu entries or whole menus for nodes associated with
sections of any level, based on the sectioning tree.
‘complete_tree_nodes_missing_menu’
Add whole menus for nodes associated with sections without
menu. The menus are based on the sectioning tree.
‘fill_gaps_in_sectioning’
Adds empty ‘@unnumbered...’ sections in a tree to fill gaps in
sectioning. For example, an ‘@unnumberedsec’ will be inserted
if a ‘@chapter’ is followed by a ‘@subsection’.
‘insert_nodes_for_sectioning_commands’
Insert nodes for sectioning commands lacking a corresponding
node.
‘move_index_entries_after_items’
In ‘@enumerate’ and ‘@itemize’, move index entries appearing
just before an ‘@item’ to just after the ‘@item’. Comment
lines between index entries are moved too. As mentioned, this
is always done for HTML and DocBook output.
‘regenerate_master_menu’
Update the Top node master menu, either replacing the (first)
‘@detailmenu’ in the Top node menu, or creating it at the end
of the Top node menu.
‘relate_index_entries_to_table_entries’
In ‘@table’, ‘@vtable’ and ‘@ftable’, reassociate the index
entry information from an index @-command appearing right
after an ‘@item’ line with the first element of the ‘@item’.
Remove the index @-command from the tree.
‘simple_menu’
Mostly the same as ‘SIMPLE_MENU’: use a simple preformatted
style for the menu. It differs from setting ‘SIMPLE_MENU’ in
that ‘SIMPLE_MENU’ only has an effect in HTML output.
‘USE_NODES’
Preferentially use nodes to decide where elements are separated.
If set to false, preferentially use sectioning to decide where
elements are separated. The default is true.
‘USE_NUMERIC_ENTITY’
For HTML, XML and DocBook. If set, use numeric entities instead of
named entities. By default, set to true for DocBook output.
‘USE_UP_NODE_FOR_ELEMENT_UP’
Fill in up sectioning direction with node direction when there is
no sectioning up direction. In practice this can only happen when
there is no @top section. Not set by default.
‘USE_SETFILENAME_EXTENSION’
Default is on for Info, off for other output. If set, use exactly
what ‘@setfilename’ gives for the output file name, including the
extension. You should not need to explicitly set this variable.
‘USE_UNIDECODE’
If set to false, do not use the ‘Text::Unidecode’ Perl module to
transliterate more characters; default true.
File: texinfo.info, Node: Internationalization of Document Strings, Next: Invoking pod2texi, Prev: Customization Variables, Up: Generic Translator texi2any
19.5 Internationalization of Document Strings
=============================================
‘texi2any’ writes fixed strings into the output document at various
places: cross-references, page footers, the help page, alternate text
for images, and so on. The string chosen depends on the value of the
‘documentlanguage’ at the time of the string being output (*note
@documentlanguage::, for the Texinfo command interface).
The Gettext framework is used for those strings (*note
(gettext)Top::). The ‘libintl-perl’ package is used as the ‘gettext’
implementation; more specifically, the pure Perl implementation is used,
so Texinfo can support consistent behavior across all platforms and
installations, which would not otherwise be possible. ‘libintl-perl’ is
included in the Texinfo distribution and always installed, to ensure
that it is available if needed. It is also possible to use the system
‘gettext’ (the choice can be made at build-time).
The Gettext domain ‘texinfo_document’ is used for the strings.
Translated strings are written as Texinfo, and may include @-commands.
In translated strings, the varying parts of the string are not usually
denoted by ‘%s’ and the like, but by ‘{arg_name}’. (This convention is
common for ‘gettext’ in Perl and is fully supported in GNU Gettext;
*note Perl Format Strings: (gettext)perl-format.) For example, in the
following, ‘{section}’ will be replaced by the section name:
see {section}
These Perl-style brace format strings are used for two reasons:
first, changing the order of ‘printf’ arguments is only available since
Perl 5.8.0; second, and more importantly, the order of arguments is
unpredictable, since @-command expansion may lead to different orders
depending on the output format.
The expansion of a translation string is done like this:
1. First, the string is translated. The locale is
DOCUMENTLANGUAGE‘.’DOCUMENTENCODING.
If the DOCUMENTLANGUAGE has the form ‘ll_CC’, that is tried first,
and then just ‘ll’.
To cope with the possibility of having multiple encodings, a
special use of the ‘us-ascii’ locale encoding is also possible. If
the ‘ll’ locale in the current encoding does not exist, and the
encoding is not ‘us-ascii’, then ‘us-ascii’ is tried.
The idea is that if there is a ‘us-ascii’ encoding, it means that
all the characters in the charset may be expressed as @-commands.
For example, there is a ‘fr.us-ascii’ locale that can accommodate
any encoding, since all the Latin 1 characters have associated
@-commands. On the other hand, Japanese has only a translation
‘ja.utf-8’, since there are no @-commands for Japanese characters.
The ‘us-ascii’ locales are not needed much now that UTF-8 is used
for most documents. Note that accented characters are required to
be expressed as @-commands in the ‘us-ascii’ locales, which may be
inconvenient for translators.
2. Next, the string is expanded as Texinfo, and converted. The
arguments are substituted; for example, ‘{arg_name}’ is replaced by
the corresponding actual argument.
In the following example, ‘{date}’, ‘{program_homepage}’ and
‘{program}’ are the arguments of the string. Since they are used in
‘@uref’, their order is not predictable. ‘{date}’, ‘{program_homepage}’
and ‘{program}’ are substituted after the expansion:
Generated on @emph{{date}} using
@uref{{program_homepage}, @emph{{program}}}.
This approach is admittedly a bit complicated. Its usefulness is
that it supports having translations available in different encodings
for encodings which can be covered by @-commands, and also specifying
how the formatting for some commands is done, independently of the
output format--yet still be language-dependent. For example, the
‘@pxref’ translation string can be like this:
see {node_file_href} section `{section}' in @cite{{book}}
which allows for specifying a string independently of the output format,
while nevertheless with rich formatting it may be translated
appropriately in many languages.
File: texinfo.info, Node: Invoking pod2texi, Next: texi2html, Prev: Internationalization of Document Strings, Up: Generic Translator texi2any
19.6 Invoking ‘pod2texi’: Convert Pod to Texinfo
================================================
The ‘pod2texi’ program translates Perl Pod documentation file(s) to
Texinfo. There are two basic modes of operation: generating a
standalone manual from each input Pod, or (if ‘--base-level=1’ or higher
is given) generating Texinfo subfiles suitable for use with ‘@include’.
The ‘pod2texi’ program may be useful outside of the rest of Texinfo;
thus, the invocation of ‘pod2texi’ is documented in the Pod language
using the man page format to follow the convention used in Perl
standalone programs, with a version on the web
<http://www.gnu.org/software/texinfo/manual/pod2texi.html> and a version
included below. The version included in the manual is also an example
of ‘pod2texi’ use, as it is converted from Pod using ‘pod2texi’.
* Menu:
* pod2texi manual page:: ‘pod2texi’ invocation in a manual page format.
File: texinfo.info, Node: pod2texi manual page, Up: Invoking pod2texi
19.6.1 pod2texi
---------------
pod2texi NAME
.............
pod2texi - convert Pod to Texinfo
pod2texi SYNOPSIS
.................
pod2texi [OPTION]... POD...
pod2texi DESCRIPTION
....................
Translate Pod file(s) to Texinfo. There are two basic modes of
operation. First, by default, each Pod is translated to a standalone
Texinfo manual.
Second, if ‘--base-level’ is set higher than 0, each Pod is
translated to a file suitable for ‘@include’, and one more file with a
main menu and all the ‘@include’ is generated.
pod2texi OPTIONS
................
*--appendix-sections*
Use appendix sectioning commands (‘@appendix’, ...) instead of the
default numbered sectioning Texinfo @-commands (‘@chapter’,
‘@section’, ...).
*--base-level*=_NUM|NAME_
Sets the level of the ‘head1’ commands. It may be an integer or a
Texinfo sectioning command (without the ‘@’): 1 corresponds to the
‘@chapter’/‘@unnumbered’ level, 2 to the ‘@section’ level, and so
on. The default is 0, meaning that ‘head1’ commands are still
output as chapters, but the output is arranged as a standalone
manual.
If the level is not 0, the Pod file is rendered as a fragment of a
Texinfo manual suitable for ‘@include’. In this case, each Pod
file has an additional sectioning command covering the entire file,
one level above the ‘--base-level’ value. Therefore, to make each
Pod file a chapter in a large manual, you should use ‘section’ as
the base level.
For an example of making Texinfo out of the Perl documentation
itself, see ‘contrib/perldoc-all’ in the Texinfo source
distribution.
*--debug*=_NUM_
Set debugging level to _NUM_.
*--headings-as-sections*
Use headings commands (‘@heading’, ...) instead of the default
numbered sectioning Texinfo @-commands (‘@chapter’, ‘@section’,
...). The sectioning command covering the entire file output for
each Pod file if *--base-level* is not 0 is a numbered command.
*--help*
Display help and exit.
*--menus*
Output node menus. If there is a main manual, its Top node menu is
always output, since a master menu is generated. Other nodes menus
are not output in the default case.
*--output*=_NAME_
Name for the first manual, or the main manual if there is a main
manual. Default is to write to standard output.
*--no-section-nodes*
Use anchors for sections instead of nodes.
*--no-fill-section-gaps*
Do not fill sectioning gaps with empty ‘@unnumbered’ files.
Ordinarily, it's good to keep the sectioning hierarchy intact.
*--preamble*=_STR_
Insert _STR_ as top boilerplate before menu and includes. If _STR_
is set to ‘-’, read the top boilerplate from the standard input.
The default top boilerplate is a minimal beginning for a Texinfo
document.
*--setfilename*=_STR_
Use _STR_ in top boilerplate before menu and includes for
‘@setfilename’. No ‘@setfilename’ is output in the default case.
*--subdir*=_NAME_
If there is a main manual with include files (each corresponding to
an input Pod file), then those include files are put in directory
_NAME_.
*--unnumbered-sections*
Use unnumbered sectioning commands (‘@unnumbered’, ...) instead of
the default numbered sectioning Texinfo @-commands (‘@chapter’,
‘@section’, ...).
*--top*=_TOP_
Name of the ‘@top’ element for the main manual. May contain
Texinfo code.
*--version*
Display version information and exit.
pod2texi SEE ALSO
.................
*note (Pod-Simple-Texinfo)::. *note (perlpod)::. The Texinfo manual.
Texinfo home page: <http://www.gnu.org/software/texinfo/>
pod2texi COPYRIGHT AND LICENSE
..............................
Copyright 2012-2023 Free Software Foundation, Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.
There is NO WARRANTY, to the extent permitted by law.
pod2texi AUTHOR
...............
Patrice Dumas <bug-texinfo@gnu.org>.
File: texinfo.info, Node: texi2html, Prev: Invoking pod2texi, Up: Generic Translator texi2any
19.7 ‘texi2html’: Ancestor of ‘texi2any’
========================================
Conceptually, the ‘texi2html’ program is the parent of today's
‘texi2any’ program. ‘texi2html’ was developed independently, originally
by Lionel Cons in 1998; at the time, ‘makeinfo’ could not generate HTML.
Many other people contributed to ‘texi2html’ over the years.
The present ‘texi2any’ uses little of the actual code of ‘texi2html’,
and has quite a different basic approach to the implementation (namely,
parsing the Texinfo document into a tree), but still, there is a family
resemblance.
By design, ‘texi2any’ supports nearly all the features of ‘texi2html’
in some way. However, we did not attempt to maintain strict
compatibility, so no ‘texi2html’ executable is installed by the Texinfo
package. An approximation can be run with an invocation like this:
texi2any --set-customization-variable TEXI2HTML=1 ...
but, to emphasize, this is _not_ a drop-in replacement for the previous
‘texi2html’. Here are the biggest differences:
• Most blatantly, the command line options of ‘texi2html’ are now
customization variables, for the most part. A table of approximate
equivalents is given below.
• The program-level customization API is very different in
‘texi2any’.
• Indices cannot be split.
We do not intend to reimplement these differences. Therefore, the
route forward for authors is alter manuals and build processes as
necessary to use the new features and methods of ‘texi2any’. The
‘texi2html’ maintainers (one of whom is the principal author of
‘texi2any’) do not intend to make further releases.
Here is the table showing ‘texi2html’ options and corresponding
‘texi2any’ customization variables.
‘--toc-links’ ‘TOC_LINKS’
‘--short-ext’ ‘EXTENSION’ set to ‘htm’
‘--prefix’ ‘PREFIX’
‘--def-table’ ‘DEF_TABLE’
‘--html-xref-prefix’ ‘EXTERNAL_DIR’
‘--l2h’ ‘HTML_MATH’ set to ‘l2h’
‘--l2h-l2h’ ‘L2H_L2H’
‘--l2h-skip’ ‘L2H_SKIP’
‘--l2h-tmp’ ‘L2H_TMP’
‘--l2h-file’ ‘L2H_FILE’
‘--l2h-clean’ ‘L2H_CLEAN’
‘--use-nodes’ ‘USE_NODES’
‘--monolithic’ ‘MONOLITHIC’
‘--top-file’ ‘TOP_FILE’
‘--frames’ ‘FRAMES’
‘--menu’ ‘FORMAT_MENU’
‘--debug’ ‘DEBUG’
‘--doctype’ ‘DOCTYPE’
‘--frameset-doctype’ ‘FRAMESET_DOCTYPE’
‘--test’ ‘TEST’
Finally, any ‘texi2html’ users seeking more detailed information can
check the first part of the archived file ‘doc/texi2oldapi.texi’ in the
Texinfo source repository.
File: texinfo.info, Node: Creating and Installing Info Files, Next: Generating HTML, Prev: Generic Translator texi2any, Up: Top
20 Creating and Installing Info Files
*************************************
This chapter gives some information on the Info output and describes how
to install Info files. For the creation of Info files with ‘texi2any’,
see *note Generic Translator texi2any::, and with Emacs, *note Info
Formatting::. *Note Info Files::, for general information about the
file format. *Note Info Format Specification::, for a detailed
technical specification of the Info format.
* Menu:
* Installing an Info File::
* Tag and Split Files::
* Info Format FAQ::
File: texinfo.info, Node: Installing an Info File, Next: Tag and Split Files, Up: Creating and Installing Info Files
20.1 Installing an Info File
============================
Info files are usually kept in the ‘info’ directory. You can read Info
files using the standalone Info program or the Info reader built into
Emacs. (*Note (info)Top::, for an introduction to Info.)
* Menu:
* Directory File:: The top-level menu for all Info files.
* New Info File:: Listing a new Info file.
* Other Info Directories:: How to specify Info files that are located in
other directories.
* Installing Dir Entries:: How to specify what menu entry to add to the
Info directory.
* Invoking install-info:: ‘install-info’ options.
File: texinfo.info, Node: Directory File, Next: New Info File, Up: Installing an Info File
20.1.1 The Directory File ‘dir’
-------------------------------
For Info to work, the ‘info’ directory must contain a file that serves
as a top-level directory for the Info system. By convention, this file
is called ‘dir’. (You can find the location of this file within Emacs
by typing ‘C-h i’ to enter Info and then typing ‘C-x C-f’ to see the
location of the ‘info’ directory.)
The ‘dir’ file is itself an Info file. It contains the top-level
menu for all the Info files in the system. The menu looks like this:
* Menu:
* Info: (info). Documentation browsing system.
* Emacs: (emacs). The extensible, self-documenting
text editor.
* Texinfo: (texinfo). With one source file, make
either a printed manual using
@TeX{} or an Info file.
...
Each of these menu entries points to the 'Top' node of the Info file
that is named in parentheses. (The menu entry does not need to specify
the 'Top' node, since Info goes to the 'Top' node if no node name is
mentioned. *Note Nodes in Other Info Files: Other Info Files.)
Thus, the ‘Info’ entry points to the 'Top' node of the ‘info’ file
and the ‘Emacs’ entry points to the 'Top' node of the ‘emacs’ file.
In each of the Info files, the 'Up' pointer of the 'Top' node refers
back to the ‘dir’ file. For example, the line for the 'Top' node of the
Emacs manual looks like this in Info:
File: emacs Node: Top, Up: (DIR), Next: Distrib
In this case, the ‘dir’ file name is written in uppercase letters--it
can be written in either upper- or lowercase. This is not true in
general, it is a special case for ‘dir’.
See the ‘util/dir-example’ file in the Texinfo distribution for a
large sample ‘dir’ file.
File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory File, Up: Installing an Info File
20.1.2 Listing a New Info File
------------------------------
To add a new Info file to your system, you must write a menu entry to
add to the menu in the ‘dir’ file in the ‘info’ directory. For example,
if you were adding documentation for GDB, you would write the following
new entry:
* GDB: (gdb). The source-level C debugger.
The first part of the menu entry is the menu entry name, followed by a
colon. The second part is the name of the Info file, in parentheses,
followed by a period. The third part is the description.
The name of an Info file often has a ‘.info’ extension. Thus, the
Info file for GDB might be called either ‘gdb’ or ‘gdb.info’. The Info
reader programs automatically try the file name both with and without
‘.info’(1); so it is better to avoid clutter and not to write ‘.info’
explicitly in the menu entry. For example, the GDB menu entry should
use just ‘gdb’ for the file name, not ‘gdb.info’.
---------- Footnotes ----------
(1) On MS-DOS/MS-Windows systems, Info will try the ‘.inf’ extension
as well.
File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Installing an Info File
20.1.3 Info Files in Other Directories
--------------------------------------
If an Info file is not in the ‘info’ directory, there are three ways to
specify its location:
1. Write the file name in the ‘dir’ file as the second part of the
menu.
2. Specify the Info directory name in the ‘INFOPATH’ environment
variable in your ‘.profile’ or ‘.cshrc’ initialization file. (Only
you and others who set this environment variable will be able to
find Info files whose location is specified this way.)
3. If you are using Emacs, list the name of the file in a second ‘dir’
file, in its directory; and then add the name of that directory to
the ‘Info-directory-list’ variable in your personal or site
initialization file.
This variable tells Emacs where to look for ‘dir’ files (the files
must be named ‘dir’). Emacs merges the files named ‘dir’ from each
of the listed directories. (In Emacs version 18, you can set the
‘Info-directory’ variable to the name of only one directory.)
For example, to reach a test file in the ‘/home/bob/info’ directory,
you could add an entry like this to the menu in the standard ‘dir’ file:
* Test: (/home/bob/info/info-test). Bob's own test file.
In this case, the absolute file name of the ‘info-test’ file is written
as the second part of the menu entry.
If you don't want to edit the system ‘dir’ file, you can tell Info
where to look by setting the ‘INFOPATH’ environment variable in your
shell startup file. This works with both the Emacs and standalone Info
readers.
Emacs uses the ‘INFOPATH’ environment variable to initialize the
value of Emacs's own ‘Info-directory-list’ variable. The standalone
Info reader merges any files named ‘dir’ in any directory listed in the
‘INFOPATH’ variable into a single menu presented to you in the node
called ‘(dir)Top’.
However you set ‘INFOPATH’, if its last character is a colon (on
MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced by
the default (compiled-in) path. This gives you a way to augment the
default path with new directories without having to list all the
standard places. For example (using ‘sh’ syntax):
INFOPATH=/home/bob/info:
export INFOPATH
will search ‘/home/bob/info’ first, then the standard directories.
Leading or doubled colons are not treated specially.
When you create your own ‘dir’ file for use with
‘Info-directory-list’ or ‘INFOPATH’, it's easiest to start by copying an
existing ‘dir’ file and replace all the text after the ‘* Menu:’ with
your desired entries. That way, the punctuation and special ‘CTRL-_’
characters that Info needs will be present.
As one final alternative, which works only with Emacs Info, you can
change the ‘Info-directory-list’ variable. For example:
(add-hook 'Info-mode-hook '(lambda ()
(add-to-list 'Info-directory-list
(expand-file-name "~/info"))))
File: texinfo.info, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Installing an Info File
20.1.4 Installing Info Directory Files
--------------------------------------
When you install an Info file onto your system, you can use the program
‘install-info’ to update the Info directory file ‘dir’. Normally the
makefile for the package runs ‘install-info’, just after copying the
Info file into its proper installed location.
In order for the Info file to work with ‘install-info’, you include
the commands ‘@dircategory’ and ‘@direntry’...‘@end direntry’ in the
Texinfo source file. Use ‘@direntry’ to specify the menu entries to add
to the Info directory file. Use ‘@dircategory’ to specify a category
for the manual, which determines which part of the Info directory to put
it in. *Note Directory Category::.
Here is how these commands are used in this manual:
@dircategory Texinfo documentation system
@direntry
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
@end direntry
Here's what this produces in the Info file:
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* Texinfo: (texinfo). The GNU documentation format.
* install-info: (texinfo)Invoking install-info. ...
...
END-INFO-DIR-ENTRY
The ‘install-info’ program sees these lines in the Info file, and that
is how it knows what to do.
Always use the ‘@direntry’ and ‘@dircategory’ commands near the
beginning of the Texinfo input, before the first ‘@node’ command. If
you use them later on in the input, ‘install-info’ will not notice them.
‘install-info’ will automatically reformat the description of the
menu entries it is adding. As a matter of convention, the description
of the main entry (above, ‘The GNU documentation format’) should start
at column 32, starting at zero (as in ‘what-cursor-position’ in Emacs).
This will make it align with most others. Description for individual
utilities best start in column 48, where possible. For more information
about formatting see the ‘--calign’, ‘--align’, and ‘--max-width’
options in *note Invoking install-info::.
If you use ‘@dircategory’ more than once in the Texinfo source, each
usage specifies the 'current' category; any subsequent ‘@direntry’
commands will add to that category.
Each 'Invoking' node for every program installed should have a
corresponding ‘@direntry’. This lets users easily find the
documentation for the different programs they can run, as with the
traditional ‘man’ system.
File: texinfo.info, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Installing an Info File
20.1.5 Invoking ‘install-info’
------------------------------
‘install-info’ inserts menu entries from an Info file into the top-level
‘dir’ file in the Info system (see the previous sections for an
explanation of how the ‘dir’ file works). ‘install-info’ also removes
menu entries from the ‘dir’ file. It's most often run as part of
software installation, or when constructing a ‘dir’ file for all manuals
on a system. Synopsis:
install-info [OPTION...] [INFO-FILE [DIR-FILE]]
If INFO-FILE or DIR-FILE are not specified, the options (described
below) that define them must be. There are no compile-time defaults,
and standard input is never used. ‘install-info’ can read only one Info
file and write only one ‘dir’ file per invocation.
If DIR-FILE (however specified) does not exist, ‘install-info’
creates it if possible (with no entries).
If any input file is compressed with ‘gzip’ (*note (gzip)Top::),
‘install-info’ automatically uncompresses it for reading. And if
DIR-FILE is compressed, ‘install-info’ also automatically leaves it
compressed after writing any changes. If DIR-FILE itself does not
exist, ‘install-info’ tries to open ‘DIR-FILE.gz’, ‘DIR-FILE.xz’,
‘DIR-FILE.bz2’, ‘DIR-FILE.lz’, and ‘DIR-FILE.lzma’, in that order.
Options:
‘--add-once’
Specifies that the entry or entries will only be put into a single
section.
‘--align=COLUMN’
Specifies the column that the second and subsequent lines of menu
entry's description will be formatted to begin at. The default for
this option is ‘35’. It is used in conjunction with the
‘--max-width’ option. COLUMN starts counting at 1.
‘--append-new-sections’
Instead of alphabetizing new sections, place them at the end of the
DIR file.
‘--calign=COLUMN’
Specifies the column that the first line of menu entry's
description will be formatted to begin at. The default for this
option is ‘33’. It is used in conjunction with the ‘--max-width’
option. When the name of the menu entry exceeds this column,
entry's description will start on the following line. COLUMN
starts counting at 1.
‘--debug’
Report what is being done.
‘--delete’
Delete the entries in INFO-FILE from DIR-FILE. The file name in
the entry in DIR-FILE must be INFO-FILE (except for an optional
‘.info’ in either one). Don't insert any new entries. Any empty
sections that result from the removal are also removed.
‘--description=TEXT’
Specify the explanatory portion of the menu entry. If you don't
specify a description (either via ‘--entry’, ‘--item’ or this
option), the description is taken from the Info file itself.
‘--dir-file=NAME’
Specify file name of the Info directory file. This is equivalent
to using the DIR-FILE argument.
‘--dry-run’
Same as ‘--test’.
‘--entry=TEXT’
Insert TEXT as an Info directory entry; TEXT should have the form
of an Info menu item line plus zero or more extra lines starting
with whitespace. If you specify more than one entry, they are all
added. If you don't specify any entries, they are determined from
information in the Info file itself.
‘--help’
Display a usage message with basic usage and all available options,
then exit successfully.
‘--info-file=FILE’
Specify Info file to install in the directory. This is equivalent
to using the INFO-FILE argument.
‘--info-dir=DIR’
Specify the directory where the directory file ‘dir’ resides.
Equivalent to ‘--dir-file=DIR/dir’.
‘--infodir=DIR’
Same as ‘--info-dir’.
‘--item=TEXT’
Same as ‘--entry=TEXT’. An Info directory entry is actually a menu
item.
‘--keep-old’
Do not replace pre-existing menu entries. When ‘--remove’ is
specified, this option means that empty sections are not removed.
‘--max-width=COLUMN’
Specifies the column that the menu entry's description will be
word-wrapped at. COLUMN starts counting at 1.
‘--maxwidth=COLUMN’
Same as ‘--max-width’.
‘--menuentry=TEXT’
Same as ‘--name’.
‘--name=TEXT’
Specify the name portion of the menu entry. If the TEXT does not
start with an asterisk ‘*’, it is presumed to be the text after the
‘*’ and before the parentheses that specify the Info file.
Otherwise TEXT is taken verbatim, and is taken as defining the text
up to and including the first period (a space is appended if
necessary). If you don't specify the name (either via ‘--entry’,
‘--item’ or this option), it is taken from the Info file itself.
If the Info does not contain the name, the basename of the Info
file is used.
‘--no-indent’
Suppress formatting of new entries into the ‘dir’ file.
‘--quiet’
‘--silent’
Suppress warnings, etc., for silent operation.
‘--remove’
Same as ‘--delete’.
‘--remove-exactly’
Also like ‘--delete’, but only entries if the Info file name
matches exactly; ‘.info’ and/or ‘.gz’ suffixes are _not_ ignored.
‘--section=SEC’
Put this file's entries in section SEC of the directory. If you
specify more than one section, all the entries are added in each of
the sections. If you don't specify any sections, they are
determined from information in the Info file itself. If the Info
file doesn't specify a section, the menu entries are put into the
Miscellaneous section.
‘--section REGEX SEC’
Same as ‘--regex=REGEX --section=SEC --add-once’.
‘install-info’ tries to detect when this alternate syntax is used,
but does not always guess correctly. Here is the heuristic that
‘install-info’ uses:
1. If the second argument to ‘--section’ starts with a hyphen,
the original syntax is presumed.
2. If the second argument to ‘--section’ is a file that can be
opened, the original syntax is presumed.
3. Otherwise the alternate syntax is used.
When the heuristic fails because your section title starts with a
hyphen, or it happens to be a file that can be opened, the syntax
should be changed to ‘--regex=REGEX --section=SEC --add-once’.
‘--regex=REGEX’
Put this file's entries into any section that matches REGEX. If
more than one section matches, all of the entries are added in each
of the sections. Specify REGEX using basic regular expression
syntax, more or less as used with ‘grep’, for example.
‘--test’
Suppress updating of the directory file.
‘--version’
Display version information and exit successfully.
File: texinfo.info, Node: Tag and Split Files, Next: Info Format FAQ, Prev: Installing an Info File, Up: Creating and Installing Info Files
20.2 Tag Files and Split Files
==============================
Info files always contain a “tag table”, to be able to jump to nodes
quickly. Info files can be “nonsplit” (also called “unsplit”) or
“split”.
If the Info file contains less than about 300,000 characters the file
should be nonsplit. In that case, the tag table should appear at the
end of the Info file. If the Texinfo file contains more than about
300,000 characters, Texinfo processors split the large Info file into
shorter “indirect” subfiles of about 300,000 characters each. With
‘texi2any’, splitting may be prevented by ‘--no-split’, and the default
size of 300,000 characters may be modified with ‘--split-size’ (*note
Invoking texi2any::).
When a file is split, Info itself makes use of a shortened version of
the original file that contains just the tag table and references to the
files that were split off. The split-off files are called “indirect”
files.
The split-off files have names that are created by appending ‘-1’,
‘-2’, ‘-3’ and so on to the output file name, specified by the
‘@setfilename’ command or the input file name. The shortened version of
the original file continues to have the name specified by ‘@setfilename’
or the input file name.
At one stage in writing this document, for example, the Info file was
saved as the file ‘test-texinfo’ and that file looked like this:
Info file: test-texinfo, -*-Text-*-
produced by texinfo-format-buffer
from file: new-texinfo-manual.texinfo
^_
Indirect:
test-texinfo-1: 102
test-texinfo-2: 50422
test-texinfo-3: 101300
^_^L
Tag table:
(Indirect)
Node: overview^?104
Node: info file^?1271
Node: printed manual^?4853
Node: conventions^?6855
...
(But ‘test-texinfo’ had far more nodes than are shown here.) Each of
the split-off, indirect files, ‘test-texinfo-1’, ‘test-texinfo-2’, and
‘test-texinfo-3’, is listed in this file after the line that says
‘Indirect:’. The tag table is listed after the line that says ‘Tag
table:’.
In the list of indirect files, the number following the file name
records the cumulative number of bytes in the preceding indirect files,
not counting the file list itself, the tag table, or any permissions
text in the first file. In the tag table, the number following the node
name records the location of the beginning of the node, in bytes from
the beginning of the (unsplit) output.
If you are using ‘texinfo-format-buffer’ to create Info files, you
may want to run the ‘Info-validate’ command. (The ‘texi2any’ command
does such a good job on its own, you do not need ‘Info-validate’.)
However, you cannot run the ‘M-x Info-validate’ node-checking command on
indirect files. For information on how to prevent files from being
split with ‘texinfo-format-buffer’ and how to validate the structure of
the nodes, see *note Using Info-validate::.
File: texinfo.info, Node: Info Format FAQ, Prev: Tag and Split Files, Up: Creating and Installing Info Files
20.3 Info Format FAQ
====================
Here are some questions that have been frequently asked on the project
mailing lists and elsewhere.
Why when I run ‘info FOO’ do I get the same output as ‘man FOO’?
Check that the Info manuals are installed. Not all GNU/Linux
distributions install all the Info manuals by default. This is
regrettable, as often the Info manual provides more information
than the provided man page.
Why not use HTML instead of Info?
Manuals are rarely written in the Info format itself, but are
generated from Texinfo source by the ‘texi2any’ program.
‘texi2any’ can generate HTML as well as Info from Texinfo source.
You can also access and download HTML manuals from the GNU website
(<https://www.gnu.org/manual/manual.html>). Additionally, some
GNU/Linux distributions provide packages for the installation of
HTML manuals.
Info still has some advantages over HTML for locally installed
documentation. The Info browsers support index lookup and support
for links between locally installed manuals in multiple locations.
It's important to have documentation installed locally on your
machine rather than relying on the Internet; this makes accessing
documentation more reliable, and ensures it matches installed
versions of packages. It's hoped that support for browsing locally
installed Texinfo documentation in some form of HTML can be
improved in the future.
Why provide the command-line ‘info’ program when the Emacs Info reader is better?
The Emacs Info reader can display images, and fully supports using
a mouse. There are not many differences among the Info readers
besides that. Command-line ‘info’ can be configured to change the
default key bindings, as well as change the color of
cross-references and search results, and to enable mouse scrolling
support. You should not need to be experienced with the Emacs
editor to use ‘info’. (Some recommend another program called
‘pinfo’, but this lacks in important features like index lookup.)
Some prefer to be able to scroll through the entire manual at once
(as happens with man pages), rather than being limited to a single
'node' of content at once. Of course, there is no accounting for
taste, but a single, unstructured block of text becomes more
awkward as a manual becomes longer and more complicated. (However,
if you really want to, you can view an info manual all at once in
the ‘less’ pager with ‘info FOO | less’.)
Why do I have 'see' appearing in front of all of my links?
By default, Emacs Info mode either changes the marker ‘*note’ for
cross-references to 'see', or hides it completely. Command-line
‘info’ does the same if ‘hide-note-references’ is set.
Unfortunately, there is no way to do this reliably, as both the
‘@pxref’ and ‘@ref’ commands in Texinfo output this marker in the
Info output, and the 'see' text is only appropriate for ‘@pxref’.
Yes, but how do I get a plain link, with no extra markup?
You can't. Info is a plain text format that is displayed mostly
as-is in the viewers, and without the ‘*note’ text there would be
nothing to mark text as a link.
For output formats such as HTML, you can use the ‘@link’ command to
produce a plain link. *Note @link::. This does not produce a
working cross-reference in Info output or in a printed copy of the
manual, though.
Why do lines containing links appear mysteriously short?
This due to Emacs (or ‘info’ with ‘hide-note-references’ set to
‘On’) hiding ‘*note’ strings, as mentioned above.
Can the Info format be extended to support fonts, colors or reflowable text?
Any extension would be incompatible with existing Info-viewing
programs. Extra markup added to Info files would be displayed to
the user, making files ugly and unreadable.
When Texinfo files are processed into Info files, information about
which Texinfo commands were used to markup text is lost. Moreover,
it is not possible to reliably detect whether text can be reflowed
(e.g. a paragraph of prose), or whether line breaks should be kept
(e.g. a code sample, or poem).
Info's core purpose is to display documentation on text terminals.
If you want more, you are recommended to use the HTML output from
‘texi2any’ instead.
File: texinfo.info, Node: Generating HTML, Next: @-Command Details, Prev: Creating and Installing Info Files, Up: Top
21 Generating HTML
******************
‘texi2any’ generates Info output by default, but given the ‘--html’
option, it will generate HTML, for web browsers and other programs.
This chapter gives some details on such HTML output.
‘texi2any’ has many user-definable customization variables with which
you can influence the HTML output. *Note Customization Variables::. In
particular, there is support for syntax highlighting in ‘@example’
(*note Syntax Highlighting::). You can also write so-called
“initialization files”, or “init files” for short, to modify almost
every aspect of HTML output formatting. Initialization files contain
code and are loaded by ‘--init-file’ (*note Invoking texi2any::).
Some initialization files are maintained with Texinfo and installed
in the default case. For example, ‘chm.pm’ produces the intermediate
compressed HTML Help format files that can be subsequently converted to
the CHM format.
The documentation of ‘texi2any’ HTML output adaptation using
customization files is in a separate manual. *Note (texi2any_api)::.
* Menu:
* HTML Translation:: Details of the HTML output.
* HTML Splitting:: How HTML output is split.
* HTML CSS:: Influencing HTML output with Cascading Style
Sheets.
* @documentdescription:: Document summary for the HTML output.
* Generating EPUB:: Details on the EPUB output.
* Syntax Highlighting::
* HTML Xref::
File: texinfo.info, Node: HTML Translation, Next: HTML Splitting, Up: Generating HTML
21.1 HTML Translation
=====================
The HTML generated by ‘texi2any’ generates standard HTML output. The
output is intentionally quite plain for maximum portability and
accessibility.
You can customize the output via CSS (*note HTML CSS::) or other
means (*note Customization Variables::). If you cannot accomplish a
reasonable customization, feel free to report that.
*Navigation bar:* By default, a navigation bar is inserted at the
start of each node, analogous to Info output. If the ‘--no-headers’
option is used, the navigation bar is only inserted at the beginning of
split files. Header ‘<link>’ elements in split output support Info-like
navigation with browsers which implement this feature.
*Raw HTML*: ‘texi2any’ will include segments of Texinfo source
between ‘@ifhtml’ and ‘@end ifhtml’ in the HTML output (but not any of
the other conditionals, by default). Source between ‘@html’ and ‘@end
html’ is passed without change to the output (i.e., suppressing the
normal escaping of input ‘<’, ‘>’ and ‘&’ characters which have special
significance in HTML). *Note Conditional Commands::.
*Standards*: It is intentionally not our goal, and not even always
possible, to pass through every conceivable validation test without any
diagnostics. Different validation tests have different goals, often
about pedantic enforcement of some standard or another. Our overriding
goal is to help users, not blindly comply with standards.
Please report output from an error-free run of ‘texi2any’ which has
_practical_ browser or EPUB reader portability problems as a bug (*note
Reporting Bugs::).
In practice, the HTML produced by ‘texi2any’ is slowly adjusted over
time towards the latest HTML standard, while also trying to keep
compatibility with earlier produced HTML. We use transitional markup and
try to be slow enough to give time for the diverse HTML readers to
adjust (and for standards to reincorporate useful features that were
dropped...).
File: texinfo.info, Node: HTML Splitting, Next: HTML CSS, Prev: HTML Translation, Up: Generating HTML
21.2 HTML Splitting
===================
When splitting output at nodes (which is the default), ‘texi2any’ writes
HTML output into (basically) one output file per Texinfo source ‘@node’.
Each output file name is the node name with spaces replaced by ‘-’'s
and special characters changed to ‘_’ followed by their code point in
hex (*note HTML Xref::). This is to make it portable and easy to use as
a file name. In the unusual case of two different nodes having the same
name after this treatment, they are written consecutively to the same
file, with HTML anchors so each can be referred to independently.
If ‘texi2any’ is run on a system which does not distinguish case in
file names, nodes which are the same except for case (e.g., ‘index’ and
‘Index’) will also be folded into the same output file with anchors.
You can also pretend to be on a case insensitive filesystem by setting
the customization variable ‘CASE_INSENSITIVE_FILENAMES’.
It is also possible to split at chapters or sections with ‘--split’
(*note Invoking texi2any::). In that case, the file names are
constructed after the name of the node associated with the relevant
sectioning command. Also, unless ‘--no-node-files’ is specified, a
redirection file is output for every node in order to more reliably
support cross-references to that manual (*note HTML Xref::).
When splitting, the HTML output files are written into a
subdirectory. The subdirectory name is derived from the base name (that
is, any extension is removed), with ‘_html’ postpended. For example,
HTML output for ‘gcc.texi’ would be written into a subdirectory named
‘gcc_html/’. The subdirectory name is based on ‘@setfilename’ or on the
input file name (*note Setting the Output File Name::).
In any case, the top-level output file within the directory is always
named ‘index.html’.
Monolithic output (‘--no-split’) is named according to
‘@setfilename’, if present (with any ‘.info’ extension replaced with
‘.html’), ‘--output’ (the argument is used literally), or based on the
input file name as a last resort (*note Setting the Output File Name::).
File: texinfo.info, Node: HTML CSS, Next: @documentdescription, Prev: HTML Splitting, Up: Generating HTML
21.3 HTML CSS
=============
Cascading Style Sheets (CSS) is an Internet standard for influencing the
display of HTML documents: see <http://www.w3.org/Style/CSS/>.
By default, some CSS code is included to better implement the
appearance of some Texinfo environments. For example:
pre.display { font-family:inherit }
The above tells the web browser to use the same font as the main
document inside ‘<pre>’ elements used for ‘@display’ environments. By
default, the HTML ‘<pre>’ command uses a monospaced font.
Please see the reference above for a full explanation of CSS.
You can influence the CSS in the HTML output with two ‘texi2any’
options: ‘--css-include=FILE’ and ‘--css-ref=URL’.
The option ‘--css-ref=URL’ adds to each output HTML file a ‘<link>’
tag referencing a CSS at the given URL. This allows using external
style sheets.
The option ‘--css-include=FILE’ includes the contents FILE in the
HTML output, as you might expect. However, the details are somewhat
tricky, as described in the following, to provide maximum flexibility.
The CSS file first line may be a ‘@charset’ directive. If present,
this directive is used to determine the encoding of the CSS file. The
line is not copied into the output.
The CSS file may begin with so-called ‘@import’ directives, which
link to external CSS specifications for browsers to use when
interpreting the document. Again, a full description is beyond our
scope here, but we'll describe how they work syntactically, so we can
explain how they are handled.
There can be more than one ‘@import’, but they have to come first in
the file, with only whitespace and comments interspersed, no normal
definitions. Comments in CSS files are delimited by ‘/* ... */’, as in
C. An ‘@import’ directive must be in one of these two forms:
@import url(http://example.org/foo.css);
@import "http://example.net/bar.css";
The crucial characters are the ‘@’ at the beginning and the semicolon
terminating the directive. When reading the CSS file, any such
‘@’-directive is simply copied into the output, as follows:
• If FILE contains only normal CSS declarations, it is included after
the default CSS, thus overriding it.
• If FILE begins with ‘@import’ specifications (see below), then the
‘import’'s are included first (they have to come first, according
to the standard), and then the default CSS is included. If you
need to override the default CSS from an ‘@import’, you can do so
with the ‘! important’ CSS construct, as in:
pre.example { font-size: inherit ! important }
• If FILE contains both ‘@import’ and inline CSS specifications, the
‘@import’'s are included first, then default CSS, and lastly the
inline CSS from FILE.
• Any @-directive other than ‘@import’ and ‘@charset’ is treated as a
CSS declaration, meaning the default CSS is included and then the
rest of the file is prepended.
If the CSS file is malformed or erroneous, the output is unspecified.
The meaning of the CSS file is not interpreted in any way; the special
‘@’ and ‘;’ characters are looked for the text is blindly copied into
the output. Comments in the CSS file may or may not be included in the
output.
In addition to the possibilities offered by CSS, ‘texi2any’ has many
user-definable customization variables with which you can influence the
HTML output. *Note Customization Variables::.
File: texinfo.info, Node: @documentdescription, Next: Generating EPUB, Prev: HTML CSS, Up: Generating HTML
21.4 ‘@documentdescription’: Summary Text
=========================================
When producing HTML output for a document, a ‘<meta>’ element is written
in the ‘<head>’ to give some idea of the content of the document. By
default, this “description” is the title of the document, taken from the
‘@settitle’ command (*note @settitle::). To change this, use the
‘@documentdescription’ environment, as in:
@documentdescription
descriptive text.
@end documentdescription
This will produce the following output in the ‘<head>’ of the HTML:
<meta name=description content="descriptive text.">
File: texinfo.info, Node: Generating EPUB, Next: Syntax Highlighting, Prev: @documentdescription, Up: Generating HTML
21.5 Generating EPUB
====================
EPUB is a format designed for reading electronic books on portable
devices. ‘texi2any’ generated EPUB 3.2 in 2022. An EPUB file is a ZIP
archive container, holding informative files as well as the manual
rendered in HTML.
The generation of the EPUB file depends on the ‘Archive::Zip’ Perl
module being installed. This dependency is checked at runtime. In the
default case, trying to output EPUB without this dependency raises an
error. However, if the EPUB output file is not generated, with the
customization variable ‘EPUB_CREATE_CONTAINER_FILE’ set to 0, it is not
an error if ‘Archive::Zip’ is not installed.
The ‘texi2any’ tests related to EPUB generation do not require the
installation of ‘Archive::Zip’, as they set ‘EPUB_CREATE_CONTAINER_FILE’
to 0 and keep the directory containing the files and directories needed
for the EPUB file by setting the ‘EPUB_KEEP_CONTAINER_FOLDER’
customization variable to 1.
* Menu:
* EPUB Output File and Directory:: Use syntax highlighting in code excerpts.
* EPUB Cross-References:: Cross-references in HTML output.
* EPUB HTML::
File: texinfo.info, Node: EPUB Output File and Directory, Next: EPUB Cross-References, Up: Generating EPUB
21.5.1 Container Directory and Output Files
-------------------------------------------
A directory containing the files and directories needed for the EPUB
format is created when outputting EPUB. The name of this container
directory is derived from the base name of the input file (that is, any
extension is removed), with ‘_epub_package’ postpended. If an output
directory is specified, with ‘--output’, or with the ‘SUBDIR’
customization variable, the container directory is created in that
directory instead of the current directory. At the beginning of a new
run, the container directory and all its contents are removed. The
container directory is also removed after the final EPUB file has been
generated in the default case.
The HTML files produced from the Texinfo manual are output in
subdirectories of the container directory. Image files referred to from
the Texinfo manual, if found, are copied to subdirectories of the
container directory.
The EPUB output file is a ZIP archive of the container directory.
The file name is derived from the base name, with the ‘.epub’ extension
postpended. If an output file is specified, with ‘--output’, or with
the ‘OUTFILE’ customization function, this file name is used instead.
The output EPUB file is never placed in the directory specified by
‘--output’ or ‘SUBDIR’; only the container directory is placed there, as
explained just above.
The EPUB output file is not generated if the customization variable
‘EPUB_CREATE_CONTAINER_FILE’ is set to 0. The container directory is
left after the final EPUB file has been generated if
‘EPUB_KEEP_CONTAINER_FOLDER’ is set.
*Note Invoking texi2any::.
File: texinfo.info, Node: EPUB Cross-References, Next: EPUB HTML, Prev: EPUB Output File and Directory, Up: Generating EPUB
21.5.2 EPUB Cross-References
----------------------------
The EPUB format does not support references from an EPUB file to another
EPUB file. Therefore any references to "external" Texinfo manuals
should resolve to an external URL. ‘texi2any’ produces these links with
HTML cross-reference configuration (*note HTML Xref Configuration::).
Since the links in the resulting EPUB are incorrect if no information is
found for the cross-references, ‘texi2any’ issues a warning by default
for missing cross-references information. If these warnings are
unwanted, set ‘CHECK_HTMLXREF’ to 0.
Browse
Usage
Versions