Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       doctools - doctools - Processing documents

SYNOPSIS

       package require Tcl  8.2

       package require doctools  ?1.5.6?

       ::doctools::new objectName ?option value...?

       ::doctools::help

       ::doctools::search path

       objectName method ?arg arg ...?

       objectName configure

       objectName configure option

       objectName configure -option value...

       objectName cget -option

       objectName destroy

       objectName format text

       objectName map symbolic actual

       objectName parameters

       objectName search path

       objectName setparam name value

       objectName warnings

_________________________________________________________________________________________________

DESCRIPTION

       This package provides a class for the creation of objects able to process and convert text
       written in the doctools markup language into any output format X for  which  a  formatting
       engine is available.

       A  reader interested in the markup language itself should start with the doctools language
       introduction and proceed from there  to  the  formal  specifications,  i.e.  the  doctools
       language syntax and the doctools language command reference.

       If on the other hand the reader wishes to write her own formatting engine for some format,
       i.e. is a plugin writer then reading and understanding the doctools plugin  API  reference
       is  an absolute necessity, as that document specifies the interaction between this package
       and its plugins, i.e. the formatting engines, in detail.

PUBLIC API

   PACKAGE COMMANDS
       ::doctools::new objectName ?option value...?
              This command creates a new doctools object with an  associated  Tcl  command  whose
              name is objectName. This object command is explained in full detail in the sections
              OBJECT COMMAND and OBJECT METHODS. The object command will  be  created  under  the
              current  namespace  if  the objectName is not fully qualified, and in the specified
              namespace otherwise.

              The options and their values coming after the name of the object are  used  to  set
              the initial configuration of the object.

       ::doctools::help
              This is a convenience command for applications wishing to provide their user with a
              short description of the available  formatting  commands  and  their  meanings.  It
              returns a string containing a standard help text.

       ::doctools::search path
              Whenever  an  object created by this the package has to map the name of a format to
              the file containing the code for its formatting engine it will search for the  file
              in  a  number  of directories stored in a list. See section FORMAT MAPPING for more
              explanations.

              This list not only contains three default directories which  are  declared  by  the
              package  itself,  but  is also extensible user of the package.  This command is the
              means to do so. When given a path to an existing and  readable  directory  it  will
              prepend  that  directory  to the list of directories to search. This means that the
              path added last is later searched through first.

              An error will be thrown if the path either does not exist, is not a  directory,  or
              is not readable.

   OBJECT COMMAND
       All commands created by ::doctools::new have the following general form and may be used to
       invoke various operations on their doctools converter object.

       objectName method ?arg arg ...?
              The method method and its arg'uments determine the exact behavior of  the  command.
              See section OBJECT METHODS for the detailed specifications.

   OBJECT METHODS
       objectName configure
              The method returns a list of all known options and their current values when called
              without any arguments.

       objectName configure option
              The method behaves like the method cget when called  with  a  single  argument  and
              returns the value of the option specified by said argument.

       objectName configure -option value...
              The  method  reconfigures  the specified options of the object, setting them to the
              associated values, when called with an even number of arguments, at least two.

              The legal options are described in the section OBJECT CONFIGURATION.

       objectName cget -option
              This method expects a legal configuration option as argument and  will  return  the
              current value of that option for the object the method was invoked for.

              The legal configuration options are described in section OBJECT CONFIGURATION.

       objectName destroy
              This method destroys the object it is invoked for.

       objectName format text
              This  method runs the text through the configured formatting engine and returns the
              generated string as its  result.  An  error  will  be  thrown  if  no  -format  was
              configured for the object.

              The  method  assumes  that  the  text  is  in  doctools  format as specified in the
              companion document doctools_fmt. Errors will be thrown otherwise.

       objectName map symbolic actual
              This methods add one entry to the per-object mapping from symbolic filenames to the
              actual  uris.   The  object  just stores this mapping and makes it available to the
              configured  formatting  engine  through  the  command  dt_fmap.   This  command  is
              described  in  more detail in the doctools plugin API reference which specifies the
              interaction between the objects created by this  package  and  doctools  formatting
              engines.

       objectName parameters
              This  method  returns a list containing the names of all engine parameters provided
              by the configured formatting engine. It will return an empty list if the object  is
              not yet configured for a specific format.

       objectName search path
              This  method  extends the per-object list of paths searched for doctools formatting
              engines. See also the command ::doctools::search on how to extend  the  per-package
              list  of  paths.  Note that the path entered last will be searched first.  For more
              details see section FORMAT MAPPING.

       objectName setparam name value
              This method sets the named engine parameter to the specified value.  It will  throw
              an  error  if  the object is either not yet configured for a specific format, or if
              the formatting engine for the configured format does not provide a  parameter  with
              the  given  name.   The  list  of  parameters provided by the configured formatting
              engine can be retrieved through the method parameters.

       objectName warnings
              This method returns a list containing all the warnings which were generated by  the
              configured formatting engine during the last invocation of the method format.

   OBJECT CONFIGURATION
       All doctools objects understand the following configuration options:

       -file file
              The  argument  of  this  option  is  stored in the object and made available to the
              configured formatting engine through the commands dt_file and  dt_mainfile.   These
              commands  are described in more detail in the companion document doctools_api which
              specifies the API between the object and formatting engines.

              The default value of this option is the empty string.

              The configured formatting engine should interpret the value as the name of the file
              containing the document which is currently processed.

       -ibase file
              The  argument  of this option is stored in the object and used as the base path for
              resolution of relative include paths. If this option is not set (empty string)  the
              value of -file is used instead.

              Note that -file and -ibase, while similar looking, are actually very different. The
              value of -file is used by some  engines  for  the  generation  of  proper  relative
              references between output documents (HTML). As such this is a destination path. The
              -ibase on the other hand is used to resolve relative include  paths,  and  as  such
              deals with source paths.

              The default value of this option is the empty string.

       -module text
              The  argument  of  this  option  is  stored in the object and made available to the
              configured formatting engine  through  the  command  dt_module.   This  command  is
              described in more detail in the companion document doctools_api which specifies the
              API between the object and formatting engines.

              The default value of this option is the empty string.

              The configured formatting engine should interpret the value  as  the  name  of  the
              module the file containing the document which is currently processed belongs to.

       -format text
              The argument of this option specifies the format to generate and by implication the
              formatting engine to use when converting text via the method  format.  Its  default
              value  is  the empty string. The method format cannot be used if this option is not
              set to a valid value at least once.

              The package will immediately try to map the given name to  a  file  containing  the
              code  for  a  formatting  engine generating that format. An error will be thrown if
              this mapping fails. In that case a previously configured format is left untouched.

              The section FORMAT MAPPING explains in detail how the package and object will  look
              for engine implementations.

       -deprecated boolean
              This  option  is  a boolean flag. The object will generate warnings if this flag is
              set and the text given to method format  contains  the  deprecated  markup  command
              strong.  Its default value is FALSE. In other words, no warnings will be generated.

       -copyright text
              The  argument  of  this  option  is  stored in the object and made available to the
              configured formatting engine through the command  dt_copyright.   This  command  is
              described in more detail in the companion document doctools_api which specifies the
              API between the object and formatting engines.

              The default value of this option is the empty string.

              The configured  formatting  engine  should  interpret  the  value  as  a  copyright
              assignment  for the document which is currently processed, or the package described
              by it.

              This information must be used if and only if the  engine  is  unable  to  find  any
              copyright  assignments  within  the  document  itself.  Such  are  specified by the
              formatting command copyright. This command is  described  in  more  detail  in  the
              companion document doctools_fmt which specifies the doctools format itself.

   FORMAT MAPPING
       The  package  and  object will perform the following algorithm when trying to map a format
       name foo to a file containing an implementation of a formatting engine for foo:

       [1]    If foo is the name of an existing file then this file  is  directly  taken  as  the
              implementation.

       [2]    If  not, the list of per-object search paths is searched. For each directory in the
              list the package checks if that directory contains a file "fmt.foo". If  yes,  then
              that file is taken as the implementation.

              Note  that  this  list  of paths is initially empty and can be extended through the
              object method search.

       [3]    If not, the list of package paths is searched.  For each directory in the list  the
              package  checks if that directory contains a file "fmt.foo". If yes, then that file
              is taken as the implementation.

              This list of paths can be extended  through  the  command  ::doctools::search.   It
              contains  initially  one  path,  the  subdirectory "mpformats" of the directory the
              package itself is located in.   In  other  words,  if  the  package  implementation
              "doctools.tcl"  is installed in the directory "/usr/local/lib/tcllib/doctools" then
              it will by default search the directory  "/usr/local/lib/tcllib/doctools/mpformats"
              for format implementations.

       [4]    The mapping fails.

