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

NAME

8       doctools2idx_introduction - DocTools - Keyword indices
9

DESCRIPTION

11       docidx  (short  for documentation indices) stands for a set of related,
12       yet different, entities which are working together for  the  easy  cre‐
13       ation and transformation of keyword indices for documentation.
14
15       These are
16
17       [1]    A tcl based language for the semantic markup of a keyword index.
18              Markup is represented by Tcl commands.  Beginners  should  start
19              with the docidx language introduction.  The formal specification
20              is split over two documents, one dealing with  the  docidx  lan‐
21              guage syntax, the other a docidx language command reference.
22
23       [2]    A  set  of packages for the programmatic manipulation of keyword
24              indices in memory, and their conversion between various formats,
25              reading  and  writing. The aforementioned markup language is one
26              of the formats which can be both read from and written to.
27
28       [3]    The system for the conversion of indices is based  on  a  plugin
29              mechanism,  for  this  we have two APIs describing the interface
30              between the packages above and the import/export plugins.
31
32       Which of the more detailed documents are relevant to the reader of this
33       introduction depends on their role in the documentation process.
34
35       [1]    A  writer of documentation has to understand the markup language
36              itself. A beginner to docidx should  read  the  more  informally
37              written docidx language introduction first. Having digested this
38              the formal docidx language syntax  specification  should  become
39              understandable.  A  writer experienced with docidx may only need
40              the docidx language command reference from time to time  to  re‐
41              fresh her memory.
42
43              While  a  document is written the dtp application can be used to
44              validate it, and after completion it also performs  the  conver‐
45              sion into the chosen system of visual markup, be it *roff, HTML,
46              plain text, wiki, etc. The simpler dtplite application makes in‐
47              ternal use of docidx when handling directories of documentation,
48              automatically generating a proper keyword index for them.
49
50       [2]    A processor of documentation written in the docidx  markup  lan‐
51              guage has to know which tools are available for use.
52
53              The  main tool is the aforementioned dtp application provided by
54              Tcllib. The simpler dtplite does not expose docidx to the  user.
55              At  the  bottom  level,  common to both applications, however we
56              find the three packages providing the basic facilities to handle
57              keyword  indices, i.e. import from textual formats, programmatic
58              manipulation in memory, and export to textual formats. These are
59
60              doctools::idx
61                     Programmatic manipulation of keyword indices in memory.
62
63              doctools::idx::import
64                     Import of keyword indices from various  textual  formats.
65                     The set of supported formats is extensible through plugin
66                     packages.
67
68              doctools::idx::export
69                     Export of keyword indices to various textual formats. The
70                     set  of  supported  formats  is extensible through plugin
71                     packages.
72
73              See also section Package Overview for an overview of the  depen‐
74              dencies between these and other, supporting packages.
75
76       [3]    At  last,  but  not least, plugin writers have to understand the
77              interaction between the import and  export  packages  and  their
78              plugins.   These APIs are described in the documentation for the
79              two relevant packages, i.e.
80
81doctools::idx::import
82
83doctools::idx::export
84
86       The docidx format does not stand alone, it has two  companion  formats.
87       These  are  called  doctoc  and doctools, and they are intended for the
88       markup of tables of contents, and  of  general  documentation,  respec‐
89       tively.  They are described in their own sets of documents, starting at
90       the DocTools - Tables Of Contents and the DocTools -  General,  respec‐
91       tively.
92

PACKAGE OVERVIEW

94                                                  ~~~~~~~~~~~ doctools::idx ~~~~~~~~~~~
95                                                 ~~                   |               ~~
96                              doctools::idx::export ~~~~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~ doctools::idx::import
97                                      |                               |                       |
98                      +---------------+-------------------------+     |    +------------------+---------------+-----------------------+---------------+
99                      |               |                         |     |    |                  |               |                       |               |
100              struct::map             =                         |     |    |                  =       doctools::include       struct::map      fileutil::paths
101                                      |                         |     |    |                  |
102                              doctools::idx::export::<*>        |     |    |          doctools::idx::import::<*>
103                                      docidx                    |     |    |                  docidx, json
104                                      json                      |     |    |                  |           \
105                                      html                      |     |    |          doctools::idx::parse \
106                                      nroff                     |     |    |                  |             \
107                                      wiki                      |     |    |  +---------------+              json
108                                      text                      |     |    |  |               |
109                                                              doctools::idx::structure        |
110                                                                                              |
111                                                                                      +-------+---------------+
112                                                                                      |                       |
113                        doctools::html  doctools::html::cssdefaults           doctools::tcl::parse    doctools::msgcat
114                              |                                                                               |
115                        doctools::text  doctools::nroff::man_macros                                           =
116                                                                                                              |
117                                                                                                      doctools::msgcat::idx::<*>
118                                                                                                              c, en, de, fr
119                                                                                                              (fr == en for now)
120                      ~~      Interoperable objects, without actual package dependencies
121                      --      Package dependency, higher requires lower package
122                      =       Dynamic dependency through plugin system
123                      <*>     Multiple packages following the given form of naming.
124
125
126

BUGS, IDEAS, FEEDBACK

128       This  document,  and the package it describes, will undoubtedly contain
129       bugs and other problems.  Please report such in the  category  doctools
130       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
131       also report any ideas for enhancements you may have for either  package
132       and/or documentation.
133
134       When proposing code changes, please provide unified diffs, i.e the out‐
135       put of diff -u.
136
137       Note further that  attachments  are  strongly  preferred  over  inlined
138       patches.  Attachments  can  be  made  by  going to the Edit form of the
139       ticket immediately after its creation, and  then  using  the  left-most
140       button in the secondary navigation bar.
141

SEE ALSO

143       docidx_intro,  doctoc_intro,  doctools, doctools2doc_introduction, doc‐
144       tools2toc_introduction, doctools_lang_cmdref,  doctools_lang_faq,  doc‐
145       tools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref
146

KEYWORDS

148       conversion,  formatting, index, keyword index, markup, parsing, plugin,
149       semantic markup
150

CATEGORY

152       Documentation tools
153
155       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
156
157
158
159
160tcllib                                2.0         doctools2idx_introduction(n)
Impressum