[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Sometimes it is good to use different text for different output formats. For example, you can use the conditional commands to specify different text for the printed manual and the Info output.
Conditional commands may not be nested.
The conditional commands comprise the following categories.
16.1 Conditional Commands | Specifying text for HTML, Info, or TeX. | |
16.2 Conditional Not Commands | Specifying text for not HTML, Info, or TeX. | |
16.3 Raw Formatter Commands | Using raw TeX or HTML commands. | |
16.4 @set , @clear , and @value | Designating which text to format (for all output formats); and how to set a flag to a string that you can insert. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Texinfo has a pair of commands for each output format, to allow conditional inclusion of text for a particular output format.
@ifinfo
begins segments of text that should be ignored by TeX
when it typesets the printed manual. The segment of text appears only
in the Info file and (for historical compatibility) the plain text
output. The @ifinfo
command should appear on a line by itself;
end the Info-only text with a line containing @end ifinfo
by
itself.
The @iftex
and @end iftex
commands are analogous to the
@ifinfo
and @end ifinfo
commands; they specify text that
will appear in the printed manual but not in the Info file. Likewise
for @ifhtml
and @end ifhtml
, which specify text to
appear only in HTML output. And for @ifplaintext
and
@end ifplaintext
, which specify text to appear only in plain
text output.
For example,
@iftex This text will appear only in the printed manual. @end iftex @ifinfo However, this text will appear only in Info (or plain text). @end ifinfo @ifhtml And this text will only appear in HTML. @end ifhtml @ifplaintext Whereas this text will only appear in plain text. @end ifplaintext
The preceding example produces the following line: However, this text will appear only in Info (or plain text). And this text will only appear in HTML.
Notice that you only see one of the input lines, depending on which version of the manual you are reading.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can specify text to be included in any output format other
than some given one with the @ifnot…
commands:
@ifnothtml … @end ifnothtml @ifnotinfo … @end ifnotinfo @ifnotplaintext … @end ifnotplaintext @ifnottex … @end ifnottex
(The @ifnot…
command and the @end
command must
appear on lines by themselves in your actual source file.)
If the output file is not being made for the given format, the region is included. Otherwise, it is ignored.
With one exception (for historical compatibility): @ifnotinfo
text is omitted for both Info and plain text output, not just Info. To
specify text which appears only in Info and not in plain text, use
@ifnotplaintext
, like this:
This will be in Info, but not plain text.
The regions delimited by these commands are ordinary Texinfo source as
with @iftex
, not raw formatter source as with @tex
(see section Raw Formatter Commands).
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Inside a region delineated by @iftex
and @end iftex
, you
can embed some raw TeX commands. Info will ignore these commands
since they are only in that part of the file which is seen by TeX.
You can write the TeX commands as you would write them in a normal
TeX file, except that you must replace the ‘\’ used by TeX
with an ‘@’. For example, in the @titlepage
section of a
Texinfo file, you can use the TeX command @vskip
to format
the copyright page. (The @titlepage
command causes Info to
ignore the region automatically, as it does with the @iftex
command.)
However, many features of plain TeX will not work, as they are overridden by Texinfo features.
You can enter plain TeX completely, and use ‘\’ in the TeX
commands, by delineating a region with the @tex
and @end
tex
commands. (The @tex
command also causes Info to ignore the
region, like the @iftex
command.) The sole exception is that the
@
character still introduces a command, so that @end tex
can be recognized properly.
For example, here is a mathematical expression written in plain TeX:
@tex $$ \chi^2 = \sum_{i=1}^N \left (y_i - (a + b x_i) \over \sigma_i\right)^2 $$ @end tex
The output of this example will appear only in a printed manual. If you are reading this in Info, you will not see the equation that appears in the printed manual.
Analogously, you can use @ifhtml … @end ifhtml
to delimit
a region to be included in HTML output only, and @html …
@end html
for a region of raw HTML (again, except that @
is
still the escape character, so the @end
command can be
recognized.)
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
@set
, @clear
, and @value
You can direct the Texinfo formatting commands to format or ignore parts
of a Texinfo file with the @set
, @clear
, @ifset
,
and @ifclear
commands.
Brief descriptions:
@set flag [value]
Set the variable flag, to the optional value if specifed.
@clear flag
Undefine the variable flag, whether or not it was previously defined.
@ifset flag
If flag is set, text through the next @end ifset
command
is formatted. If flag is clear, text through the following
@end ifset
command is ignored.
@ifclear flag
If flag is set, text through the next @end ifclear
command
is ignored. If flag is clear, text through the following
@end ifclear
command is formatted.
16.4.1 @set and @value | Expand a flag variable to a string. | |
16.4.2 @ifset and @ifclear | Format a region if a flag is set. | |
16.4.3 @value Example | An easy way to update edition information. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
@set
and @value
You use the @set
command to specify a value for a flag, which is
later expanded by the @value
command.
A flag is an identifier. In general, it is best to use only letters and numerals in a flag name, not ‘-’ or ‘_’—they will work in some contexts, but not all, due to limitations in TeX.
The value is the remainder of the input line, and can contain anything.
Write the @set
command like this:
@set foo This is a string.
This sets the value of the flag foo
to “This is a string.”.
The Texinfo formatters then replace an @value{flag}
command with the string to which flag is set. Thus, when
foo
is set as shown above, the Texinfo formatters convert this:
@value{foo}
to this:
This is a string.
You can write an @value
command within a paragraph; but you
must write an @set
command on a line of its own.
If you write the @set
command like this:
@set foo
without specifying a string, the value of foo
is the empty string.
If you clear a previously set flag with @clear flag
, a
subsequent @value{flag}
command will report an error.
For example, if you set foo
as follows:
@set how-much very, very, very
then the formatters transform
It is a @value{how-much} wet day.
into
It is a very, very, very wet day.
If you write
@clear how-much
then the formatters transform
It is a @value{how-much} wet day.
into
It is a {No value for "how-much"} wet day.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
@ifset
and @ifclear
When a flag is set, the Texinfo formatting commands format text
between subsequent pairs of @ifset flag
and @end
ifset
commands. When the flag is cleared, the Texinfo formatting
commands do not format the text. @ifclear
operates
analogously.
Write the conditionally formatted text between @ifset flag
and @end ifset
commands, like this:
@ifset flag conditional-text @end ifset
For example, you can create one document that has two variants, such as a manual for a ‘large’ and ‘small’ model:
You can use this machine to dig up shrubs without hurting them. @set large @ifset large It can also dig up fully grown trees. @end ifset Remember to replant promptly …
In the example, the formatting commands will format the text between
@ifset large
and @end ifset
because the large
flag is set.
When flag is cleared, the Texinfo formatting commands do
not format the text between @ifset flag
and
@end ifset
; that text is ignored and does not appear in either
printed or Info output.
For example, if you clear the flag of the preceding example by writing
an @clear large
command after the @set large
command
(but before the conditional text), then the Texinfo formatting commands
ignore the text between the @ifset large
and @end ifset
commands. In the formatted output, that text does not appear; in both
printed and Info output, you see only the lines that say, “You can use
this machine to dig up shrubs without hurting them. Remember to replant
promptly …”.
If a flag is cleared with an @clear flag
command, then
the formatting commands format text between subsequent pairs of
@ifclear
and @end ifclear
commands. But if the flag
is set with @set flag
, then the formatting commands do
not format text between an @ifclear
and an @end
ifclear
command; rather, they ignore that text. An @ifclear
command looks like this:
@ifclear flag
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
@value
ExampleYou can use the @value
command to minimize the number of places
you need to change when you record an update to a manual. See section GNU Sample Texts, for an example of this same principle can work with
Automake distributions, and full texts.
Here is an example adapted from Overview in The GNU Make Manual):
@set EDITION 0.35 Beta @set VERSION 3.63 Beta @set UPDATED 14 August 1992 @set UPDATE-MONTH August 1992
@copying
section (see section @copying
: Declare copying permissions):
@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
@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.)
@ifnottex @node Top @top Make @insertcopying … @end ifnottex
After you format the manual, the @value
constructs have been
expanded, so the output contains text like this:
This is Edition 0.35 Beta, last updated 14 August 1992, of `The GNU Make Manual', for `make', Version 3.63 Beta.
When you update the manual, you change only the values of the flags; you do not need to edit the three sections.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on a sunny day using texi2html.