In Texinfo, you can mark words and phrases in a variety of ways. The Texinfo formatters use this information to determine how to highlight the text. You can specify, for example, whether a word or phrase is a defining occurrence, a metasyntactic variable, or a symbol used in a program. Also, you can emphasize text.
Texinfo has commands for indicating just what kind of object a piece of
text refers to. For example, metasyntactic variables are marked by
@var
, and code by @code
. Since the pieces of text are
labelled by commands that tell what kind of object they are, it is easy
to change the way the Texinfo formatters prepare such text. (Texinfo is
an intentional formatting language rather than a typesetting
formatting language.)
For example, in a printed manual,
code is usually illustrated in a typewriter font;
@code
tells TeX to typeset this text in this font. But it
would be easy to change the way TeX highlights code to use another
font, and this change would not effect how keystroke examples are
highlighted. If straight typesetting commands were used in the body
of the file and you wanted to make a change, you would need to check
every single occurrence to make sure that you were changing code and
not something else that should not be changed.
The highlighting commands can be used to generate useful information from the file, such as lists of functions or file names. It is possible, for example, to write a program in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains words or phrases marked by a specified command. You could do this to construct an index of functions if you had not already made the entries.
The commands serve a variety of purposes:
@code{sample-code}
@kbd{keyboard-characters}
@key{key-name}
@samp{text}
@var{metasyntactic-variable}
@file{file-name}
@dfn{term}
@cite{reference}
@code
{sample-code}
Use the @code
command to indicate text that is a piece of a
program and which consists of entire syntactic tokens. Enclose the
text in braces.
Thus, you should use @code
for an expression in a program, for
the name of a variable or function used in a program, or for a
keyword. Also, you should use @code
for the name of a
program, such as diff
, that is a name used in the machine. (You
should write the name of a program in the ordinary text font if you
regard it as a new English word, such as `Emacs' or `Bison'.)
Use @code
for environment variables such as TEXINPUTS
,
and other variables.
Use @code
for command names in command languages that
resemble programming languages, such as Texinfo or the shell.
For example, @code
and @samp
are produced by writing
`@code{@@code}' and `@code{@@samp}' in the Texinfo
source, respectively.
Note, however, that you should not use @code
for shell options
such as `-c' when such options stand alone. (Use @samp
.)
Also, an entire shell command often looks better if written using
@samp
rather than @code
. In this case, the rule is to
choose the more pleasing format.
It is incorrect to alter the case of a word inside an @code
command when it appears at the beginning of a sentence. Most computer
languages are case sensitive. In C, for example, Printf
is
different from the identifier printf
, and most likely is a
misspelling of it. Even in languages which are not case sensitive, it
is confusing to a human reader to see identifiers spelled in different
ways. Pick one spelling and always use that. If you do not want to
start a sentence with a command written all in lower case, you should
rearrange the sentence.
Do not use the @code
command for a string of characters shorter
than a syntactic token. If you are writing about `TEXINPU', which
is just a part of the name for the TEXINPUTS
environment
variable, you should use @samp
.
In particular, you should not use the @code
command when writing
about the characters used in a token; do not, for example, use
@code
when you are explaining what letters or printable symbols
can be used in the names of functions. (Use @samp
.) Also, you
should not use @code
to mark text that is considered input to
programs unless the input is written in a language that is like a
programming language. For example, you should not use @code
for
the keystroke commands of GNU Emacs (use @kbd
instead) although
you may use @code
for the names of the Emacs Lisp functions that
the keystroke commands invoke.
In the printed manual, @code
causes TeX to typeset the
argument in a typewriter face. In the Info file, it causes the Info
formatting commands to use single quotation marks around the text.
For example,
Use @code{diff} to compare two files.
produces this in the printed manual:
Use
diff
to compare two files.
and this in the Info file:
Use `diff' to compare two files.
@kbd
{keyboard-characters}
Use the @kbd
command for characters of input to be typed by
users. For example, to refer to the characters M-a,
write
@kbd{M-a}
and to refer to the characters M-x shell, write
@kbd{M-x shell}
The @kbd
command has the same effect as @code
in Info,
but may produce a different font in a printed manual.
You can embed another @-command inside the braces of an @kbd
command. Here, for example, is the way to describe a command that
would be described more verbosely as "press an `r' and then
press the RET key":
@kbd{r @key{RET}}
This produces: r RET
You also use the @kbd
command if you are spelling out the letters
you type; for example:
To give the @code{logout} command, type the characters @kbd{l o g o u t @key{RET}}.
This produces:
To give the
logout
command, type the characters l o g o u t RET.
(Also, this example shows that you can add spaces for clarity. If you really want to mention a space character as one of the characters of input, write @key{SPC} for it.)
@key
{key-name}
Use the @key
command for the conventional name for a key on a
keyboard, as in:
@key{RET}
You can use the @key
command within the argument of an
@kbd
command when the sequence of characters to be typed
includes one or more keys that are described by name.
For example, to produce C-x ESC you would type:
@kbd{C-x @key{ESC}}
Here is a list of the recommended names for keys; they are all in upper case:
- SPC
- Space
- RET
- Return
- LFD
- Linefeed
- TAB
- Tab
- BS
- Backspace
- ESC
- Escape
- DEL
- Delete
- SFT
- Shift
- CTL
- Control
- META
- Meta
There are subtleties to handling words like `meta' or `ctl' that are
names of shift keys. When mentioning a character in which the shift
key is used, such as Meta-a, use the @kbd
command alone;
do not use the @key
command; but when you are referring to the
shift key in isolation, use the @key
command. For example,
write `@kbd{Meta-a}' to produce Meta-a and
`@key{META}' to produce META. This is because
Meta-a refers to keys that you press on a keyboard, but
META refers to a key without implying that you press it. In
short, use @kbd
for what you do, and use @key
for what
you talk about: "Press @kbd{M-a}
to move point to the
beginning of the sentence. The @key{META}
key is often in the
lower left of the keyboard."
@samp
{text}
Use the @samp
command to indicate text that is a literal example
or `sample' of a sequence of characters in a file, string, pattern, etc.
Enclose the text in braces. The argument appears within single
quotation marks in both the Info file and the printed manual; in
addition, it is printed in a fixed-width font.
To match @samp{foo} at the end of the line, use the regexp @samp{foo$}.
produces
To match `foo' at the end of the line, use the regexp `foo$'.
Any time you are referring to single characters, you should use
@samp
unless @kbd
is more appropriate. Use
@samp
for the names of command-line options. Also, you may use
@samp
for entire statements in C and for entire shell
commands--in this case, @samp
often looks better than
@code
. Basically, @samp
is a catchall for whatever is
not covered by @code
, @kbd
, or @key
.
Only include punctuation marks within braces if they are part of the string you are specifying. Write punctuation marks outside the braces if those punctuation marks are part of the English text that surrounds the string. In the following sentence, for example, the commas and period are outside of the braces:
In English, the vowels are @samp{a}, @samp{e}, @samp{i}, @samp{o}, @samp{u}, and sometimes @samp{y}.
This produces:
In English, the vowels are `a', `e', `i', `o', `u', and sometimes `y'.
@var
{metasyntactic-variable}
Use the @var
command to indicate metasyntactic variables. A
metasyntactic variable is something that stands for another piece of
text. For example, you should use a metasyntactic variable in the
documentation of a function to describe the arguments that are passed
to that function.
Do not use @var
for the names of particular variables in
programming languages. These are specific names from a program, so
@code
is correct for them. For example, the Lisp variable
texinfo-tex-command
is not a metasyntactic variable; it is
properly formatted using @code
.
The effect of @var
in the Info file is to change the case of
the argument to all upper case; in the printed manual, to italicize it.
For example,
To delete file @var{filename}, type @code{rm @var{filename}}.
produces
To delete file filename, type
rm filename
.
(Note that @var
may appear inside @code
,
@samp
, @file
, etc.)
Write a metasyntactic variable all in lower case without spaces, and use hyphens to make it more readable. Thus, the Texinfo source for the illustration of how to begin a Texinfo manual looks like this:
\input texinfo @@setfilename @var{info-file-name} @@settitle @var{name-of-manual}
This produces:
\input texinfo @setfilename info-file-name @settitle name-of-manual
In some documentation styles, metasyntactic variables are shown with angle brackets, for example:
..., type rm <filename>
However, that is not the style that Texinfo uses. (You can, of
course, modify the sources to TeX and the Info formatting commands
to output the <...>
format if you wish.)
@file
{file-name}
Use the @file
command to indicate text that is the name of a
file, buffer, or directory, or is the name of a node in Info. You can
also use the command for file name suffixes. Do not use @file
for symbols in a programming language; use @code
.
Currently, @file
is equivalent to @samp
in its effects.
For example,
The @file{.el} files are in the @file{/usr/local/emacs/lisp} directory.
produces
The `.el' files are in the `/usr/local/emacs/lisp' directory.
@dfn
{term}
Use the @dfn
command to identify the introductory or defining
use of a technical term. Use the command only in passages whose
purpose is to introduce a term which will be used again or which the
reader ought to know. Mere passing mention of a term for the first
time does not deserve @dfn
. The command generates italics in
the printed manual, and double quotation marks in the Info file. For
example:
Getting rid of a file is called @dfn{deleting} it.
produces
Getting rid of a file is called deleting it.
As a general rule, a sentence containing the defining occurrence of a term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition--it should make the meaning clear.
@cite
{reference}
Use the @cite
command for the name of a book that lacks a
companion Info file. The command produces italics in the printed
manual, and quotation marks in the Info file.
(If a book is written in Texinfo, it is better to use a cross reference
command since a reader can easily follow such a reference in Info.
See section @xref
.)
Usually, Texinfo changes the font to mark words in the text according to
what category the words belong to; an example is the @code
command.
Most often, this is the best way to mark words.
However, sometimes you will want to emphasize text without indicating a
category. Texinfo has two commands to do this. Also, Texinfo has
several commands that specify the font in which TeX will typeset
text. These commands have no affect on Info and only one of them,
the @r
command, has any regular use.
@emph
{text} and @strong
{text}
The @emph
and @strong
commands are for emphasis;
@strong
is stronger. In printed output, @emph
produces italics and @strong
produces
bold.
For example,
@quotation @strong{Caution:} @code{rm * .[^.]*} removes @emph{all} files in the directory. @end quotation
produces the following in printed output:
Caution:
rm * .[^.]*
removes all files in the directory.
and the following in Info:
*Caution*: `rm * .[^.]*' removes *all* files in the directory.
The @strong
command is seldom used except to mark what is, in
effect, a typographical element, such as the word `Caution' in the
preceding example.
In the Info file, both @emph
and @strong
put asterisks
around the text.
Caution: Do not use
@emph
or@strong
with the word `Note'; Info will mistake the combination for a cross reference. Use a phrase such as Please note or Caution instead.
@sc
{text}: The Small Caps FontUse the `@sc' command to set text in the printed output in A SMALL CAPS FONT and set text in the Info file in upper case letters.
Write the text between braces in lower case, like this:
The @sc{acm} and @sc{ieee} are technical societies.
This produces:
The ACM and IEEE are technical societies.
TeX typesets the small caps font in a manner that prevents the letters from `jumping out at you on the page'. This makes small caps text easier to read than text in all upper case. The Info formatting commands set all small caps text in upper case.
If the text between the braces of an @sc
command is upper case,
TeX typesets in FULL-SIZE CAPITALS. Use full-size capitals
sparingly.
You may also use the small caps font for a jargon word such as ATO (a NASA word meaning `abort to orbit').
There are subtleties to using the small caps font with a jargon word such as CDR, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the CDR of the list), but you should use `@code' when the word refers to the Lisp function of the same spelling.
Texinfo provides four font commands that specify font changes in the
printed manual but have no effect in the Info file. @i
requests italic font (in some versions of TeX, a slanted font
is used), @b
requests bold face, @t
requests the
fixed-width, typewriter-style font used by @code
, and @r
requests a
roman font, which is the usual font in which text is printed. All
four commands apply to an argument that follows, surrounded by
braces.
Only the @r
command has much use: in example programs, you
can use the @r
command to convert code comments from the
fixed-width font to a roman font. This looks better in printed
output.
For example,
@lisp (+ 2 2) ; @r{Add two plus two.} @end lisp
produces
(+ 2 2) ; Add two plus two.
If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language.
You can use regular TeX commands inside of @iftex
...
@end iftex
to create your own customized highlighting commands
for Texinfo. The easiest way to do this is to equate your customized
commands with pre-existing commands, such as those for italics. Such
new commands work only with TeX.
You can use the @definfoenclose
command inside of
@ifinfo
... @end ifinfo
to define commands for Info
with the same names as new commands for TeX.
@definfoenclose
creates new commands for Info that mark text by
enclosing it in strings that precede and follow the text.
(7)
Here is how to create a new @-command called @phoo
that causes
TeX to typeset its argument in italics and causes Info to display the
argument between `//' and `\\'.
For TeX, write the following to equate the @phoo
command with
the existing @i
italics command:
@iftex @global@let@phoo=@i @end iftex
This defines @phoo
as a command that causes TeX to typeset
the argument to @phoo
in italics. @global@let
tells
TeX to equate the next argument with the argument that follows the
equals sign.
For Info, write the following to tell the Info formatters to enclose the argument between `//' and `\\':
@ifinfo @definfoenclose phoo, //, \\ @end ifinfo
Write the @definfoenclose
command on a line and follow it with
three arguments separated by commas (commas are used as separators in an
@node
line in the same way).
@definfoenclose
is the @-command name
without the `@';
The latter two arguments enclose the highlighted text in the Info file. A delimiter string may contain spaces. Neither the start nor end delimiter is required. However, if you do not provide a start delimiter, you must follow the command name with two commas in a row; otherwise, the Info formatting commands will misinterpret the end delimiter string as a start delimiter string.
After you have defined @phoo
both for TeX and for Info, you
can then write @phoo{bar}
to see `//bar\\'
in Info and see
bar in italics in printed output.
Note that each definition applies to its own formatter: one for TeX, the other for Info.
Here is another example:
@ifinfo @definfoenclose headword, , : @end ifinfo @iftex @global@let@headword=@b @end iftex
This defines @headword
as an Info formatting command that
inserts nothing before and a colon after the argument and as a TeX
formatting command to typeset its argument in bold.