<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>doctoc_intro - Documentation tools</title>
<style type="text/css"><!--
HTML {
background: #FFFFFF;
color: black;
}
BODY {
background: #FFFFFF;
color: black;
}
DIV.doctools {
margin-left: 10%;
margin-right: 10%;
}
DIV.doctools H1,DIV.doctools H2 {
margin-left: -5%;
}
H1, H2, H3, H4 {
margin-top: 1em;
font-family: sans-serif;
font-size: large;
color: #005A9C;
background: transparent;
text-align: left;
}
H1.doctools_title {
text-align: center;
}
UL,OL {
margin-right: 0em;
margin-top: 3pt;
margin-bottom: 3pt;
}
UL LI {
list-style: disc;
}
OL LI {
list-style: decimal;
}
DT {
padding-top: 1ex;
}
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
font: normal 12pt/14pt sans-serif;
list-style: none;
}
LI.doctools_section, LI.doctools_subsection {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
PRE {
display: block;
font-family: monospace;
white-space: pre;
margin: 0%;
padding-top: 0.5ex;
padding-bottom: 0.5ex;
padding-left: 1ex;
padding-right: 1ex;
width: 100%;
}
PRE.doctools_example {
color: black;
background: #f5dcb3;
border: 1px solid black;
}
UL.doctools_requirements LI, UL.doctools_syntax LI {
list-style: none;
margin-left: 0em;
text-indent: 0em;
padding: 0em;
}
DIV.doctools_synopsis {
color: black;
background: #80ffff;
border: 1px solid black;
font-family: serif;
margin-top: 1em;
margin-bottom: 1em;
}
UL.doctools_syntax {
margin-top: 1em;
border-top: 1px solid black;
}
UL.doctools_requirements {
margin-bottom: 1em;
border-bottom: 1px solid black;
}
--></style>
</head>
<!-- Generated from file 'doctoc_intro.man' by tcllib/doctools with format 'html'
-->
<!-- Copyright &copy; 2007 Andreas Kupries &lt;[email protected]&gt;
-->
<!-- doctoc_intro.n
-->
<body><hr> [
<a href="../../../../../../../../home">Tcllib Home</a>
| <a href="../../../../toc.html">Main Table Of Contents</a>
| <a href="../../../toc.html">Table Of Contents</a>
| <a href="../../../../index.html">Keyword Index</a>
| <a href="../../../../toc0.html">Categories</a>
| <a href="../../../../toc1.html">Modules</a>
| <a href="../../../../toc2.html">Applications</a>
] <hr>
<div class="doctools">
<h1 class="doctools_title">doctoc_intro(n) 1.0 tcllib "Documentation tools"</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>doctoc_intro - doctoc introduction</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#section1">Description</a></li>
<li class="doctools_section"><a href="#section2">RELATED FORMATS</a></li>
<li class="doctools_section"><a href="#section3">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#see-also">See Also</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p><i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i> (short for <em>documentation tables of contents</em>)
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</p>
<ol class="doctools_enumerated">
<li><p>A tcl based language for the semantic markup of a table of
contents. Markup is represented by Tcl commands.</p></li>
<li><p>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.</p></li>
<li><p>An API describing the interface between the package above and a
plugin.</p></li>
</ol>
<p>Which of the more detailed documents are relevant to the reader of
this introduction depends on their role in the documentation process.</p>
<ol class="doctools_enumerated">
<li><p>A <i class="term">writer</i> of documentation has to understand the markup language
itself. A beginner to doctoc should read the more informally written
<i class="term"><a href="doctoc_lang_intro.html">doctoc language introduction</a></i> first. Having digested this
the formal <i class="term"><a href="doctoc_lang_syntax.html">doctoc language syntax</a></i> specification should
become understandable. A writer experienced with doctoc may only
need the <i class="term"><a href="doctoc_lang_cmdref.html">doctoc language command reference</a></i> from time to
time to refresh her memory.</p>
<p>While a document is written the <b class="syscmd">dtp</b> 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 <b class="syscmd"><a href="../../apps/dtplite.html">dtplite</a></b> application makes
internal use of doctoc when handling directories of documentation,
automatically generating a proper table of contents for them.</p></li>
<li><p>A <i class="term">processor</i> of documentation written in the <i class="term"><a href="../../../../index.html#doctoc">doctoc</a></i>
markup language has to know which tools are available for use.</p>
<p>The main tool is the aforementioned <b class="syscmd">dtp</b> application provided
by Tcllib. The simpler <b class="syscmd"><a href="../../apps/dtplite.html">dtplite</a></b> does not expose doctoc to the
user.
At the bottom level, common to both applications, however sits the
package <b class="package">doctoools::toc</b>, providing the basic facilities to
read and process files containing text in the doctoc format.</p></li>
<li><p>At last, but not least, <i class="term">plugin writers</i> have to understand the
interaction between the <b class="package"><a href="doctoc.html">doctools::toc</a></b> package and its
plugins, as described in the <i class="term"><a href="doctoc_plugin_apiref.html">doctoc plugin API reference</a></i>.</p></li>
</ol>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">RELATED FORMATS</a></h2>
<p>doctoc does not stand alone, it has two companion formats. These are
called <i class="term"><a href="../../../../index.html#docidx">docidx</a></i> and <i class="term"><a href="../../../../index.html#doctools">doctools</a></i>, and they are for the markup
of <i class="term">keyword indices</i>, and general documentation, respectively.
They are described in their own sets of documents, starting at the
<i class="term"><a href="docidx_intro.html">docidx introduction</a></i> and the <i class="term"><a href="doctools_intro.html">doctools introduction</a></i>,
respectively.</p>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>doctools</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="see-also" class="doctools_section"><h2><a name="see-also">See Also</a></h2>
<p><a href="docidx_intro.html">docidx_intro</a>, <a href="doctoc_lang_cmdref.html">doctoc_lang_cmdref</a>, <a href="doctoc_lang_faq.html">doctoc_lang_faq</a>, <a href="doctoc_lang_intro.html">doctoc_lang_intro</a>, <a href="doctoc_lang_syntax.html">doctoc_lang_syntax</a>, <a href="doctoc_plugin_apiref.html">doctoc_plugin_apiref</a>, <a href="doctoc.html">doctools::toc</a>, <a href="doctools_intro.html">doctools_intro</a></p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#markup">markup</a>, <a href="../../../../index.html#semantic_markup">semantic markup</a>, <a href="../../../../index.html#table_of_contents">table of contents</a>, <a href="../../../../index.html#toc">toc</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Documentation tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright © 2007 Andreas Kupries <[email protected]></p>
</div>
</div></body></html>
