texinfo: Functions Commands

Def Cmds in Detail

Variables Commands

Back to Software Index

16.5.1 Functions and Similar Entities
-------------------------------------

This section describes the commands for describing functions and similar
entities:

'@deffn CATEGORY NAME ARGUMENTS...'
     The '@deffn' command is the general definition command for
     functions, interactive commands, and similar entities that may take
     arguments.  You must choose a term to describe the category of
     entity being defined; for example, "Function" could be used if the
     entity is a function.  The '@deffn' command is written at the
     beginning of a line and is followed on the same line by the
     category of entity being described, the name of this particular
     entity, and its arguments, if any.  Terminate the definition with
     '@end deffn' on a line of its own.

     For example, here is a definition:

          @deffn Command forward-char nchars
          Move point forward @var{nchars} characters.
          @end deffn

     This shows a rather terse definition for a "command" named
     'forward-char' with one argument, NCHARS.

     '@deffn' prints argument names such as NCHARS in slanted type in
     the printed output, because we think of these names as
     metasyntactic variables--they stand for the actual argument values.
     Within the text of the description, however, write an argument name
     explicitly with '@var' to refer to the value of the argument.  In
     the example above, we used '@var{nchars}' in this way.

     In the extremely unusual case when an argument name contains '--',
     or another character sequence which is treated specially (Note:
     Conventions), use '@code' around the special characters.  This
     avoids the conversion to typographic en-dashes and em-dashes.

     The template for '@deffn' is:

          @deffn CATEGORY NAME ARGUMENTS...
          BODY-OF-DEFINITION
          @end deffn

'@defun NAME ARGUMENTS...'
     The '@defun' command is the definition command for functions.
     '@defun' is equivalent to '@deffn Function ...'.  Terminate the
     definition with '@end defun' on a line of its own.  Thus, the
     template is:

          @defun FUNCTION-NAME ARGUMENTS...
          BODY-OF-DEFINITION
          @end defun

'@defmac NAME ARGUMENTS...'
     The '@defmac' command is the definition command for macros.
     '@defmac' is equivalent to '@deffn Macro ...' and works like
     '@defun'.

'@defspec NAME ARGUMENTS...'
     The '@defspec' command is the definition command for special forms.
     (In Lisp, a special form is an entity much like a function; Note:
     (elisp)Special Forms.)  '@defspec' is equivalent to '@deffn
     {Special Form} ...' and works like '@defun'.

  All these commands create entries in the index of functions.