1doctools::idx(n)              Documentation tools             doctools::idx(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools::idx - docidx - Processing indices
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require doctools::idx  ?1.1?
14
15       ::doctools::idx::new objectName ?-option value ...?
16
17       ::doctools::idx::help
18
19       ::doctools::idx::search path
20
21       objectName method ?arg arg ...?
22
23       objectName configure
24
25       objectName configure option
26
27       objectName configure -option value...
28
29       objectName cget -option
30
31       objectName destroy
32
33       objectName format text
34
35       objectName map symbolic actual
36
37       objectName parameters
38
39       objectName search path
40
41       objectName setparam name value
42
43       objectName warnings
44
45______________________________________________________________________________
46

DESCRIPTION

48       This  package  provides  a  class  for  the creation of objects able to
49       process and convert text written in the docidx markup language into any
50       output format X for which a formatting engine is available.
51
52       A reader interested in the markup language itself should start with the
53       docidx language introduction and proceed from there to the formal spec‐
54       ifications,  i.e.  the  docidx  language syntax and the docidx language
55       command reference.
56
57       If on the other hand the reader wishes to write her own formatting  en‐
58       gine  for  some format, i.e. is a plugin writer then reading and under‐
59       standing the docidx plugin API reference is an absolute  necessity,  as
60       that  document  specifies  the interaction between this package and its
61       plugins, i.e. the formatting engines, in detail.
62

PUBLIC API

64   PACKAGE COMMANDS
65       ::doctools::idx::new objectName ?-option value ...?
66              This command creates a new docidx object with an associated  Tcl
67              command  whose  name  is  objectName. This object command is ex‐
68              plained in full detail in the sections OBJECT COMMAND and OBJECT
69              METHODS.  The  object  command will be created under the current
70              namespace if the objectName is not fully qualified, and  in  the
71              specified namespace otherwise.
72
73              The options and their values coming after the name of the object
74              are used to set the initial configuration of the object.
75
76       ::doctools::idx::help
77              This is a convenience command for applications wishing  to  pro‐
78              vide  their  user with a short description of the available for‐
79              matting commands and their meanings. It returns  a  string  con‐
80              taining a standard help text.
81
82       ::doctools::idx::search path
83              Whenever  an  object  created by this the package has to map the
84              name of a format to the file containing the code for its format‐
85              ting  engine it will search for the file in a number of directo‐
86              ries stored in a list. See section FORMAT MAPPING for  more  ex‐
87              planations.
88
89              This  list not only contains three default directories which are
90              declared by the package itself, but is also extensible  user  of
91              the  package.   This command is the means to do so. When given a
92              path to an existing and readable directory it will prepend  that
93              directory  to the list of directories to search. This means that
94              the path added last is later searched through first.
95
96              An error will be thrown if the path either does  not  exist,  is
97              not a directory, or is not readable.
98
99   OBJECT COMMAND
100       All commands created by ::doctools::idx::new have the following general
101       form and may be used to invoke various operations on their docidx  con‐
102       verter object.
103
104       objectName method ?arg arg ...?
105              The  method method and its arg'uments determine the exact behav‐
106              ior of the command. See section OBJECT METHODS for the  detailed
107              specifications.
108
109   OBJECT METHODS
110       objectName configure
111              The method returns a list of all known options and their current
112              values when called without any arguments.
113
114       objectName configure option
115              The method behaves like the method cget when called with a  sin‐
116              gle  argument  and  returns the value of the option specified by
117              said argument.
118
119       objectName configure -option value...
120              The method reconfigures the specified  options  of  the  object,
121              setting  them to the associated values, when called with an even
122              number of arguments, at least two.
123
124              The legal options are described in the section OBJECT CONFIGURA‐
125              TION.
126
127       objectName cget -option
128              This method expects a legal configuration option as argument and
129              will return the current value of that option for the object  the
130              method was invoked for.
131
132              The  legal configuration options are described in section OBJECT
133              CONFIGURATION.
134
135       objectName destroy
136              This method destroys the object it is invoked for.
137
138       objectName format text
139              This method runs the text through the configured formatting  en‐
140              gine  and  returns  the generated string as its result. An error
141              will be thrown if no -format was configured for the object.
142
143              The method assumes that the text is in docidx format  as  speci‐
144              fied in the companion document docidx_fmt. Errors will be thrown
145              otherwise.
146
147       objectName map symbolic actual
148              This methods add one entry to the per-object mapping  from  sym‐
149              bolic filenames to the actual uris.  The object just stores this
150              mapping and makes it available to the configured formatting  en‐
151              gine  through the command dt_fmap.  This command is described in
152              more detail in the docidx plugin API reference  which  specifies
153              the  interaction between the objects created by this package and
154              index formatting engines.
155
156       objectName parameters
157              This method returns a list containing the names  of  all  engine
158              parameters provided by the configured formatting engine. It will
159              return an empty list if the object is not yet configured  for  a
160              specific format.
161
162       objectName search path
163              This  method  extends  the per-object list of paths searched for
164              index  formatting  engines.  See   also   the   command   ::doc‐
165              tools::idx::search  on  how  to  extend  the per-package list of
166              paths. Note that the path entered last will be  searched  first.
167              For more details see section FORMAT MAPPING.
168
169       objectName setparam name value
170              This  method  sets  the  named engine parameter to the specified
171              value.  It will throw an error if the object is either  not  yet
172              configured  for  a  specific format, or if the formatting engine
173              for the configured format does not provide a parameter with  the
174              given  name.   The list of parameters provided by the configured
175              formatting engine can be retrieved through  the  method  parame‐
176              ters.
177
178       objectName warnings
179              This  method  returns  a  list containing all the warnings which
180              were generated by the configured formatting  engine  during  the
181              last invocation of the method format.
182
183   OBJECT CONFIGURATION
184       All docidx objects understand the following configuration options:
185
186       -file file
187              The  argument  of  this  option is stored in the object and made
188              available to the configured formatting engine through  the  com‐
189              mand  dt_file.   This command is described in more detail in the
190              companion document docidx_api which specifies  the  API  between
191              the object and formatting engines.
192
193              The default value of this option is the empty string.
194
195              The  configured  formatting engine should interpret the value as
196              the name of the file containing the document which is  currently
197              processed.
198
199       -format text
200              The argument of this option specifies the format to generate and
201              by implication the formatting engine to use when converting text
202              via  the  method  format. Its default value is the empty string.
203              The method format cannot be used if this option is not set to  a
204              valid value at least once.
205
206              The package will immediately try to map the given name to a file
207              containing the code for a formatting engine generating that for‐
208              mat. An error will be thrown if this mapping fails. In that case
209              a previously configured format is left untouched.
210
211              The section FORMAT MAPPING explains in detail  how  the  package
212              and object will look for engine implementations.
213
214   FORMAT MAPPING
215       The package and object will perform the following algorithm when trying
216       to map a format name foo to a file containing an  implementation  of  a
217       formatting engine for foo:
218
219       [1]    If  foo  is  the  name of an existing file then this file is di‐
220              rectly taken as the implementation.
221
222       [2]    If not, the list of per-object search  paths  is  searched.  For
223              each  directory in the list the package checks if that directory
224              contains a file "idx.foo". If yes, then that file  is  taken  as
225              the implementation.
226
227              Note  that  this list of paths is initially empty and can be ex‐
228              tended through the object method search.
229
230       [3]    If not, the list of package paths is searched.  For each  direc‐
231              tory in the list the package checks if that directory contains a
232              file "idx.foo". If yes, then that file is taken as the implemen‐
233              tation.
234
235              This  list  of  paths can be extended through the command ::doc‐
236              tools::idx::search.  It contains initially one path, the  subdi‐
237              rectory  "mpformats"  of the directory the package itself is lo‐
238              cated in. In other words, if  the  package  implementation  "do‐
239              cidx.tcl"    is    installed    in   the   directory   "/usr/lo‐
240              cal/lib/tcllib/doctools" then it will by default search the  di‐
241              rectory  "/usr/local/lib/tcllib/doctools/mpformats"  for  format
242              implementations.
243
244       [4]    The mapping fails.
245

PREDEFINED ENGINES

247       The package provides predefined formatting engines  for  the  following
248       formats.  Some  of  the  formatting  engines support engine parameters.
249       These will be explicitly highlighted.
250
251       html   This  engine  generates  HTML  markup,  for  processing  by  web
252              browsers and the like. This engine supports three parameters:
253
254              footer The  value  for  this  parameter has to be valid selfcon‐
255                     tained HTML markup for the body section of a  HTML  docu‐
256                     ment. The default value is the empty string. The value is
257                     inserted  into  the  generated  output  just  before  the
258                     </body> tag, closing the body of the generated HTML.
259
260                     This can be used to insert boilerplate footer markup into
261                     the generated document.
262
263              header The value for this parameter has  to  be  valid  selfcon‐
264                     tained  HTML  markup for the body section of a HTML docu‐
265                     ment. The default value is the empty string. The value is
266                     inserted  into the generated output just after the <body>
267                     tag, starting the body of the generated HTML.
268
269                     This can be used to insert boilerplate header markup into
270                     the generated document.
271
272              meta   The  value  for  this  parameter has to be valid selfcon‐
273                     tained HTML markup for the header section of a HTML docu‐
274                     ment. The default value is the empty string. The value is
275                     inserted into the generated output just after the  <head>
276                     tag, starting the header section of the generated HTML.
277
278                     This  can  be used to insert boilerplate meta data markup
279                     into  the  generated  document,  like  references  to   a
280                     stylesheet, standard meta keywords, etc.
281
282
283       latex  This engine generates output suitable for the latex text proces‐
284              sor coming out of the TeX world.
285
286       list   This engine retrieves version, section and title of the  manpage
287              from  the  document. As such it can be used to generate a direc‐
288              tory listing for a set of manpages.
289
290       markdown
291              This engine generates Markdown markup.
292
293       nroff  This engine generates nroff output, for processing by nroff,  or
294              groff.  The  result will be standard man pages as they are known
295              in the unix world.
296
297       null   This engine generates no outout at all. This can be used if  one
298              just wants to validate some input.
299
300       tmml   This  engine  generates TMML markup as specified by Joe English.
301              The Tcl Manpage Markup Language is a derivate of XML.
302
303       wiki   This engine generates Wiki markup as understood by  Jean  Claude
304              Wippler's wikit application.
305

BUGS, IDEAS, FEEDBACK

307       This  document,  and the package it describes, will undoubtedly contain
308       bugs and other problems.  Please report such in the  category  doctools
309       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
310       also report any ideas for enhancements you may have for either  package
311       and/or documentation.
312
313       When proposing code changes, please provide unified diffs, i.e the out‐
314       put of diff -u.
315
316       Note further that  attachments  are  strongly  preferred  over  inlined
317       patches.  Attachments  can  be  made  by  going to the Edit form of the
318       ticket immediately after its creation, and  then  using  the  left-most
319       button in the secondary navigation bar.
320

SEE ALSO

322       docidx_intro,  docidx_lang_cmdref,  docidx_lang_intro, docidx_lang_syn‐
323       tax, docidx_plugin_apiref
324

KEYWORDS

326       HTML, TMML, conversion, docidx, documentation,  index,  keyword  index,
327       latex, manpage, markdown, markup, nroff, wiki
328

CATEGORY

330       Documentation tools
331
333       Copyright (c) 2003-2019 Andreas Kupries <andreas_kupries@users.sourceforge.net>
334
335
336
337
338tcllib                                1.1                     doctools::idx(n)
Impressum