14. Special Insertions

Texinfo provides several commands for inserting characters that have special meaning in Texinfo, such as braces, and for other graphic elements that do not correspond to simple characters you can type.

14.1 Inserting @ and {} and ,

‘@’ and curly braces are special characters in Texinfo. To insert these characters so they appear in text, you must put an ‘@’ in front of these characters to prevent Texinfo from misinterpreting them.

The comma ‘,’ is a special character only in one uncommon context: it separates arguments to commands that take multiple arguments.

14.1.1 Inserting ‘@’ with @@

@@ stands for a single ‘@’ in either printed or Info output.

Do not put braces after an @@ command.

14.1.2 Inserting ‘{’ and ‘}’ with @{ and @}

@{ stands for a single ‘{’ in either printed or Info output.

@} stands for a single ‘}’ in either printed or Info output.

Do not put braces after either an @{ or an @} command.

14.1.3 Inserting ‘,’ with @comma{}

Ordinarily, a comma ‘,’ is a normal character that can be simply typed in your input where you need it.

However, Texinfo uses the comma as a special character in one uncommon context: some commands, such as @acronym (see section @acronym{acronym[, meaning]}) and @xref (see section Cross References), as well as user-defined macros (see section Defining Macros), can take more than one argument. In these cases, the comma character is used to separate arguments.

Since a comma character would confuse Texinfo’s parsing for these commands, you must use the command ‘@comma{}’ instead if you want to pass an actual comma. Here are some examples:

@acronym{ABC, A Bizarre @comma{}}
@xref{Comma,, The @comma{} symbol}
@mymac{One argument@comma{} containing a comma}

Although , can be used nearly anywhere, there is no need for it anywhere except in this unusual case.

14.2 Inserting Quote Characters

As explained in the early section on general Texinfo input conventions (see section General Syntactic Conventions), Texinfo source files use the ASCII character ` (96 decimal) to produce a left quote (‘), and ASCII ' (39 decimal) to produce a right quote (’). Doubling these input characters (`` and '') produces double quotes (“ and ”). These are the conventions used by TeX.

This works all right for text. However, in examples of computer code, readers are especially likely to cut and paste the text verbatim—and, unfortunately, some document viewers will mangle these characters. (The free PDF reader xpdf works fine, but other PDF readers, both free and nonfree, have problems.)

If this is a concern for your document, Texinfo provides two special settings via @set:

@set txicodequoteundirected

causes the output for the ' character to be the undirected single quote, like this: '.

@set txicodequotebacktick

Cause the output for the ` character to be the standalone grave accent, like this: `.

xyza`'bc

If you want these settings for only part of the document, @clear will restore the normal behavior, as in @clear txicodequoteundirected.

These settings affect @code, @example, and @verbatim; they do not affect @samp. (See section Highlighting Commands are Useful.)

14.3 Inserting Space

The following sections describe commands that control spacing of various kinds within and after sentences.

14.3.1 Not Ending a Sentence

Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, less or more space is inserted after a period in a typeset manual. Since it is not always possible to determine when a period ends a sentence and when it is used in an abbreviation, special commands are needed in some circumstances. Usually, Texinfo can guess how to handle periods, so you do not need to use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the period, question mark, or exclamation mark that ends a sentence.

Use the @: command after a period, question mark, exclamation mark, or colon that should not be followed by extra space. For example, use @: after periods that end abbreviations which are not at the ends of sentences.

For example,

foo vs.@: bar
foo vs. bar

produces

foo vs. bar
foo vs. bar

@: has no effect on the Info and HTML output. In Docbook and XML, the previous punctuation character (.?!:) is output as an entity instead of as the normal character: ‘. ? ! :’. This gives further processors a chance to notice and not add the usual extra space.

Do not put braces after @: (or any non-alphabetic command).

14.3.2 Ending a Sentence

