17. Conditionally Visible Text

The conditional commands allow you to use different text for different output formats, or for general conditions that you define. For example, you can use them to specify different text for the printed manual and the Info output.

The conditional commands comprise the following categories.

• Commands specific to an output format (Info, TeX, HTML, …).
• Commands specific to any output format other than a given one (not Info, not TeX, …).
• ‘Raw’ formatter text for any output format, passed straight through with no interpretation of @-commands.
• Format-independent variable substitutions, and testing if a variable is set or clear.

17.1 Conditional Commands

Texinfo has an @ifformat environment for each output format, to allow conditional inclusion of text for a particular output format.

@ifinfo begins segments of text that should be ignored by TeX when it typesets the printed manual, and by makeinfo when not producing Info output. The segment of text appears only in the Info file and, for historical compatibility, the plain text output.

The environments for the other formats are analogous:

@ifdocbook … @end ifdocbook

Text to appear only in the Docbook output.

@ifhtml … @end ifhtml

Text to appear only in the HTML output.

@ifplaintext … @end ifplaintext

Text to appear only in the plain text output.

@iftex … @end iftex

Text to appear only in the printed manual.

@ifxml … @end ifxml

Text to appear only in the XML output.

The @if… and @end if… commands must appear on lines by themselves in your source file.

Here is an example showing all these conditionals:

@iftex
This text will appear only in the printed manual.
@end iftex
@ifinfo
However, this text will appear only in Info and plain text.
@end ifinfo
@ifhtml
And this text will only appear in HTML.
@end ifhtml
@ifplaintext
Whereas this text will only appear in plain text.
@end ifplaintext
@ifxml
Notwithstanding that this will only appear in XML.
@end ifxml
@ifdocbook
Nevertheless, this will only appear in Docbook.
@end ifdocbook

The preceding example produces the following line:

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.

17.2 Conditional Not Commands

You can specify text to be included in any output format other than a given one with the @ifnot… environments:

@ifnotdocbook … @end ifnotdocbook
@ifnothtml … @end ifnothtml
@ifnotinfo … @end ifnotinfo
@ifnotplaintext … @end ifnotplaintext
@ifnottex … @end ifnottex
@ifnotxml … @end ifnotxml

The @ifnot… command and the @end command must appear on lines by themselves in your actual source file.

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

There is one exception (for historical compatibility): @ifnotinfo text is omitted for both Info and plain text output, not just Info. To specify text which appears only in Info and not in plain text, use @ifnotplaintext, like this:

@ifinfo
@ifnotplaintext
This will be in Info, but not plain text.
@end ifnotplaintext
@end ifinfo

The regions delimited by these commands are ordinary Texinfo source as with @iftex, not raw formatter source as with @tex (see section Raw Formatter Commands).

17.3 Raw Formatter Commands

Inside a region delineated by @iftex and @end iftex, you can embed some raw TeX commands. The Texinfo processors will ignore such a region unless TeX output is being produced. You can write the TeX commands as you would write them in a normal TeX file, except that you must replace the ‘\’ used by TeX with an ‘@’. For example, in the @titlepage section of a Texinfo file, you can use the TeX command @vskip to format the copyright page. (The @titlepage command causes Info to ignore the region automatically, as it does with the @iftex command.)

However, most features of plain TeX will not work within @iftex, as they are overridden by Texinfo features. The purpose of @iftex is to provide conditional processing for the Texinfo source, not provide access to underlying formatting features.

You can enter plain TeX completely, and use ‘\’ in the TeX commands, by delineating a region with the @tex and @end tex commands. All plain TeX commands and category codes are restored within an @tex region. The sole exception is that the @ character still introduces a command, so that @end tex can be recognized properly. As with @iftex, Texinfo processors will ignore such a region unless TeX output is being produced.

In complex cases, you may wish to define new TeX macros within @tex. You must use \gdef to do this, not \def, because @tex regions are processed in a TeX group.

As an example, here is a mathematical expression written in plain TeX:

@tex
$$ \chi^2 = \sum_{i=1}^N
         \left (y_i - (a + b x_i)
         \over \sigma_i\right)^2 $$
@end tex

The output of this example will appear only in a printed manual. If you are reading this in Info, you will not see the equation that appears in the printed manual.

Analogously, you can use @ifhtml … @end ifhtml to delimit a region to be included in HTML output only, and @html … @end html for a region of raw HTML.

Likewise, you can use @ifxml … @end ifxml to delimit a region to be included in XML output only, and @xml … @end xml for a region of raw XML.

Again likewise, you can use @ifdocbook … @end ifdocbook to delimit a region to be included in Docbook output only, and @docbook … @end docbook for a region of raw Docbook.

In all cases, the exception to the raw processing is that @ is still an escape character, so the @end command can be recognized.

17.4 @set, @clear, and @value

You can direct the Texinfo formatting commands to format or ignore parts of a Texinfo file with the @set, @clear, @ifset, and @ifclear commands.

Here are brief descriptions of these commands, see the following sections for more details:

@set flag [value]

Set the variable flag, to the optional value if 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.

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

17.4.1 @set and @value

You use the @set command to specify a value for a flag, which is later expanded by the @value command.

A flag (aka variable) is an identifier. It is best to use only letters and numerals in a flag name, not ‘-’ or ‘_’—they will work in some contexts, but not all, due to limitations in TeX.

The value is the remainder of the input line, and can contain anything.

Write the @set command like this:

@set foo This is a string.

This sets the value of the flag foo to “This is a string.”.

The Texinfo formatters then replace an @value{flag} command with the string to which flag is set. Thus, when foo is set as shown above, the Texinfo formatters convert this:

@value{foo}
to this:
This is a string.

You can write an @value command within a paragraph; but you must write an @set command on a line of its own.

If you write the @set command like this:

@set foo

without specifying a string, the value of foo is the empty string.

If you clear a previously set flag with @clear flag, a subsequent @value{flag} command will report an error.

For example, if you set foo as follows:

@set howmuch very, very, very

then the formatters transform

It is a @value{howmuch} wet day.
into
It is a very, very, very wet day.

If you write

@clear howmuch

then the formatters transform

It is a @value{howmuch} wet day.
into
It is a {No value for "howmuch"} wet day.

17.4.2 @ifset and @ifclear

When a flag is set, the Texinfo formatting commands format text between subsequent pairs of @ifset flag and @end ifset commands. When the flag is cleared, the Texinfo formatting commands do not format the text. @ifclear operates analogously.

Write the conditionally formatted text between @ifset flag and @end ifset commands, like this:

@ifset flag
conditional-text
@end ifset

For example, you can create one document that has two variants, such as a manual for a ‘large’ and ‘small’ model:

You can use this machine to dig up shrubs
without hurting them.

@set large

@ifset large
It can also dig up fully grown trees.
@end ifset

Remember to replant promptly …

In the example, the formatting commands will format the text between @ifset large and @end ifset because the large flag is set.

When flag is cleared, the Texinfo formatting commands do not format the text between @ifset flag and @end ifset; that text is ignored and does not appear in either printed or Info output.

For example, if you clear the flag of the preceding example by writing an @clear large command after the @set large command (but before the conditional text), then the Texinfo formatting commands ignore the text between the @ifset large and @end ifset commands. In the formatted output, that text does not appear; in both printed and Info output, you see only the lines that say, “You can use this machine to dig up shrubs without hurting them. Remember to replant promptly …”.

If a flag is cleared with an @clear flag command, then the formatting commands format text between subsequent pairs of @ifclear and @end ifclear commands. But if the flag is set with @set flag, then the formatting commands do not format text between an @ifclear and an @end ifclear command; rather, they ignore that text. An @ifclear command looks like this:

@ifclear flag

17.4.3 @value Example

You can use the @value command to minimize the number of places you need to change when you record an update to a manual. See section GNU Sample Texts, for the full text of an example of using this to work with Automake distributions.

This example is adapted from (make)Top section ‘Overview’ in The GNU Make Manual.

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 (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

3. Write text for the title page, for people reading the printed manual:

   @titlepage @title GNU Make @subtitle A Program for Directing Recompilation @subtitle Edition @value{EDITION}, … @subtitle @value{UPDATE-MONTH} @page @insertcopying … @end titlepage

   (On a printed cover, a date listing the month and the year looks less fussy than a date listing the day as well as the month and year.)

4. Write text for the Top node, for people reading the Info file:

   @ifnottex @node Top @top Make @insertcopying … @end ifnottex

   After you format the manual, the @value constructs have been expanded, so the output contains text like this:

   This is Edition 0.35 Beta, last updated 14 August 1992, of `The GNU Make Manual', for `make', Version 3.63 Beta.

When you update the manual, you change only the values of the flags; you do not need to edit the three sections.

17.5 Conditional Nesting

Conditionals can be nested; however, the details are a little tricky. The difficulty comes with failing conditionals, such as @ifhtml when HTML is not being produced, where the included text is to be ignored. However, it is not to be completely ignored, since it is useful to have one @ifset inside another, for example—that is a way to include text only if two conditions are met. Here’s an example:

@ifset somevar
@ifset anothervar
Both somevar and anothervar are set.
@end ifset
@ifclear anothervar
Somevar is set, anothervar is not.
@end ifclear
@end ifset

Technically, Texinfo requires that for a failing conditional, the ignored text must be properly nested with respect to that failing conditional. Unfortunately, it’s not always feasible to check that all conditionals are properly nested, because then the processors could have to fully interpret the ignored text, which defeats the purpose of the command. Here’s an example illustrating these rules:

@ifset a
@ifset b
@ifclear ok  - ok, ignored
@end junky   - ok, ignored
@end ifset
@c WRONG - missing @end ifset.

Finally, as mentioned above, all conditional commands must be on lines by themselves, with no text (even spaces) before or after. Otherwise, the processors cannot reliably determine which commands to consider for nesting purposes.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.