doctools_lang_cmdref(n)       Documentation tools      doctools_lang_cmdref(n)



______________________________________________________________________________

NAME
       doctools_lang_cmdref - doctools language command reference

SYNOPSIS
       arg text

       arg_def type name ?mode?

       bullet

       call args

       category text

       class text

       cmd text

       cmd_def command

       comment plaintext

       const text

       copyright text

       def text

       description

       enum

       emph text

       example text

       example_begin

       example_end

       file text

       fun text

       image name ?label?

       include filename

       item

       keywords args

       lb

       list_begin what

       list_end

       lst_item text

       manpage_begin command section version

       manpage_end

       method text

       moddesc text

       namespace text

       nl

       opt text

       opt_def name ?arg?

       option text

       package text

       para

       rb

       require package ?version?

       section name

       sectref id ?text?

       sectref-external text

       see_also args

       strong text

       subsection name

       syscmd text

       term text

       titledesc desc

       tkoption_def name dbname dbclass

       type text

       uri text ?text?

       usage args

       var text

       vset varname value

       vset varname

       widget text

_________________________________________________________________

DESCRIPTION
       This document specifies both names and syntax of all the commands which
       together are the doctools markup language, version 1.  As this document
       is intended to be a reference the commands are listed in alphabetical
       order, and the descriptions are relatively short.  A beginner should
       read the much more informally written doctools language introduction
       first.