Use @. instead of a period, @! instead of an exclamation point, and @? instead of a question mark at the end of a sentence that ends with a capital letter. Otherwise, TeX will think the letter is an abbreviation and will not insert the correct end-of-sentence spacing. Here is an example:

Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

produces

Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.

In the Info file output, @. is equivalent to a simple ‘.’; likewise for @! and @?.

The meanings of @: and @. in Texinfo are designed to work well with the XEmacs sentence motion commands (see (xemacs)Sentences section ‘Sentences’ in XEmacs User’s Manual).

Do not put braces after any of these commands.

14.3.3 Multiple Spaces

Ordinarily, TeX collapses multiple whitespace characters (space, tab, and newline) into a single space. Info output, on the other hand, preserves whitespace as you type it, except for changing a newline into a space; this is why it is important to put two spaces at the end of sentences in Texinfo documents.

Occasionally, you may want to actually insert several consecutive spaces, either for purposes of example (what your program does with multiple spaces as input), or merely for purposes of appearance in headings or lists. Texinfo supports three commands: @SPACE, @TAB, and @NL, all of which insert a single space into the output. (Here, @SPACE represents an ‘@’ character followed by a space, i.e., ‘@ ’, and TAB and NL represent the tab character and end-of-line, i.e., when ‘@’ is the last character on a line.)

For example,

Spacey@ @ @ @
example.

produces

Spacey    example.

Other possible uses of @SPACE have been subsumed by @multitable (see section @multitable: Multi-column Tables).

Do not follow any of these commands with braces.

To produce a non-breakable space, see @tie.

14.3.4 @frenchspacing val: Control sentence spacing

In American typography, it is traditional and correct to put extra space at the end of a sentence, after a semi-colon, and so on. This is the default in Texinfo. In French typography (and many others), this extra space is wrong; all spaces are uniform.

Therefore Texinfo provides the @frenchspacing command to control the spacing after punctuation. It reads the rest of the line as its argument, which must be the single word ‘on’ or ‘off’ (always these words, regardless of the language) of the document. Here is an example:

@frenchspacing on
This is text. Two sentences. Three sentences. French spacing.

@frenchspacing off
This is text. Two sentences. Three sentences. Non-French spacing.

produces (there will be no difference in Info):

This is text. Two sentences. Three sentences. French spacing.

This is text. Two sentences. Three sentences. Non-French spacing.

@frenchspacing mainly affects the printed output, including the output after @., @!, and @? (see section Ending a Sentence).

In Info, usually space characters in the input are written unaltered to the output, and @frenchspacing does not change this. It does change the one case where makeinfo outputs a space on its own: when a sentence ends at a newline in the source. Here’s an example:

Some sentence.
Next sentence.

produces in Info output, with @frenchspacing off (the default), two spaces between the sentences:

Some sentence.  Next sentence.

With @frenchspacing on, makeinfo outputs only a single space:

Some sentence. Next sentence.

@frenchspacing has no effect on the HTML or Docbook output; for XML, it outputs a transliteration of itself (see section Output Formats).

14.3.5 @dmn{dimension}: Format a Dimension

At times, you may want to write ‘12pt’ or ‘8.5in’ with little or no space between the number and the abbreviation for the dimension. You can use the @dmn command to do this. On seeing the command, TeX inserts just enough space for proper typesetting; the Info formatting commands insert no space at all, since the Info file does not require it.

To use the @dmn command, write the number and then follow it immediately, with no intervening space, by @dmn, and then by the dimension within braces. For example,

A4 paper is 8.27@dmn{in} wide.

produces

A4 paper is 8.27in wide.

Not everyone uses this style. Some people prefer ‘8.27 in.@:’ or ‘8.27 inches’ to ‘8.27@dmn{in}’ in the Texinfo file. In these cases, however, the formatters may insert a line break between the number and the dimension, so use @w (see section @w{text}: Prevent Line Breaks). Also, if you write a period after an abbreviation within a sentence, you should write ‘@:’ after the period to prevent TeX from inserting extra whitespace, as shown here. See section Not Ending a Sentence.

