[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

16 Conditionally Visible Text

Sometimes it is good to use different text for different output formats. For example, you can use the conditional commands to specify different text for the printed manual and the Info output.

Conditional commands may not be nested.

The conditional commands comprise the following categories.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

16.1 Conditional Commands

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] [ ? ]

16.2 Conditional Not Commands

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

@ifnothtml … @end ifnothtml
@ifnotinfo … @end ifnotinfo
@ifnotplaintext … @end ifnotplaintext
@ifnottex … @end ifnottex

(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] [ ? ]

16.3 Raw Formatter Commands

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

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

You can enter plain TeX completely, and use ‘\’ in the TeX commands, by delineating a region with the @tex and @end tex commands. (The @tex command also causes Info to ignore the region, like the @iftex command.) The sole exception is that the @ character still introduces a command, so that @end tex can be recognized properly.

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

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

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

Analogously, you can use @ifhtml … @end ifhtml to delimit a region to be included in HTML output only, and @html … @end html for a region of raw HTML (again, except that @ is still the escape character, so the @end command can be recognized.)


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

16.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 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] [ ? ]

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

16.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 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):

  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.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on a sunny day using texi2html.