Conditionally Visible Text

Next: Macros: Defining New Texinfo Commands  Prev: Footnotes

Sometimes it is good to use different text for a printed manual and its corresponding Info file. In this case, you can use the conditional commands to specify which text is for the printed manual and which is for the Info file.

Conditional Commands

@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. The @ifinfo command should appear on a line by itself; end the Info-only text with a line containing @end ifinfo by itself. At the beginning of a Texinfo file, the Info permissions are contained within a region marked by @ifinfo and @end ifinfo. (See Info Summary and Permissions.)

The @iftex and @end iftex commands are similar to the @ifinfo and @end ifinfo commands, except that 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.

For example,

@iftex
This text will appear only in the printed manual.
@end iftex
@ifinfo
However, this text will appear only in Info.
@end ifinfo
The preceding example produces the following line:

However, this text will appear only in Info.Note how you only see one of the two lines, depending on whether you are reading the Info version or the printed version of this manual.

The @titlepage command is a special variant of @iftex that is used for making the title and copyright pages of the printed manual. (See @titlepage.)

Conditional Not Commands

You can specify text to be included in any output format other than some given one with the @ifnot... commands: 

@ifnothtml ... @end ifnothtml
@ifnotinfo ... @end ifnotinfo
@ifnottex ... @end ifnottex
(The @ifnot... command and the @end command must actually appear on lines by themselves.)

If the output file is not being made for the given format, the region is included. Otherwise, it is ignored.

The regions delimited by these commands are ordinary Texinfo source as with @iftex, not raw formatter source as with @tex.

Raw Formatter Commands

Inside a region delineated by @iftex and @end iftex, you can embed some raw TEX commands. Info will ignore these commands since they are only in that part of the file which is seen by TEX. You can write the TEX commands as you would write them in a normal TEX file, except that you must replace the `\' used by TEX with an `@'. For example, in the @titlepage section of a Texinfo file, you can use the TEX command @vskip to format the copyright page. (The @titlepage command causes Info to ignore the region automatically, as it does with the @iftex command.)

However, many features of plain TEX will not work, as they are overridden by Texinfo features.

You can enter plain TEX completely, and use `\' in the TEX commands, by delineating a region with the @tex and @end tex commands. (The @tex command also causes Info to ignore the region, like the @iftex command.) The sole exception is that @ 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 ifhtml for a region of raw HTML (again, except that @ is still the escape character, so the @end command can be recognized.)

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

In addition, you can use the @set flag command to set the value of flag to a string of characters; and use @value{flag} to insert that string. You can use @set, for example, to set a date and use @value to insert the date in several places in the Texinfo file.

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

Use the @set flag command to turn on, or set, a flag; a flag can be any single word. The format for the command looks like this: 

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

Use the @clear flag command to turn off, or clear, a flag. Clearing a flag is the opposite of setting a flag. The command looks like this:

@clear flag
Write the command on a line of its own.

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

In brief, the commands are:

@set flag
Tell the Texinfo formatting commands that flag is set.

@clear flag
Tell the Texinfo formatting commands that flag is cleared.

@ifset flag
If flag is set, tell the Texinfo formatting commands to format the text up to the following @end ifset command.

If flag is cleared, tell the Texinfo formatting commands to ignore text up to the following @end ifset command.

@ifclear flag
If flag is set, tell the Texinfo formatting commands to ignore the text up to the following @end ifclear command.

If flag is cleared, tell the Texinfo formatting commands to format the text up to the following @end ifclear command.

@value

You can use the @set command to specify a value for a flag, which is expanded by the @value command. The value is a string a characters.

Write the @set command like this:

@set foo This is a string.
This sets the value of foo to ``This is a string.''

The Texinfo formatters 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

@value{foo}
@exdent to
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 an empty string.

If you clear a previously set flag with an @clear flag command, a subsequent @value{flag} command is invalid and the string is replaced with an error message that says `{No value for "flag"}'.

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.
@exdent 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.
@exdent into
It is a {No value for "how-much"} wet day.

@value Example

You can use the @value command to limit the number of places you need to change when you record an update to a manual. Here is how it is done in The GNU Make Manual:Set the flags:

@set EDITION 0.35 Beta
@set VERSION 3.63 Beta
@set UPDATED 14 August 1992
@set UPDATE-MONTH August 1992
Write text for the first @ifinfo section, for people reading the Texinfo file:

This is Edition @value{EDITION},
last updated @value{UPDATED},
of @cite{The GNU Make Manual},
for @code{make}, Version @value{VERSION}.
Write text for the title page, for people reading the printed manual:

@title GNU Make
@subtitle A Program for Directing Recompilation
@subtitle Edition @value{EDITION}, ...
@subtitle @value{UPDATE-MONTH}
(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.)Write text for the Top node, for people reading the Info file:

This is Edition @value{EDITION}
of the @cite{GNU Make Manual},
last updated @value{UPDATED}
for @code{make} Version @value{VERSION}.

After you format the manual, the text in the first @ifinfo section looks 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, change only the values of the flags; you do not need to rewrite the three sections.