14.4 Inserting Accents

Here is a table with the commands Texinfo provides for inserting floating accents. They all need an argument, the character to accent, which can either be given in braces as usual (@'{e}), or, as a special case, the braces can be omitted, in which case the argument is the next character (@'e). This is to make the source as convenient as possible to type and read, since accented characters are very common in some languages.

If the command is alphabetic, such as @dotaccent, then there must be a space between the command name and argument if braces are not used. If the command is non-alphabetic, such as @', then there must not be a space; the argument is the very next character.

Exception: the argument to @tieaccent must be enclosed in braces (since it is two characters instead of one).

To get the true accented characters output in Info, not just the ASCII transliterations, it is necessary to specify @documentencoding with an encoding which supports the required characters (see section @documentencoding). In this case, you can also use non-ASCII (e.g., pre-accented) characters in the source file.

This table lists the Texinfo commands for inserting other characters commonly used in languages other than English.

14.5 Inserting Quotation Marks

Use doubled single-quote characters to begin and end quotations: ‘‘…’’. TeX converts two single quotes to left- and right-hand doubled quotation marks, and Info converts doubled single-quote characters to ASCII double-quotes: ‘‘…’’ becomes "…".

You may occasionally need to produce two consecutive single quotes; for example, in documenting a computer language such as Maxima where ’’ is a valid command. You can do this with the input ’@w{}’; the empty @w command stops the combination into the double-quote characters.

The left quote character (‘, ASCII code 96) used in Texinfo is a grave accent in ANSI and ISO character set standards. We use it as a quote character because that is how TeX is set up, by default.

Texinfo supports several other quotation marks used in languages other than English. Below is a table with the commands Texinfo provides for inserting quotation marks.

In order to get the symbols for the quotation marks in encoded Info output, it is necessary to specify @documentencoding UTF-8. (See section @documentencoding.) Double guillemets are also present in ISO 8859-1 (aka Latin 1) and ISO 8859-15 (aka Latin 9).

The standard TeX fonts support the usual quotation marks used in English (the ones produced with single and doubled ASCII single-quotes). For the other quotation marks, TeX uses European Computer Modern (EC) fonts (‘ecrm1000’ and other variants). These fonts are freely available, of course; you can download them from http://www.ctan.org/tex-archive/fonts/ec, among other places.

The free EC fonts are bitmap fonts created with Metafont. Especially for on-line viewing, Type 1 (vector) versions of the fonts are preferable; these are available in the CM-Super font package (http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super).

Both distributions include installation instructions.

For the double angle quotation marks, Adobe and LaTeX glyph names are also supported: @guillemotleft and @guillemotright. These names are actually incorrect; a “guillemot” is a bird species (a type of auk).

