1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin doctools n 1.4.10] 3[copyright {2003-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Documentation tools}] 5[titledesc {doctools - Processing documents}] 6[category {Documentation tools}] 7[require Tcl 8.2] 8[require doctools [opt 1.4.10]] 9[description] 10 11This package provides a class for the creation of objects able to 12process and convert text written in the [term doctools] markup 13language into any output format X for which a 14[term {formatting engine}] is available. 15 16[para] 17 18A reader interested in the markup language itself should start with 19the [term {doctools language introduction}] and proceed from there to 20the formal specifications, i.e. the [term {doctools language syntax}] 21and the [term {doctools 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 {doctools 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::new] [arg objectName] [opt [arg "option value"]...]] 38 39This command creates a new doctools 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::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::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::new] have the following 89general form and may be used to invoke various operations on their 90doctools 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[subsection {OBJECT METHODS}] 103 104[list_begin definitions] 105 106[call [arg objectName] [method configure]] 107 108The method returns a list of all known options and their current 109values when called without any arguments. 110 111 112[call [arg objectName] [method configure] [arg option]] 113 114The method behaves like the method [method cget] when called with a 115single argument and returns the value of the option specified by said 116argument. 117 118 119[call [arg objectName] [method configure] [option -option] [arg value]...] 120 121The method reconfigures the specified [option option]s of the object, 122setting them to the associated [arg value]s, when called with an even 123number of arguments, at least two. 124 125[para] 126 127The legal options are described in the section 128[sectref {OBJECT CONFIGURATION}]. 129 130 131[call [arg objectName] [method cget] [option -option]] 132 133This method expects a legal configuration option as argument and will 134return the current value of that option for the object the method was 135invoked for. 136 137[para] 138 139The legal configuration options are described in section 140[sectref {OBJECT CONFIGURATION}]. 141 142 143[call [arg objectName] [method destroy]] 144 145This method destroys the object it is invoked for. 146 147 148[call [arg objectName] [method format] [arg text]] 149 150This method runs the [arg text] through the configured formatting 151engine and returns the generated string as its result. An error will 152be thrown if no [option -format] was configured for the object. 153 154[para] 155 156The method assumes that the [arg text] is in [term doctools] format as 157specified in the companion document [term doctools_fmt]. Errors will 158be thrown otherwise. 159 160 161[call [arg objectName] [method map] [arg symbolic] [arg actual]] 162 163This methods add one entry to the per-object mapping from 164[arg symbolic] filenames to the [arg actual] uris. 165 166The object just stores this mapping and makes it available to the 167configured formatting engine through the command [cmd dt_fmap]. 168 169This command is described in more detail in the 170[term {doctools plugin API reference}] which specifies the interaction 171between the objects created by this package and doctools formatting 172engines. 173 174 175[call [arg objectName] [method parameters]] 176 177This method returns a list containing the names of all engine 178parameters provided by the configured formatting engine. It will 179return an empty list if the object is not yet configured for a 180specific format. 181 182 183[call [arg objectName] [method search] [arg path]] 184 185This method extends the per-object list of paths searched for doctools 186formatting engines. See also the command [cmd ::doctools::search] on 187how to extend the per-package list of paths. Note that the path 188entered last will be searched first. 189 190For more details see section [sectref {FORMAT MAPPING}]. 191 192 193[call [arg objectName] [method setparam] [arg name] [arg value]] 194 195This method sets the [arg name]d engine parameter to the specified 196[arg value]. 197 198It will throw an error if the object is either not yet configured for 199a specific format, or if the formatting engine for the configured 200format does not provide a parameter with the given [arg name]. 201 202The list of parameters provided by the configured formatting engine 203can be retrieved through the method [method parameters]. 204 205 206[call [arg objectName] [method warnings]] 207 208This method returns a list containing all the warnings which were 209generated by the configured formatting engine during the last 210invocation of the method [method format]. 211 212[list_end] 213 214 215[subsection {OBJECT CONFIGURATION}] 216 217All doctools objects understand the following configuration options: 218 219[list_begin options] 220 221[opt_def -file [arg file]] 222 223The argument of this option is stored in the object and made available 224to the configured formatting engine through the commands [cmd dt_file] 225and [cmd dt_mainfile]. 226 227These commands are described in more detail in the companion document 228[term doctools_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 -module [arg text]] 242 243The argument of this option is stored in the object and made available 244to the configured formatting engine through the command [cmd dt_module]. 245 246This command is described in more detail in the companion document 247[term doctools_api] which specifies the API between the object and 248formatting engines. 249 250[para] 251 252The default value of this option is the empty string. 253 254[para] 255 256The configured formatting engine should interpret the value as the 257name of the module the file containing the document which is currently 258processed belongs to. 259 260 261[opt_def -format [arg text]] 262 263The argument of this option specifies the format to generate and by 264implication the formatting engine to use when converting text via the 265method [method format]. Its default value is the empty string. The 266method [method format] cannot be used if this option is not set to a 267valid value at least once. 268 269[para] 270 271The package will immediately try to map the given name to a file 272containing the code for a formatting engine generating that format. An 273error will be thrown if this mapping fails. In that case a previously 274configured format is left untouched. 275 276[para] 277 278The section [sectref {FORMAT MAPPING}] explains in detail how the 279package and object will look for engine implementations. 280 281 282[opt_def -deprecated [arg boolean]] 283 284This option is a boolean flag. The object will generate warnings if 285this flag is set and the text given to method [method format] contains 286the deprecated markup command [cmd strong]. 287 288Its default value is [const FALSE]. In other words, no warnings will 289be generated. 290 291 292[opt_def -copyright [arg text]] 293 294The argument of this option is stored in the object and made available 295to the configured formatting engine through the command [cmd dt_copyright]. 296 297 298This command is described in more detail in the companion document 299[term doctools_api] which specifies the API between the object and 300formatting engines. 301 302[para] 303 304The default value of this option is the empty string. 305 306[para] 307 308The configured formatting engine should interpret the value as a 309copyright assignment for the document which is currently processed, or 310the package described by it. 311 312[para] 313 314This information must be used if and only if the engine is unable to 315find any copyright assignments within the document itself. Such are 316specified by the formatting command [cmd copyright]. This command is 317described in more detail in the companion document [term doctools_fmt] 318which specifies the [term doctools] format itself. 319 320 321[list_end] 322 323[subsection {FORMAT MAPPING}] 324 325The package and object will perform the following algorithm when 326trying to map a format name [term foo] to a file containing an 327implementation of a formatting engine for [term foo]: 328 329[list_begin enumerated] 330[enum] 331 332If [term foo] is the name of an existing file then this file is 333directly taken as the implementation. 334 335[enum] 336 337If not, the list of per-object search paths is searched. For each 338directory in the list the package checks if that directory contains a 339file [file fmt.[term foo]]. If yes, then that file is taken as the 340implementation. 341 342[para] 343 344Note that this list of paths is initially empty and can be extended 345through the object method [method search]. 346 347[enum] 348 349If not, the list of package paths is searched. 350 351For each directory in the list the package checks if that directory 352contains a file [file fmt.[term foo]]. If yes, then that file is taken 353as the implementation. 354 355[para] 356 357This list of paths can be extended 358through the command [cmd ::doctools::search]. 359 360It contains initially one path, the subdirectory [file mpformats] of 361the directory the package itself is located in. 362 363In other words, if the package implementation [file doctools.tcl] is 364installed in the directory [file /usr/local/lib/tcllib/doctools] then 365it will by default search the 366 367directory [file /usr/local/lib/tcllib/doctools/mpformats] for format 368implementations. 369 370[enum] 371 372The mapping fails. 373 374[list_end] 375 376 377[section {PREDEFINED ENGINES}] 378 379The package provides predefined engines for the following 380formats. Some of the engines support parameters. These will be 381explained below as well. 382 383[list_begin definitions] 384[def html] 385 386This engine generates HTML markup, for processing by web browsers and 387the like. This engine supports four parameters: 388 389[list_begin definitions] 390[def footer] 391 392The value for this parameter has to be valid selfcontained HTML markup 393for the body section of a HTML document. The default value is the 394empty string. The value is inserted into the generated output just 395before the [const </body>] tag, closing the body of the generated 396HTML. 397 398[para] 399 400This can be used to insert boilerplate footer markup into the 401generated document. 402 403[def header] 404 405The value for this parameter has to be valid selfcontained HTML markup 406for the body section of a HTML document. The default value is the 407empty string. The value is inserted into the generated output just 408after the [const <body>] tag, starting the body of the generated HTML. 409 410[para] 411 412This can be used to insert boilerplate header markup into the 413generated document. 414 415 416[def meta] 417 418The value for this parameter has to be valid selfcontained HTML markup 419for the header section of a HTML document. The default value is the 420empty string. The value is inserted into the generated output just 421after the [const <head>] tag, starting the header section of the 422generated HTML. 423 424[para] 425 426This can be used to insert boilerplate meta data markup into the 427generated document, like references to a stylesheet, standard meta 428keywords, etc. 429 430 431[def xref] 432 433The value for this parameter has to be a list of triples specifying 434cross-reference information. This information is used by the engine to 435create more hyperlinks. Each triple is a list containing a pattern, 436symbolic filename and fragment reference, in this order. If a pattern 437is specified multiple times the last occurence of the pattern will be 438used. 439 440[para] 441 442The engine will consult the xref database when encountering specific 443commands and will create a link if the relevant text matches one of 444the patterns. No link will be created if no match was found. The link 445will go to the uri [const {file#fragment}] listed in the relevant 446triple, after conversion of the symbolic file name to the actual uri 447via [cmd dt_fmap] (see the [term {doctools plugin API reference}]). 448 449This file-to-uri mapping was build by calls to the method [method map] 450of the doctools object (See section [sectref {OBJECT METHODS}]). 451 452[para] 453 454The following formatting commands will consult the xref database: 455 456[list_begin definitions] 457[def "[cmd cmd] [arg word]"] 458 459The command will look for the patterns [const sa,][arg word], and 460[arg word], in this order. If this fails if it will convert [arg word] 461to all lowercase and try again. 462 463 464[def "[cmd syscmd] [arg word]"] 465 466The command will look for the patterns [const sa,][arg word], and 467[arg word], in this order. If this fails if it will convert [arg word] 468to all lowercase and try again. 469 470 471[def "[cmd term] [arg word]"] 472 473The command will look for the patterns [const kw,][arg word], 474[const sa,][arg word], and [arg word], in this order. If this fails if 475it will convert [arg word] to all lowercase and try again. 476 477 478[def "[cmd package] [arg word]"] 479 480The command will look for the patterns [const sa,][arg word], 481[const kw,][arg word], and [arg word], in this order. If this fails if 482it will convert [arg word] to all lowercase and try again. 483 484 485[def "[cmd see_also] [arg word]..."] 486 487The command will look for the patterns [const sa,][arg word], and 488[arg word], in this order, for each [arg word] given to the 489command. If this fails if it will convert [arg word] to all lowercase 490and try again. 491 492 493[def "[cmd keywords] [arg word]..."] 494 495The command will look for the patterns [const kw,][arg word], and 496[arg word], in this order, for each [arg word] given to the 497command. If this fails if it will convert [arg word] to all lowercase 498and try again. 499 500 501[list_end] 502[list_end] 503[para] 504 505[def latex] 506 507This engine generates output suitable for the [syscmd latex] text 508processor coming out of the TeX world. 509 510[def list] 511 512This engine retrieves version, section and title of the manpage from 513the document. As such it can be used to generate a directory listing 514for a set of manpages. 515 516[def nroff] 517 518This engine generates nroff output, for processing by [syscmd nroff], 519or [syscmd groff]. The result will be standard man pages as they are 520known in the unix world. 521 522[def null] 523 524This engine generates no outout at all. This can be used if one just 525wants to validate some input. 526 527[def tmml] 528 529This engine generates TMML markup as specified by Joe English. The Tcl 530Manpage Markup Language is a derivate of XML. 531 532[def wiki] 533 534This engine generates Wiki markup as understood by Jean Claude 535Wippler's [syscmd wikit] application. 536 537[list_end] 538 539 540[section {BUGS, IDEAS, FEEDBACK}] 541 542This document, and the package it describes, will undoubtedly contain 543bugs and other problems. 544 545Please report such in the category [emph doctools] of the 546[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 547 548Please also report any ideas for enhancements you may have for either 549package and/or documentation. 550 551 552[see_also doctools_intro] 553[see_also doctools_lang_intro] 554[see_also doctools_lang_syntax] 555[see_also doctools_lang_cmdref] 556[see_also doctools_plugin_apiref] 557[keywords documentation manpage TMML HTML nroff conversion markup] 558[manpage_end] 559