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

NAME

8       docidx_intro - docidx introduction
9

DESCRIPTION

11       docidx (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 keyword-based indices for documen‐
14       tation. These are
15
16       [1]    A tcl based language for the semantic markup of a keyword index.
17              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  docidx should read the more informally
32              written docidx language introduction first. Having digested this
33              the  formal  docidx  language syntax specification should become
34              understandable. A writer experienced with docidx may  only  need
35              the  docidx  language  command  reference  from  time to time to
36              refresh 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
42              internal use of docidx when handling directories  of  documenta‐
43              tion, automatically generating a proper keyword index for them.
44
45       [2]    A  processor  of documentation written in the docidx 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 docidx to the user.
50              At the bottom level, common to both applications,  however  sits
51              the  package  doctoools::idx,  providing the basic facilities to
52              read and process files containing text in the docidx format.
53
54       [3]    At last, but not least, plugin writers have  to  understand  the
55              interaction  between  the doctools::idx package and its plugins,
56              as described in the docidx plugin API reference.
57
59       docidx does not stand alone, it has two companion  formats.  These  are
60       called  doctoc  and  doctools, and they are for the markup of tables of
61       contents, and general documentation, respectively.  They are  described
62       in their own sets of documents, starting at the doctoc 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_lang_cmdref,         docidx_lang_faq,         docidx_lang_intro,
82       docidx_lang_syntax,  docidx_plugin_apiref, doctoc_intro, doctools::idx,
83       doctools_intro
84

KEYWORDS

86       index, keyword index, markup, semantic markup
87

CATEGORY

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