plucky (3) doctools_lang_cmdref.3tcl.gz

Provided by: tcllib_2.0+dfsg-2_all bug

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 set of required versions 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  Trackers  [http://core.tcl.tk/tcllib/reportlist].
       Please also report any ideas for enhancements you may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note  further  that  attachments  are strongly preferred over inlined patches. Attachments can be made by
       going to the Edit form of the ticket immediately after its creation, and then using the left-most  button
       in the secondary navigation bar.

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 (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>