COMMANDS
       arg text
              Text markup. The argument text is marked up as the argument of a
              command. Main uses are the highlighting of command arguments in
              free-form text, and for the argument parameters of the markup
              commands call and usage.

       arg_def type name ?mode?
              Text structure. List element. Argument list. Automatically
              closes the previous list element. Specifies the data-type of the
              described argument of a command, its name and its i/o-mode. The
              latter is optional.

       bullet Deprecated. Text structure. List element. Itemized list. See
              item for the canonical command to open a list item in an
              itemized list.

       call args
              Text structure. List element. Definition list. Automatically
              closes the previous list element. Defines the term as a command
              and its arguments.  The first argument is the name of the
              command described by the following free-form text, and all
              arguments coming after that are descriptions of the command's
              arguments.  It is expected that the arguments are marked up with
              arg, method, option etc., as is appropriate, and that the
              command itself is marked up with cmd.  It is expected that the
              formatted term is not only printed in place, but also in the
              table of contents of the document, or synopsis, depending on the
              output format.

       category text
              Document information. Anywhere. This command registers its plain
              text arguments as the category this document belongs to. If this
              command is used multiple times the last value specified is used.

       class text
              Text markup. The argument is marked up as the name of a class.
              The text may have other markup already applied to it. Main use
              is the highlighting of class names in free-form text.

       cmd text
              Text markup. The argument text is marked up as the name of a Tcl
              command. The text may have other markup already applied to it.
              Main uses are the highlighting of commands in free-form text,
              and for the command parameters of the markup commands call and
              usage.

       cmd_def command
              Text structure. List element. Command list. Automatically closes
              the previous list element. The argument specifies the name of
              the Tcl command to be described by the list element. Expected to
              be marked up in the output as if it had been formatted with cmd.

       comment plaintext
              Text markup. The argument text is marked up as a comment
              standing outside of the actual text of the document. Main use is
              in free-form text.

       const text
              Text markup. The argument is marked up as a constant value. The
              text may have other markup already applied to it. Main use is
              the highlighting of constants in free-form text.

       copyright text
              Document information. Anywhere. The command registers the plain
              text argument as a copyright assignment for the manpage. When
              invoked more than once the assignments are accumulated.

       def text
              Text structure. List element. Definition list. Automatically
              closes the previous list element. The argument text is the term
              defined by the new list element. Text markup can be applied to
              it.

       description
              Document structure. This command separates the header from the
              document body.  Implicitly starts a section named "DESCRIPTION"
              (See command section).

       enum   Text structure. List element. Enumerated list. Automatically
              closes the previous list element.

       emph text
              Text markup. The argument text is marked up as emphasized. Main
              use is for general highlighting of pieces of free-form text
              without attaching special meaning to the pieces.

       example text
              Text structure, Text markup. This command marks its argument up
              as an example. Main use is the simple embedding of examples in
              free-form text. It should be used if the example does not need
              special markup of its own. Otherwise use a sequence of
              example_begin ... example_end.

       example_begin
              Text structure. This commands starts an example. All text until
              the next example_end belongs to the example. Line breaks,
              spaces, and tabs have to be preserved literally. Examples cannot
              be nested.

       example_end
              Text structure. This command closes the example started by the
              last example_begin.

       file text
              Text markup. The argument is marked up as a file or directory,
              i.e. in general a path. The text may have other markup already
              applied to it. Main use is the highlighting of paths in free-
              form text.

       fun text
              Text markup. The argument is marked up as the name of a
              function. The text may have other markup already applied to it.
              Main use is the highlighting of function names in free-form
              text.

       image name ?label?
              Text markup. The argument is the symbolic name of an image and
              replaced with the image itself, if a suitable variant is found
              by the backend. The second argument, should it be present, will
              be interpreted the human-readable description of the image, and
              put into the output in a suitable position, if such is supported
              by the format. The HTML format, for example, can place it into
              the alt attribute of image references.

       include filename
              Templating. The contents of the named file are interpreted as
              text written in the doctools markup and processed in the place
              of the include command. The markup in the file has to be self-
              contained. It is not possible for a markup command to cross the
              file boundaries.

       item   Text structure. List element. Itemized list. Automatically
              closes the previous list element.

       keywords args
              Document information. Anywhere. This command registers all its
              plain text arguments as keywords applying to this document. Each
              argument is a single keyword. If this command is used multiple
              times all the arguments accumulate.

       lb     Text. The command is replaced with a left bracket. Use in free-
              form text.  Required to avoid interpretation of a left bracket
              as the start of a markup command.

       list_begin what
              Text structure. This command starts a list. The exact nature of
              the list is determined by the argument what of the command. This
              further determines which commands are have to be used to start
              the list elements. Lists can be nested, i.e. it is allowed to
              start a new list within a list element.

              The allowed types (and their associated item commands) are:

              arguments
                     arg_def.

              commands
                     cmd_def.

              definitions
                     def and call.

              enumerated
                     enum

              itemized
                     item

              options
                     opt_def

              tkoptions
                     tkoption_def

       Additionally the following names are recognized as shortcuts for some
       of the regular types:

              args   Short for arguments.

              cmds   Short for commands.

              enum   Short for enumerated.

              item   Short for itemized.

              opts   Short for options.

       At last the following names are still recognized for backward
       compatibility, but are otherwise considered to be deprecated.

              arg    Deprecated. See arguments.

              bullet Deprecated. See itemized.

              cmd    Deprecated. See commands.

              opt    Deprecated. See options.

              tkoption
                     Deprecated. See tkoptions.


       list_end
              Text structure. This command closes the list opened by the last
              list_begin command coming before it.

       lst_item text
              Deprecated. Text structure. List element. Definition list. See
              def for the canonical command to open a general list item in a
              definition list.

       manpage_begin command section version
              Document structure. The command to start a manpage. The
              arguments are the name of the command described by the manpage,
              the section of the manpages this manpage resides in, and the
              version of the module containing the command. All arguments have
              to be plain text, without markup.

       manpage_end
              Document structure. Command to end a manpage/document. Anything
              in the document coming after this command is in error.

       method text
              Text markup. The argument text is marked up as the name of an
              object method, i.e. subcommand of a Tcl command. The text may
              have other markup already applied to it. Main uses are the
              highlighting of method names in free-form text, and for the
              command parameters of the markup commands call and usage.

       moddesc text
              Document information. Header. Registers the plain text argument
              as a short description of the module the manpage resides in.

       namespace text
              Text markup. The argument text is marked up as a namespace name.
              The text may have other markup already applied to it. Main use
              is the highlighting of namespace names in free-form text.

       nl     Deprecated. Text structure. See para for the canonical command
              to insert paragraph breaks into the text.

       opt text
              Text markup. The argument text is marked up as optional. The
              text may have other markup already applied to it. Main use is
              the highlighting of optional arguments, see the command arg arg.

       opt_def name ?arg?
              Text structure. List element. Option list. Automatically closes
              the previous list element. Specifies name and arguments of the
              option described by the list element. It is expected that the
              name is marked up using option.

       option text
              Text markup. The argument is marked up as option. The text may
              have other markup already applied to it. Main use is the
              highlighting of options, also known as command-switches, in
              either free-form text, or the arguments of the call and usage
              commands.

       package text
              Text markup. The argument is marked up as the name of a package.
              The text may have other markup already applied to it. Main use
              is the highlighting of package names in free-form text.

       para   Text structure. This command breaks free-form text into
              paragraphs. Each command closes the paragraph coming before it
              and starts a new paragraph for the text coming after it. Higher-
              level forms of structure are sections and subsections.

       rb     Text. The command is replaced with a right bracket. Use in free-
              form text.  Required to avoid interpretation of a right bracket
              as the end of a markup command.

       require package ?version?
              Document information. Header. This command registers its
              argument package as the name of a package or application
              required by the described package or application. A minimum
              version can be provided as well. This argument can be marked up.
              The usual markup is opt.

       section name
              Text structure. This command starts a new named document
              section. The argument has to be plain text. Implicitly closes
              the last paragraph coming before it and also implicitly opens
              the first paragraph of the new section.

       sectref id ?text?
              Text markup. Formats a reference to the section identified by
              id.  If no text is specified the title of the referenced section
              is used in the output, otherwise text is used.

       sectref-external text
              Text markup. Like sectref, except that the section is assumed to
              be in a different document and therefore doesn't need to be
              identified, nor are any checks for existence made. Only the text
              to format is needed.

       see_also args
              Document information. Anywhere. The command defines direct
              cross-references to other documents. Each argument is a plain
              text label identifying the referenced document. If this command
              is used multiple times all the arguments accumulate.

       strong text
              Deprecated. Text markup. See emph for the canonical command to
              emphasize text.

       subsection name
              Text structure. This command starts a new named subsection of a
              section. The argument has to be plain text. Implicitly closes
              the last paragraph coming before it and also implicitly opens
              the first paragraph of the new subsection.

       syscmd text
              Text markup. The argument text is marked up as the name of an
              external command. The text may have other markup already applied
              to it. Main use is the highlighting of external commands in
              free-form text.

       term text
              Text markup. The argument is marked up as unspecific
              terminology.  The text may have other markup already applied to
              it. Main use is the highlighting of important terms and concepts
              in free-form text.

       titledesc desc
              Document information. Header. Optional. Registers the plain text
              argument as the title of the manpage. Defaults to the value
              registered by moddesc.

       tkoption_def name dbname dbclass
              Text structure. List element. Widget option list. Automatically
              closes the previous list element. Specifies the name of the
              option as used in scripts, the name used by the option database
              (dbname), and its class (dbclass), i.e. its type. It is expected
              that the name is marked up using option.

       type text
              Text markup. The argument is marked up as the name of a data
              type. The text may have other markup already applied to it. Main
              use is the highlighting of data types in free-form text.

       uri text ?text?
              Text markup. The argument is marked up as an uri (i.e. a uniform
              resource identifier. The text may have other markup already
              applied to it. Main use is the highlighting of uris in free-form
              text. The second argument, should it be present, will be
              interpreted the human-readable description of the uri. In other
              words, as its label. Without an explicit label the uri will be
              its own label.

       usage args
              Text markup. See call for the full description, this command is
              syntactically identical, as it is in its expectations for the
              markup of its arguments.  In contrast to call it is however not
              allowed to generate output where this command occurs in the
              text. The command is silent.  The formatted text may only appear
              in a different section of the output, for example a table of
              contents, or synopsis, depending on the output format.

       var text
              Text markup. The argument is marked up as the name of a
              variable. The text may have other markup already applied to it.
              Main use is the highlighting of variables in free-form text.

       vset varname value
              Templating. In this form the command sets the named document
              variable to the specified value. It does not generate output.
              I.e. the command is replaced by the empty string.

       vset varname
              Templating. In this form the command is replaced by the value of
              the named document variable

       widget text
              Text markup. The argument is marked up as the name of a widget.
              The text may have other markup already applied to it. Main use
              is the highlighting of widget names in free-form text.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category doctools
       of the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either package and/or
       documentation.

SEE ALSO
       doctools_intro, doctools_lang_faq, doctools_lang_intro,
       doctools_lang_syntax

KEYWORDS
       doctools commands, doctools language, doctools markup, markup, semantic
       markup

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>




doctools                              1.0              doctools_lang_cmdref(n)
