1doctoc_intro(n)               Documentation tools              doctoc_intro(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctoc_intro - doctoc introduction
9

DESCRIPTION

11       doctoc (short for documentation tables of contents) stands for a set of
12       related, yet different, entities which are  working  together  for  the
13       easy  creation  and transformation of tables of contents for documenta‐
14       tion. These are
15
16       [1]    A tcl based language for the semantic markup of a table of  con‐
17              tents. Markup is represented by Tcl commands.
18
19       [2]    A  package  providing  the  ability  to read and transform texts
20              written in that markup language. It is important  to  note  that
21              the  actual  transformation  of  the  input text is delegated to
22              plugins.
23
24       [3]    An API describing the interface between the package above and  a
25              plugin.
26
27       Which of the more detailed documents are relevant to the reader of this
28       introduction depends on their role in the documentation process.
29
30       [1]    A writer of documentation has to understand the markup  language
31              itself.  A  beginner  to  doctoc should read the more informally
32              written doctoc language introduction first. Having digested this
33              the  formal  doctoc  language syntax specification should become
34              understandable. A writer experienced with doctoc may  only  need
35              the  doctoc  language command reference from time to time to re‐
36              fresh her memory.
37
38              While a document is written the dtp application can be  used  to
39              validate  it,  and after completion it also performs the conver‐
40              sion into the chosen system of visual markup, be it *roff, HTML,
41              plain text, wiki, etc. The simpler dtplite application makes in‐
42              ternal use of doctoc when handling directories of documentation,
43              automatically generating a proper table of contents for them.
44
45       [2]    A  processor  of documentation written in the doctoc markup lan‐
46              guage has to know which tools are available for use.
47
48              The main tool is the aforementioned dtp application provided  by
49              Tcllib.  The simpler dtplite does not expose doctoc to the user.
50              At the bottom level, common to both applications,  however  sits
51              the  package  doctoools::toc,  providing the basic facilities to
52              read and process files containing text in the doctoc format.
53
54       [3]    At last, but not least, plugin writers have  to  understand  the
55              interaction  between  the doctools::toc package and its plugins,
56              as described in the doctoc plugin API reference.
57
59       doctoc does not stand alone, it has two companion  formats.  These  are
60       called  docidx and doctools, and they are for the markup of keyword in‐
61       dices, and general documentation, respectively.  They are described  in
62       their  own  sets  of documents, starting at the docidx introduction and
63       the doctools introduction, respectively.
64

BUGS, IDEAS, FEEDBACK

66       This document, and the package it describes, will  undoubtedly  contain
67       bugs  and  other problems.  Please report such in the category doctools
68       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
69       also  report any ideas for enhancements you may have for either package
70       and/or documentation.
71
72       When proposing code changes, please provide unified diffs, i.e the out‐
73       put of diff -u.
74
75       Note  further  that  attachments  are  strongly  preferred over inlined
76       patches. Attachments can be made by going  to  the  Edit  form  of  the
77       ticket  immediately  after  its  creation, and then using the left-most
78       button in the secondary navigation bar.
79

SEE ALSO

81       docidx_intro, doctoc_lang_cmdref,  doctoc_lang_faq,  doctoc_lang_intro,
82       doctoc_lang_syntax, doctoc_plugin_apiref, doctools::toc, doctools_intro
83

KEYWORDS

85       markup, semantic markup, table of contents, toc
86

CATEGORY

88       Documentation tools
89
91       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
92
93
94
95
96tcllib                                1.0                      doctoc_intro(n)
Impressum