Scroll to navigation

doctoc_intro(3tcl) Documentation tools doctoc_intro(3tcl) 


NAME

doctoc_intro - doctoc introduction

DESCRIPTION

doctoc (short for documentation tables of contents) stands for a
  set of related, yet different, entities which are working together for the
  easy creation and transformation of tables of contents for documentation.
  These are


  
[1]

  
A tcl based language for the semantic markup of a table of
      contents. Markup is represented by Tcl commands.





  
[2]

  
A package providing the ability to read and transform texts
      written in that markup language. It is important to note that the actual
      transformation of the input text is delegated to plugins.





  
[3]

  
An API describing the interface between the package above
      and a plugin.





Which of the more detailed documents are relevant to the reader of this
  introduction depends on their role in the documentation process.


  
[1]

  
A writer of documentation has to understand the
      markup language itself. A beginner to doctoc should read the more
      informally written doctoc language introduction first. Having
      digested this the formal doctoc language syntax specification
      should become understandable. A writer experienced with doctoc may only
      need the doctoc language command reference from time to time to
      refresh her memory.
    
 

    While a document is written the dtp application can be used to
      validate it, and after completion it also performs the conversion into the
      chosen system of visual markup, be it *roff, HTML, plain text, wiki, etc.
      The simpler dtplite application makes internal use of doctoc when
      handling directories of documentation, automatically generating a proper
      table of contents for them.





  
[2]

  
A processor of documentation written in the
      doctoc markup language has to know which tools are available for
      use.
    
 

    The main tool is the aforementioned dtp application provided by
      Tcllib. The simpler dtplite does not expose doctoc to the user. At
      the bottom level, common to both applications, however sits the package
      doctoools::toc, providing the basic facilities to read and process
      files containing text in the doctoc format.





  
[3]

  
At last, but not least, plugin writers have to
      understand the interaction between the doctools::toc package and
      its plugins, as described in the doctoc plugin API reference.




RELATED FORMATS

doctoc does not stand alone, it has two companion formats. These are called
  docidx and doctools, and they are for the markup of keyword
  indices, and general documentation, respectively. They are described in
  their own sets of documents, starting at the docidx introduction and
  the doctools introduction, respectively.

BUGS, IDEAS, FEEDBACK

This document, 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.

SEE ALSO

docidx_intro, doctoc_lang_cmdref, doctoc_lang_faq, doctoc_lang_intro,
  doctoc_lang_syntax, doctoc_plugin_apiref, doctools::toc, doctools_intro

KEYWORDS

markup, semantic markup, table of contents, toc

CATEGORY

Documentation tools

COPYRIGHT


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








  

    1.0
    doctools