Traditions for quotation mark usage vary to a great extent between languages (http://en.wikipedia.org/wiki/Quotation_mark%2C_non-English_usage#Overview). Texinfo does not provide commands for typesetting quotation marks according to the numerous traditions. Therefore, you have to choose the commands appropriate for the language of your manual. Sometimes aliases (see section @alias) can simplify the usage and make the source code more readable. For example, in German, @quotedblbase is used for the left double quote, and the right double quote is actually @quotedblleft, which is counter-intuitive. Thus, in this case the following aliases would be convenient:

@alias lgqq = quotedblbase
@alias rgqq = quotedblleft

14.6 Inserting Ellipsis and Bullets

An ellipsis (a line of dots) is not typeset as a string of periods, so a special command is used for ellipsis in Texinfo. The @bullet command is special, too. Each of these commands is followed by a pair of braces, ‘{}’, without any whitespace between the name of the command and the braces. (You need to use braces with these commands because you can use them next to other text; without the braces, the formatters would be confused. See section @-Command Syntax, for further information.)

14.6.1 @dots{} (…) and @enddots{} (...)

Use the @dots{} command to generate an ellipsis, which is three dots in a row, appropriately spaced … like so. Do not simply write three periods in the input file; that would work for the Info file output, but would produce the wrong amount of space between the periods in the printed manual.

Similarly, the @enddots{} command generates an end-of-sentence ellipsis, which has different spacing afterwards, ... Look closely to see the difference.

14.6.2 @bullet{} (•)

Use the @bullet{} command to generate a large round dot, or the closest possible thing to one. In Info, an asterisk is used.

Here is a bullet: •

When you use @bullet in @itemize, you do not need to type the braces, because @itemize supplies them. (See section @itemize.)

14.7 Inserting TeX and Legal Symbols: ©, ®

The logo ‘TeX’ is typeset in a special fashion and it needs an @-command. The copyright and registered symbols, ‘©’ and ‘®’, is also special. Each of these commands is followed by a pair of braces, ‘{}’, without any whitespace between the name of the command and the braces.

14.7.1 @TeX{} (TeX) and @LaTeX{} (LaTeX)

Use the @TeX{} command to generate ‘TeX’. In a printed manual, this is a special logo that is different from three ordinary letters. In Info, it just looks like ‘TeX’.

Similarly, use the @LaTeX{} command to generate ‘LaTeX’, which is even more special in printed manuals (and different from the incorrect La@TeX{}. In Info, the result is just ‘LaTeX’. (LaTeX is another macro package built on top of TeX, very loosely analogous to Texinfo in that it emphasizes logical structure, but much (much) larger.)

The spelling of these commands are unusual among Texinfo commands in that they use both uppercase and lowercase letters.

14.7.2 @copyright{} (©)

Use the @copyright{} command to generate the copyright symbol, ‘©’. Where possible, this is a ‘c’ inside a circle; in Info, this is ‘(C)’.

14.7.3 @registeredsymbol{} (®)

Use the @registeredsymbol{} command to generate the registered symbol, ‘®’. Where possible, this is an ‘R’ inside a circle; in Info, this is ‘(R)’.

14.8 @euro{} (€): Euro Currency Symbol

Use the @euro{} command to generate ‘€’. Where possible, this is the symbol for the Euro currency, invented as part of the European economic unification. In plain Info, it is the word ‘Euro ’. A trailing space is included in the text transliteration since typically no space is desired after the symbol, so it would be inappropriate to have a space in the source document.

Texinfo cannot magically synthesize support for the Euro symbol where the underlying system (fonts, software, whatever) does not support it. Therefore, in many cases it is preferable to use the word “Euro”. (In banking circles, the abbreviation for the Euro is EUR.)

In order to get the Euro symbol in encoded Info output, for example, it is necessary to specify @documentencoding ISO-8859-15. (See section @documentencoding.) The Euro symbol is in ISO 8859-15 (aka Latin 9), and is not in the more widely-used and supported ISO 8859-1 (Latin 1).

The Euro symbol does not exist in the standard TeX fonts (which were designed before the Euro was legislated into existence). Therefore, TeX uses an additional font, named feymr10 (along with other variables). It is freely available, of course; you can download it from http://www.ctan.org/tex-archive/fonts/eurosym, among other places. The distribution includes installation instructions.

14.9 @pounds{} (£): Pounds Sterling

Use the @pounds{} command to generate ‘£’. Where possible, this is the symbol for the currency pounds sterling. In Info, it is a ‘#’.

14.10 @textdegree{} (°): Degrees Symbol

Use the @textdegree{} command to generate ‘°’. Where possible, this is the normal symbol for degrees. In plain text and Info output, it is an ‘o’.

14.11 @minus{} (-): Inserting a Minus Sign

Use the @minus{} command to generate a minus sign. In a fixed-width font, this is a single hyphen, but in a proportional font, the symbol is the customary length for a minus sign—a little longer than a hyphen, shorter than an em-dash:

‘-’ is a minus sign generated with ‘@minus{}’,

‘-’ is a hyphen generated with the character ‘-’,

‘—’ is an em-dash for text.

In the fixed-width font used by Info, @minus{} is the same as a hyphen.

You should not use @minus{} inside @code or @example because the width distinction is not made in the fixed-width font they use.

When you use @minus to specify the mark beginning each entry in an itemized list, you do not need to type the braces (see section @itemize).

14.12 @geq{} (≥) and @leq{} (≤): Inserting relations

Use the @geq{} and @geq{} commands to generate greater-than-or-equal and less-than-equal-signs, ‘≥’ and ‘≤’. In plain text and Info output, these are the ASCII sequences ‘>=’ and ‘<=’. The

14.13 @math: Inserting Mathematical Expressions

You can write a short mathematical expression with the @math command. Write the mathematical expression between braces, like this:

@math{(a + b)(a + b) = a^2 + 2ab + b^2}

This produces the following in Info and HTML:

(a + b)(a + b) = a^2 + 2ab + b^2

The @math command has no special effect on the Info and HTML output. makeinfo expands any @-commands as usual, but it does not try to produce good mathematical formatting in any way.

However, as far as the TeX output is concerned, plain TeX mathematical commands are allowed in @math, starting with ‘\’, and the plain TeX math characters like ‘^’ and ‘_’ are also recognized. In essence, @math drops you into plain TeX math mode.

This allows you to conveniently write superscripts and subscripts (as in the above example), and also to use all the plain TeX math control sequences for symbols, functions, and so on, and thus get proper formatting in the TeX output, at least.

It’s best to use ‘\’ instead of ‘@’ for any such mathematical commands; otherwise, makeinfo will complain. On the other hand, input with matching (but unescaped) braces, such as ‘k_{75}’, is allowed inside @math, although makeinfo would complain about the bare braces in regular input.

Here’s an example:

@math{\sin 2\pi \equiv \cos 3\pi}

which looks like the input in Info and HTML:

\sin 2\pi \equiv \cos 3\pi

Since ‘\’ is an escape character inside @math, you can use @\ to get a literal backslash (\\ will work in TeX, but you’d get the literal ‘\\’ in Info). @\ is not defined outside of @math, since a ‘\’ ordinarily produces a literal ‘\’.

For displayed equations, you must at present use TeX directly (see section Raw Formatter Commands).

14.14 Click Sequences

When documenting graphical interfaces, it is necessary to describe sequences such as ‘Click on ‘File’, then choose ‘Open’, then …’. Texinfo offers commands @clicksequence and click to represent this, typically used like this:

… @clicksequence{File @click{} Open} …

which produces:

… File → Open …

The @click command produces a simple right arrow (‘->’ in Info) by default; this glyph is also available independently via the command @arrow{}.

You can change the glyph produced by @click with the command @clickstyle, which takes a command name as its single argument on the rest of the line, much like @itemize and friends (see section @itemize). The command should produce a glyph, and the usual empty braces ‘{}’ are omitted. Here’s an example:

@clickstyle @result
… @clicksequence{File @click{} Open} …

now produces:

… File ⇒ Open …

14.15 Glyphs for Examples

In Texinfo, code is often illustrated in examples that are delimited by @example and @end example, or by @lisp and @end lisp. In such examples, you can indicate the results of evaluation or an expansion using ‘⇒’ or ‘→’. Likewise, there are commands to insert glyphs to indicate printed output, error messages, equivalence of expressions, and the location of point.

The glyph-insertion commands do not need to be used within an example, but most often they are. Every glyph-insertion command is followed by a pair of left- and right-hand braces.

14.15.1 Glyphs Summary

Here are the different glyph commands:

⇒

@result{} points to the result of an expression.

→

@expansion{} shows the results of a macro expansion.

-|

@print{} indicates printed output.

error-->

@error{} indicates that the following text is an error message.

≡

@equiv{} indicates the exact equivalence of two forms.

∗

@point{} shows the location of point.

14.15.2 @result{} (⇒): Indicating Evaluation

Use the @result{} command to indicate the result of evaluating an expression.

The @result{} command is displayed as ‘⇒’ in Info and HTML and as a true double stemmed arrow in the printed output.

Thus, the following,

(cdr '(1 2 3))
    ⇒ (2 3)

may be read as “(cdr '(1 2 3)) evaluates to (2 3)”.

14.15.3 @expansion{} (→): Indicating an Expansion

When an expression is a macro call, it expands into a new expression. You can indicate the result of the expansion with the @expansion{} command.

The @expansion{} command is displayed as ‘→’ in Info and HTML, and as a long arrow with a flat base in the printed output.

For example, the following

@lisp
(third '(a b c))
    @expansion{} (car (cdr (cdr '(a b c))))
    @result{} c
@end lisp

produces

(third '(a b c))
    → (car (cdr (cdr '(a b c))))
    ⇒ c

which may be read as:

(third '(a b c)) expands to (car (cdr (cdr '(a b c)))); the result of evaluating the expression is c.

Often, as in this case, an example looks better if the @expansion{} and @result{} commands are indented.

14.15.4 @print{} (-|): Indicating Printed Output

Sometimes an expression will print output during its execution. You can indicate the printed output with the @print{} command.

The @print{} command is displayed as ‘-|’ in Info and HTML and (similarly) as a horizontal dash butting against a vertical bar in the printed output.

In the following example, the printed text is indicated with ‘-|’, and the value of the expression follows on the last line.

(progn (print 'foo) (print 'bar))
    -| foo
    -| bar
    ⇒ bar

In a Texinfo source file, this example is written as follows:

@lisp
(progn (print 'foo) (print 'bar))
    @print{} foo
    @print{} bar
    @result{} bar
@end lisp

14.15.5 @error{} (error-->): Indicating an Error Message

A piece of code may cause an error when you evaluate it. You can designate the error message with the @error{} command.

The @error{} command is displayed as ‘error-->’ in Info and HTML and as the word ‘error’ in a box in the printed output.

Thus,

@lisp
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@end lisp

produces

(+ 23 'x)
error--> Wrong type argument: integer-or-marker-p, x

This indicates that the following error message is printed when you evaluate the expression:

Wrong type argument: integer-or-marker-p, x

‘error-->’ itself is not part of the error message.

14.15.6 @equiv{} (≡): Indicating Equivalence

Sometimes two expressions produce identical results. You can indicate the exact equivalence of two forms with the @equiv{} command.

The @equiv{} command is displayed as ‘≡’ in Info and HTML and as a standard mathematical equivalence sign (three parallel horizontal lines) in the printed output.

Thus,

@lisp
(make-sparse-keymap) @equiv{} (list 'keymap)
@end lisp

produces

(make-sparse-keymap) ≡ (list 'keymap)

This indicates that evaluating (make-sparse-keymap) produces identical results to evaluating (list 'keymap).

14.15.7 @point{} (∗): Indicating Point in a Buffer

Sometimes you need to show an example of text in an XEmacs buffer. In such examples, the convention is to include the entire contents of the buffer in question between two lines of dashes containing the buffer name.

You can use the ‘@point{}’ command to show the location of point in the text in the buffer. (The symbol for point, of course, is not part of the text in the buffer; it indicates the place between two characters where point is located.)

The @point{} command is displayed as ‘∗’ in Info and HTML and as a small five pointed star in the printed output.

The following example shows the contents of buffer ‘foo’ before and after evaluating a Lisp command to insert the word changed.

---------- Buffer: foo ----------
This is the ∗contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
    ⇒ nil
---------- Buffer: foo ----------
This is the changed ∗contents of foo.
---------- Buffer: foo ----------

In a Texinfo source file, the example is written like this:

@example
---------- Buffer: foo ----------
This is the @point{}contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
    @result{} nil
---------- Buffer: foo ----------
This is the changed @point{}contents of foo.
---------- Buffer: foo ----------
@end example

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