doctools(3)



doctools(3tcl)                Documentation tools               doctools(3tcl)

______________________________________________________________________________

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 lan-
       guage command reference.

       If on the other hand the reader wishes to write her own formatting  en-
       gine  for  some format, i.e. is a plugin writer then reading and under-
       standing 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 ex-
              plained 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  pro-
              vide  their  user with a short description of the available for-
              matting commands and their meanings. It returns  a  string  con-
              taining 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 format-
              ting  engine it will search for the file in a number of directo-
              ries stored in a list. See section FORMAT MAPPING for  more  ex-
              planations.

              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  con-
       verter object.

       objectName method ?arg arg ...?
              The  method method and its arg'uments determine the exact behav-
              ior 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  sin-
              gle  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 CONFIGURA-
              TION.

       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  en-
              gine  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 speci-
              fied  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  sym-
              bolic filenames to the actual uris.  The object just stores this
              mapping and makes it available to the configured formatting  en-
              gine  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   ::doc-
              tools::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  parame-
              ters.

       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  com-
              mands  dt_file and dt_mainfile.  These commands are described in
              more detail in the companion document doctools_api which  speci-
              fies 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 in-
              stead.

              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 doc-
              uments (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  com-
              mand 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 for-
              mat. 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 com-
              mand dt_copyright.  This command is described in more detail  in
              the  companion document doctools_api which specifies the API be-
              tween 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 pro-
              cessed, or the package described by it.

              This information must be used if and only if the engine  is  un-
              able  to  find any copyright assignments within the document it-
              self. Such are specified by the  formatting  command  copyright.
              This  command is described in more detail in the companion docu-
              ment 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  di-
              rectly 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  ex-
              tended through the object method search.

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

              This list of paths can be extended through  the  command  ::doc-
              tools::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/lo-
              cal/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 selfcon-
                     tained HTML markup for the body section of a  HTML  docu-
                     ment. 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  selfcon-
                     tained  HTML  markup for the body section of a HTML docu-
                     ment. 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 selfcon-
                     tained HTML markup for the header section of a HTML docu-
                     ment. 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  pat-
                     tern will be used.

                     The engine will consult the xref database when encounter-
                     ing specific commands and will create a link if the rele-
                     vant  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 proces-
              sor 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  direc-
              tory 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  selfcon-
                     tained 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 out-
       put 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,    doc-
       tools_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>

tcllib                               1.5.6                      doctools(3tcl)

Man(1) output converted with man2html
list of all man pages