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.
@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 section Summary and Copying Permissions for Info.)
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.
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:
This text will appear only in the printed manual.
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 section @titlepage.)
Inside a region delineated by @iftex and @end iftex,
you can embed some PlainTeX 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 PlainTeX will not work, as they are overridden by features of Texinfo.
You can enter PlainTeX 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.)
For example, here is a mathematical expression written in PlainTeX:
@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 anything after this paragraph. In a printed manual, the above expression looks like this:
@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
@clear flag
@ifset flag
@end ifset command.
If flag is cleared, tell the Texinfo formatting commands to
ignore text up to the following @end ifset command.
@ifclear flag
@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}
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.
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.
@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.