PREDEFINED ENGINES

       The  package  provides  predefined  engines for the following formats. Some of the engines
       support parameters. These will be explained below as well.

       html   This engine generates HTML markup, for processing by web  browsers  and  the  like.
              This engine supports four parameters:

              footer The  value  for this parameter has to be valid selfcontained HTML markup for
                     the body section of a HTML document. The default value is the empty  string.
                     The value is inserted into the generated output just before the </body> tag,
                     closing the body of the generated HTML.

                     This can be used to insert boilerplate  footer  markup  into  the  generated
                     document.

              header The  value  for this parameter has to be valid selfcontained HTML markup for
                     the body section of a HTML document. The default value is the empty  string.
                     The  value  is inserted into the generated output just after the <body> tag,
                     starting the body of the generated HTML.

                     This can be used to insert boilerplate  header  markup  into  the  generated
                     document.

              meta   The  value  for this parameter has to be valid selfcontained HTML markup for
                     the header section of a HTML  document.  The  default  value  is  the  empty
                     string.  The  value  is  inserted  into  the generated output just after the
                     <head> tag, starting the header section of the generated HTML.

                     This can be used to insert boilerplate meta data markup into  the  generated
                     document, like references to a stylesheet, standard meta keywords, etc.

              xref   The  value  for this parameter has to be a list of triples specifying cross-
                     reference information. This information is used by the engine to create more
                     hyperlinks.  Each  triple  is a list containing a pattern, symbolic filename
                     and fragment reference, in this order. If a pattern  is  specified  multiple
                     times the last occurrence of the pattern will be used.

                     The  engine  will  consult  the  xref  database  when  encountering specific
                     commands and will create a link if the relevant  text  matches  one  of  the
                     patterns. No link will be created if no match was found. The link will go to
                     the uri file#fragment listed in the relevant triple, after conversion of the
                     symbolic  file  name  to the actual uri via dt_fmap (see the doctools plugin
                     API reference).  This file-to-uri mapping was build by calls to  the  method
                     map of the doctools object (See section OBJECT METHODS).

                     The following formatting commands will consult the xref database:

                     cmd word
                            The  command  will  look  for the patterns sa,word, and word, in this
                            order. If this fails if it will convert word to all lowercase and try
                            again.

                     syscmd word
                            The  command  will  look  for the patterns sa,word, and word, in this
                            order. If this fails if it will convert word to all lowercase and try
                            again.

                     term word
                            The command will look for the patterns kw,word, sa,word, and word, in
                            this order. If this fails if it will convert word  to  all  lowercase
                            and try again.

                     package word
                            The command will look for the patterns sa,word, kw,word, and word, in
                            this order. If this fails if it will convert word  to  all  lowercase
                            and try again.

                     see_also word...
                            The  command  will  look  for the patterns sa,word, and word, in this
                            order, for each word given to the command. If this fails if  it  will
                            convert word to all lowercase and try again.

                     keywords word...
                            The  command  will  look  for the patterns kw,word, and word, in this
                            order, for each word given to the command. If this fails if  it  will
                            convert word to all lowercase and try again.

       latex  This  engine  generates  output suitable for the latex text processor coming out of
              the TeX world.

       list   This engine retrieves version, section and title of the manpage from the  document.
              As such it can be used to generate a directory listing for a set of manpages.

       nroff  This  engine  generates nroff output, for processing by nroff, or groff. The result
              will be standard man pages as they are known in the unix world.

       markdown
              This engine generates Markdown markup. This engine supports two parameters:

              header The value for this parameter has to be valid selfcontained  markdown  markup
                     for  the body section of a markdown document. The default value is the empty
                     string. The value is inserted into the  generated  output  just  before  the
                     table of contents.

                     This  can  be  used  to  insert boilerplate header markup into the generated
                     document.

              xref   The value for this parameter has to be a list of triples  specifying  cross-
                     reference information.

                     The  full  details  of expected syntax and engine-internal use are explained
                     above for the html engine.

       null   This engine generates no outout at all. This can be  used  if  one  just  wants  to
              validate some input.

       tmml   This  engine  generates  TMML  markup  as specified by Joe English. The Tcl Manpage
              Markup Language is a derivate of XML.

       wiki   This engine generates Wiki markup as understood  by  Jean  Claude  Wippler's  wikit
              application.

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_cmdref,    doctools_lang_intro,     doctools_lang_syntax,
       doctools_plugin_apiref

KEYWORDS

       HTML, TMML, conversion, documentation, manpage, markdown, markup, nroff

CATEGORY

       Documentation tools

COPYRIGHT

       Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>