Scroll to navigation

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 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.



  

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








OBJECT METHODS



  

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

  

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

  

  
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.

  

  

  
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.

  

  

  
This method destroys the object it is invoked for.

  

  
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.

  

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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:



  

  
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.

  

  

  
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.

  

  

  
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.

  

  

  
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.

  

  

  
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.

  
  
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.



  

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







  
  
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.

  

  
  
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.

  

  

  
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.

  

  

  
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:

  







  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.











  

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

  

  
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.

  

  
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.

  

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







  

  
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.

  

  

  
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.

  









  

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

  

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

  

  
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>








  

    1.5.6
    tcllib