1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin doctools::idx n 1.0.4] 3[copyright {2003-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Documentation tools}] 5[titledesc {docidx - Processing indices}] 6[category {Documentation tools}] 7[require Tcl 8.2] 8[require doctools::idx [opt 1.0.4]] 9[description] 10 11This package provides a class for the creation of objects able to 12process and convert text written in the [term docidx] markup language 13into any output format X for which a [term {formatting engine}] is 14available. 15 16[para] 17 18A reader interested in the markup language itself should start with 19the [term {docidx language introduction}] and proceed from there to 20the formal specifications, i.e. the [term {docidx language syntax}] 21and the [term {docidx language command reference}]. 22 23[para] 24 25If on the other hand the reader wishes to write her own formatting 26engine for some format, i.e. is a [term {plugin writer}] then reading 27and understanding the [term {docidx plugin API reference}] is an 28absolute necessity, as that document specifies the interaction between 29this package and its plugins, i.e. the formatting engines, in detail. 30 31 32[section {PUBLIC API}] 33[subsection {PACKAGE COMMANDS}] 34 35[list_begin definitions] 36 37[call [cmd ::doctools::idx::new] [arg objectName] [opt "[option -option] [arg value] ..."]] 38 39This command creates a new docidx object with an associated Tcl 40command whose name is [arg objectName]. This [term object] command is 41explained in full detail in the sections [sectref {OBJECT COMMAND}] 42and [sectref {OBJECT METHODS}]. The object command will be created 43under the current namespace if the [arg objectName] is not fully 44qualified, and in the specified namespace otherwise. 45 46[para] 47 48The options and their values coming after the name of the object are 49used to set the initial configuration of the object. 50 51 52[call [cmd ::doctools::idx::help]] 53 54This is a convenience command for applications wishing to provide 55their user with a short description of the available formatting 56commands and their meanings. It returns a string containing a standard 57help text. 58 59 60[call [cmd ::doctools::idx::search] [arg path]] 61 62Whenever an object created by this the package has to map the name of 63a format to the file containing the code for its formatting engine it 64will search for the file in a number of directories stored in a 65list. See section [sectref {FORMAT MAPPING}] for more explanations. 66 67[para] 68 69This list not only contains three default directories which are 70declared by the package itself, but is also extensible user of the 71package. 72 73This command is the means to do so. When given a [arg path] to an 74existing and readable directory it will prepend that directory to the 75list of directories to search. This means that the [arg path] added 76last is later searched through first. 77 78[para] 79 80An error will be thrown if the [arg path] either does not exist, is 81not a directory, or is not readable. 82 83[list_end] 84 85 86[subsection {OBJECT COMMAND}] 87 88All commands created by [cmd ::doctools::idx::new] have the following 89general form and may be used to invoke various operations on their 90docidx converter object. 91 92[list_begin definitions] 93 94[call [cmd objectName] [method method] [opt [arg "arg arg ..."]]] 95 96The method [method method] and its [arg arg]'uments determine the exact 97behavior of the command. See section [sectref {OBJECT METHODS}] for 98the detailed specifications. 99 100[list_end] 101 102 103[subsection {OBJECT METHODS}] 104 105[list_begin definitions] 106 107[call [arg objectName] [method configure]] 108 109The method returns a list of all known options and their current 110values when called without any arguments. 111 112 113[call [arg objectName] [method configure] [arg option]] 114 115The method behaves like the method [method cget] when called with a 116single argument and returns the value of the option specified by said 117argument. 118 119 120[call [arg objectName] [method configure] [option -option] [arg value]...] 121 122The method reconfigures the specified [option option]s of the object, 123setting them to the associated [arg value]s, when called with an even 124number of arguments, at least two. 125 126[para] 127 128The legal options are described in the section 129[sectref {OBJECT CONFIGURATION}]. 130 131 132[call [arg objectName] [method cget] [option -option]] 133 134This method expects a legal configuration option as argument and will 135return the current value of that option for the object the method was 136invoked for. 137 138[para] 139 140The legal configuration options are described in section 141[sectref {OBJECT CONFIGURATION}]. 142 143 144[call [arg objectName] [method destroy]] 145 146This method destroys the object it is invoked for. 147 148 149[call [arg objectName] [method format] [arg text]] 150 151This method runs the [arg text] through the configured formatting 152engine and returns the generated string as its result. An error will 153be thrown if no [option -format] was configured for the object. 154 155[para] 156 157The method assumes that the [arg text] is in [term docidx] format as 158specified in the companion document [term docidx_fmt]. Errors will be 159thrown otherwise. 160 161 162[call [arg objectName] [method map] [arg symbolic] [arg actual]] 163 164This methods add one entry to the per-object mapping from 165[arg symbolic] filenames to the [arg actual] uris. 166 167The object just stores this mapping and makes it available to the 168configured formatting engine through the command [cmd dt_fmap]. 169 170This command is described in more detail in the 171[term {docidx plugin API reference}] which specifies the interaction 172between the objects created by this package and index formatting 173engines. 174 175 176[call [arg objectName] [method parameters]] 177 178This method returns a list containing the names of all engine 179parameters provided by the configured formatting engine. It will 180return an empty list if the object is not yet configured for a 181specific format. 182 183 184[call [arg objectName] [method search] [arg path]] 185 186This method extends the per-object list of paths searched for index 187formatting engines. See also the command [cmd ::doctools::idx::search] 188on how to extend the per-package list of paths. Note that the path 189entered last will be searched first. 190 191For more details see section [sectref {FORMAT MAPPING}]. 192 193 194[call [arg objectName] [method setparam] [arg name] [arg value]] 195 196This method sets the [arg name]d engine parameter to the specified 197[arg value]. 198 199It will throw an error if the object is either not yet configured for 200a specific format, or if the formatting engine for the configured 201format does not provide a parameter with the given [arg name]. 202 203The list of parameters provided by the configured formatting engine 204can be retrieved through the method [method parameters]. 205 206 207[call [arg objectName] [method warnings]] 208 209This method returns a list containing all the warnings which were 210generated by the configured formatting engine during the last 211invocation of the method [method format]. 212 213[list_end] 214 215 216[subsection {OBJECT CONFIGURATION}] 217 218All docidx objects understand the following configuration options: 219 220[list_begin options] 221 222[opt_def -file [arg file]] 223 224The argument of this option is stored in the object and made available 225to the configured formatting engine through the command [cmd dt_file]. 226 227This command is described in more detail in the companion document 228[term docidx_api] which specifies the API between the object and 229formatting engines. 230 231[para] 232 233The default value of this option is the empty string. 234 235[para] 236 237The configured formatting engine should interpret the value as the 238name of the file containing the document which is currently processed. 239 240 241[opt_def -format [arg text]] 242 243The argument of this option specifies the format to generate and by 244implication the formatting engine to use when converting text via the 245method [method format]. Its default value is the empty string. The 246method [method format] cannot be used if this option is not set to a 247valid value at least once. 248 249[para] 250 251The package will immediately try to map the given name to a file 252containing the code for a formatting engine generating that format. An 253error will be thrown if this mapping fails. In that case a previously 254configured format is left untouched. 255 256[para] 257 258The section [sectref {FORMAT MAPPING}] explains in detail how the 259package and object will look for engine implementations. 260 261[list_end] 262 263 264[subsection {FORMAT MAPPING}] 265 266The package and object will perform the following algorithm when 267trying to map a format name [term foo] to a file containing an 268implementation of a formatting engine for [term foo]: 269 270[list_begin enumerated] 271[enum] 272 273If [term foo] is the name of an existing file then this file is 274directly taken as the implementation. 275 276[enum] 277 278If not, the list of per-object search paths is searched. For each 279directory in the list the package checks if that directory contains a 280file [file idx.[term foo]]. If yes, then that file is taken as the 281implementation. 282 283[para] 284 285Note that this list of paths is initially empty and can be extended 286through the object method [method search]. 287 288[enum] 289 290If not, the list of package paths is searched. 291 292For each directory in the list the package checks if that directory 293contains a file [file idx.[term foo]]. If yes, then that file is taken 294as the implementation. 295 296[para] 297 298This list of paths can be extended 299through the command [cmd ::doctools::idx::search]. 300 301It contains initially one path, the subdirectory [file mpformats] of 302the directory the package itself is located in. In other words, if the 303package implementation [file docidx.tcl] is installed in the directory 304[file /usr/local/lib/tcllib/doctools] then it will by default search 305the directory [file /usr/local/lib/tcllib/doctools/mpformats] for 306format implementations. 307 308[enum] 309 310The mapping fails. 311 312[list_end] 313 314 315[section {PREDEFINED ENGINES}] 316 317The package provides predefined formatting engines for the following 318formats. Some of the formatting engines support engine 319parameters. These will be explicitly highlighted. 320 321[list_begin definitions] 322[def html] 323 324This engine generates HTML markup, for processing by web browsers and 325the like. This engine supports three parameters: 326 327[list_begin definitions] 328[def footer] 329 330The value for this parameter has to be valid selfcontained HTML markup 331for the body section of a HTML document. The default value is the 332empty string. The value is inserted into the generated output just 333before the [const </body>] tag, closing the body of the generated 334HTML. 335 336[para] 337 338This can be used to insert boilerplate footer markup into the 339generated document. 340 341[def header] 342 343The value for this parameter has to be valid selfcontained HTML markup 344for the body section of a HTML document. The default value is the 345empty string. The value is inserted into the generated output just 346after the [const <body>] tag, starting the body of the generated HTML. 347 348[para] 349 350This can be used to insert boilerplate header markup into the 351generated document. 352 353 354[def meta] 355 356The value for this parameter has to be valid selfcontained HTML markup 357for the header section of a HTML document. The default value is the 358empty string. The value is inserted into the generated output just 359after the [const <head>] tag, starting the header section of the 360generated HTML. 361 362[para] 363 364This can be used to insert boilerplate meta data markup into the 365generated document, like references to a stylesheet, standard meta 366keywords, etc. 367 368[list_end] 369[para] 370 371[def latex] 372 373This engine generates output suitable for the [syscmd latex] text 374processor coming out of the TeX world. 375 376[def list] 377 378This engine retrieves version, section and title of the manpage from 379the document. As such it can be used to generate a directory listing 380for a set of manpages. 381 382[def nroff] 383 384This engine generates nroff output, for processing by [syscmd nroff], 385or [syscmd groff]. The result will be standard man pages as they are 386known in the unix world. 387 388[def null] 389 390This engine generates no outout at all. This can be used if one just 391wants to validate some input. 392 393[def tmml] 394 395This engine generates TMML markup as specified by Joe English. The Tcl 396Manpage Markup Language is a derivate of XML. 397 398[def wiki] 399 400This engine generates Wiki markup as understood by Jean Claude 401Wippler's [syscmd wikit] application. 402 403[list_end] 404 405 406[section {BUGS, IDEAS, FEEDBACK}] 407 408This document, and the package it describes, will undoubtedly contain 409bugs and other problems. 410 411Please report such in the category [emph doctools] of the 412[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 413 414Please also report any ideas for enhancements you may have for either 415package and/or documentation. 416 417 418[see_also docidx_intro] 419[see_also docidx_lang_intro] 420[see_also docidx_lang_syntax] 421[see_also docidx_lang_cmdref] 422[see_also docidx_plugin_apiref] 423[keywords documentation manpage TMML HTML nroff conversion markup] 424[keywords nroff latex wiki docidx index {keyword index}] 425[manpage_end] 426