texinfo: Formatting Commands

Overview

Conventions

Printed Books

Back to Software Index

1.8 @-commands
==============

In a Texinfo file, the commands you write to describe the contents of
the manual are preceded by an '@' character; they are called
"@-commands".  For example, '@node' is the command to indicate a node
and '@chapter' is the command to indicate the start of a chapter.
Almost all @ command names are entirely lowercase.

  Texinfo's @-commands are a strictly limited set of constructs.  The
strict limits are primarily intended to "force" you, the author, to
concentrate on the writing and the content of your manual, rather than
the details of the formatting.

  Depending on what they do or what arguments(1) they take, you need to
write @-commands on lines of their own or as part of sentences:

   * Some commands are written at the start of a line and the rest of
     the line comprises the argument text, such as '@chapter' (which
     creates chapter titles).

   * Some commands can appear anywhere, generally within a sentence, and
     are followed by empty braces, such as '@dots{}' (which creates an
     ellipsis ...).

   * Some commands can appear anywhere, generally within a sentence, and
     are followed by the argument text in braces, such as '@code{a+1}'
     (which marks text as being code, 'a+1' being the argument in this
     case).

   * Some commands are written at the start of a line, with general text
     on following lines, terminated by a matching '@end' command on a
     line of its own.  For example, '@example', then the lines of a
     coding example, then '@end example'.

As a general rule, a command requires braces if it mingles among other
text; but it does not need braces if it is on a line of its own.  The
non-alphabetic commands, such as '@:', are exceptions to the rule; they
do not need braces.

  As you gain experience with Texinfo, you will rapidly learn how to
write the different commands: the different ways to write commands
actually make it easier to write and read Texinfo files than if all
commands followed exactly the same syntax.  *Note @-Command Syntax:
Command Syntax, for all the details.

   ---------- Footnotes ----------

   (1) The word "argument" comes from the way it is used in mathematics
and does not refer to a dispute between two people; it refers to the
information presented to the command.  According to the 'Oxford English
Dictionary', the word derives from the Latin for "to make clear, prove";
thus it came to mean 'the evidence offered as proof', which is to say,
'the information offered', which led to its mathematical meaning.  In
its other thread of derivation, the word came to mean 'to assert in a
manner against which others may make counter assertions', which led to
the meaning of 'argument' as a dispute.