1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin doctools_lang_cmdref n 1.0] 3[copyright {2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Documentation tools}] 5[titledesc {doctools language command reference}] 6[category {Documentation tools}] 7[description] 8[para] 9 10This document specifies both names and syntax of all the commands 11which together are the doctools markup language, version 1. 12 13As this document is intended to be a reference the commands are listed 14in alphabetical order, and the descriptions are relatively short. 15 16A beginner should read the much more informally written 17[term {doctools language introduction}] first. 18 19 20[section Commands] 21[list_begin definitions] 22 23[call [cmd arg] [arg text]] 24 25Text markup. The argument text is marked up as the [term argument] of 26a command. Main uses are the highlighting of command arguments in 27free-form text, and for the argument parameters of the markup commands 28[cmd call] and [cmd usage]. 29 30[call [cmd arg_def] [arg type] [arg name] [opt [arg mode]]] 31 32Text structure. List element. Argument list. Automatically closes the 33previous list element. Specifies the data-[arg type] of the described 34argument of a command, its [arg name] and its i/o-[arg mode]. The 35latter is optional. 36 37[call [cmd bullet]] 38 39[emph Deprecated]. Text structure. List element. Itemized list. See 40[cmd item] for the canonical command to open a list item in an 41itemized list. 42 43[call [cmd call] [arg args]] 44 45Text structure. List element. Definition list. Automatically closes 46the previous list element. Defines the term as a command and its 47arguments. 48 49The first argument is the name of the command described by the 50following free-form text, and all arguments coming after that are 51descriptions of the command's arguments. 52 53It is expected that the arguments are marked up with [cmd arg], 54[cmd method], [cmd option] etc., as is appropriate, and that the 55command itself is marked up with [cmd cmd]. 56 57It is expected that the formatted term is not only printed in place, 58but also in the table of contents of the document, or synopsis, 59depending on the output format. 60 61 62[call [cmd category] [arg text]] 63 64Document information. Anywhere. This command registers its plain text 65arguments as the category this document belongs to. If this command is 66used multiple times the last value specified is used. 67 68 69[call [cmd class] [arg text]] 70 71Text markup. The argument is marked up as the name of a 72[term class]. The text may have other markup already applied to 73it. Main use is the highlighting of class names in free-form text. 74 75[call [cmd cmd] [arg text]] 76 77Text markup. The argument text is marked up as the name of a 78[term {Tcl command}]. The text may have other markup already applied 79to it. Main uses are the highlighting of commands in free-form text, 80and for the command parameters of the markup commands [cmd call] and 81[cmd usage]. 82 83[call [cmd cmd_def] [arg command]] 84 85Text structure. List element. Command list. Automatically closes the 86previous list element. The argument specifies the name of the 87[term {Tcl command}] to be described by the list element. Expected to 88be marked up in the output as if it had been formatted with [cmd cmd]. 89 90[call [cmd comment] [arg plaintext]] 91 92Text markup. The argument text is marked up as a comment standing 93outside of the actual text of the document. Main use is in free-form 94text. 95 96[call [cmd const] [arg text]] 97 98Text markup. The argument is marked up as a [term constant] value. The 99text may have other markup already applied to it. Main use is the 100highlighting of constants in free-form text. 101 102[call [cmd copyright] [arg text]] 103 104Document information. Anywhere. The command registers the plain text 105argument as a copyright assignment for the manpage. When invoked more 106than once the assignments are accumulated. 107 108[call [cmd def] [arg text]] 109 110Text structure. List element. Definition list. Automatically closes 111the previous list element. The argument text is the term defined by 112the new list element. Text markup can be applied to it. 113 114[call [cmd description]] 115 116Document structure. This command separates the header from the 117document body. Implicitly starts a section named "DESCRIPTION" (See 118command [cmd section]). 119 120[call [cmd enum]] 121 122Text structure. List element. Enumerated list. Automatically closes 123the previous list element. 124 125[call [cmd emph] [arg text]] 126 127Text markup. The argument text is marked up as emphasized. Main use is 128for general highlighting of pieces of free-form text without attaching 129special meaning to the pieces. 130 131[call [cmd example] [arg text]] 132 133Text structure, Text markup. This command marks its argument up as an 134[term example]. Main use is the simple embedding of examples in 135free-form text. It should be used if the example does [emph not] need 136special markup of its own. Otherwise use a sequence of 137[cmd example_begin] ... [cmd example_end]. 138 139[call [cmd example_begin]] 140 141Text structure. This commands starts an example. All text until the 142next [cmd example_end] belongs to the example. Line breaks, spaces, 143and tabs have to be preserved literally. Examples cannot be nested. 144 145[call [cmd example_end]] 146 147Text structure. This command closes the example started by the last 148[cmd example_begin]. 149 150[call [cmd file] [arg text]] 151 152Text markup. The argument is marked up as a [term file] or 153[term directory], i.e. in general a [term path]. The text may have 154other markup already applied to it. Main use is the highlighting of 155paths in free-form text. 156 157[call [cmd fun] [arg text]] 158 159Text markup. The argument is marked up as the name of a 160[term function]. The text may have other markup already applied to 161it. Main use is the highlighting of function names in free-form text. 162 163[call [cmd image] [arg name] [opt [arg label]]] 164 165Text markup. The argument is the symbolic name of an [term image] 166and replaced with the image itself, if a suitable variant is found 167by the backend. The second argument, should it be present, will be 168interpreted the human-readable description of the image, and put 169into the output in a suitable position, if such is supported by the 170format. The HTML format, for example, can place it into the [term alt] 171attribute of image references. 172 173[call [cmd include] [arg filename]] 174 175Templating. The contents of the named file are interpreted as text 176written in the doctools markup and processed in the place of the 177include command. The markup in the file has to be self-contained. It 178is not possible for a markup command to cross the file boundaries. 179 180[call [cmd item]] 181 182Text structure. List element. Itemized list. Automatically closes the 183previous list element. 184 185[call [cmd keywords] [arg args]] 186 187Document information. Anywhere. This command registers all its plain text 188arguments as keywords applying to this document. Each argument is a single 189keyword. If this command is used multiple times all the arguments accumulate. 190 191[call [cmd lb]] 192 193Text. The command is replaced with a left bracket. Use in free-form text. 194Required to avoid interpretation of a left bracket as the start of a markup 195command. 196 197[call [cmd list_begin] [arg what]] 198 199Text structure. This command starts a list. The exact nature of the 200list is determined by the argument [arg what] of the command. This 201further determines which commands are have to be used to start the 202list elements. Lists can be nested, i.e. it is allowed to start a new 203list within a list element. 204 205[para] 206The allowed types (and their associated item commands) are: 207 208[list_begin definitions] 209[def [const arguments]] [cmd arg_def]. 210[def [const commands]] [cmd cmd_def]. 211[def [const definitions]] [cmd def] and [cmd call]. 212[def [const enumerated]] [cmd enum] 213[def [const itemized]] [cmd item] 214[def [const options]] [cmd opt_def] 215[def [const tkoptions]] [cmd tkoption_def] 216[list_end] 217[para] 218 219Additionally the following names are recognized as shortcuts for some 220of the regular types: 221 222[list_begin definitions] 223[def [const args]] Short for [const arguments]. 224[def [const cmds]] Short for [const commands]. 225[def [const enum]] Short for [const enumerated]. 226[def [const item]] Short for [const itemized]. 227[def [const opts]] Short for [const options]. 228[list_end] 229[para] 230 231At last the following names are still recognized for backward 232compatibility, but are otherwise considered to be [emph deprecated]. 233 234[list_begin definitions] 235[def [const arg]] [emph Deprecated]. See [const arguments]. 236[def [const bullet]] [emph Deprecated]. See [const itemized]. 237[def [const cmd]] [emph Deprecated]. See [const commands]. 238[def [const opt]] [emph Deprecated]. See [const options]. 239[def [const tkoption]] [emph Deprecated]. See [const tkoptions]. 240[list_end] 241 242[para] 243 244[call [cmd list_end]] 245 246Text structure. This command closes the list opened by the last 247[cmd list_begin] command coming before it. 248 249[call [cmd lst_item] [arg text]] 250 251[emph Deprecated]. Text structure. List element. Definition list. See 252[cmd def] for the canonical command to open a general list item in a 253definition list. 254 255[call [cmd manpage_begin] [arg command] [arg section] [arg version]] 256 257Document structure. The command to start a manpage. The arguments are 258the name of the [arg command] described by the manpage, the 259[arg section] of the manpages this manpage resides in, and the 260[arg version] of the module containing the command. All arguments have 261to be plain text, without markup. 262 263[call [cmd manpage_end]] 264 265Document structure. Command to end a manpage/document. Anything in the document 266coming after this command is in error. 267 268[call [cmd method] [arg text]] 269 270Text markup. The argument text is marked up as the name of an 271[term object] [term method], i.e. subcommand of a Tcl command. The 272text may have other markup already applied to it. Main uses are the 273highlighting of method names in free-form text, and for the command 274parameters of the markup commands [cmd call] and [cmd usage]. 275 276[call [cmd moddesc] [arg text]] 277 278Document information. Header. Registers the plain text argument as a short 279description of the module the manpage resides in. 280 281[call [cmd namespace] [arg text]] 282 283Text markup. The argument text is marked up as a namespace name. The 284text may have other markup already applied to it. Main use is the 285highlighting of namespace names in free-form text. 286 287[call [cmd nl]] 288 289[emph Deprecated]. Text structure. See [cmd para] for the canonical 290command to insert paragraph breaks into the text. 291 292[call [cmd opt] [arg text]] 293 294Text markup. The argument text is marked up as [term optional]. The text may 295have other markup already applied to it. Main use is the highlighting of 296optional arguments, see the command arg [cmd arg]. 297 298[call [cmd opt_def] [arg name] [opt [arg arg]]] 299 300Text structure. List element. Option list. Automatically closes the 301previous list element. Specifies [arg name] and arguments of the 302[term option] described by the list element. It is expected that the 303name is marked up using [cmd option]. 304 305[call [cmd option] [arg text]] 306 307Text markup. The argument is marked up as [term option]. The text may 308have other markup already applied to it. Main use is the highlighting 309of options, also known as command-switches, in either free-form text, 310or the arguments of the [cmd call] and [cmd usage] commands. 311 312[call [cmd package] [arg text]] 313 314Text markup. The argument is marked up as the name of a 315[term package]. The text may have other markup already applied to 316it. Main use is the highlighting of package names in free-form text. 317 318[call [cmd para]] 319 320Text structure. This command breaks free-form text into 321paragraphs. Each command closes the paragraph coming before it and 322starts a new paragraph for the text coming after it. Higher-level 323forms of structure are sections and subsections. 324 325[call [cmd rb]] 326 327Text. The command is replaced with a right bracket. Use in free-form text. 328Required to avoid interpretation of a right bracket as the end of a markup 329command. 330 331[call [cmd require] [arg package] [opt [arg version]]] 332 333Document information. Header. This command registers its argument 334[arg package] as the name of a package or application required by the 335described package or application. A minimum version can be provided as 336well. This argument can be marked up. The usual markup is [cmd opt]. 337 338[call [cmd section] [arg name]] 339 340Text structure. This command starts a new named document section. The 341argument has to be plain text. Implicitly closes the last paragraph 342coming before it and also implicitly opens the first paragraph of the 343new section. 344 345[call [cmd sectref] [arg id] [opt [arg text]]] 346 347Text markup. Formats a reference to the section identified by [arg id]. 348If no [arg text] is specified the title of the referenced section is 349used in the output, otherwise [arg text] is used. 350 351[call [cmd sectref-external] [arg text]] 352 353Text markup. Like [cmd sectref], except that the section is assumed to 354be in a different document and therefore doesn't need to be identified, 355nor are any checks for existence made. Only the text to format is needed. 356 357 358[call [cmd see_also] [arg args]] 359 360Document information. Anywhere. The command defines direct cross-references 361to other documents. Each argument is a plain text label identifying the 362referenced document. If this command is used multiple times all the arguments 363accumulate. 364 365[call [cmd strong] [arg text]] 366 367[emph Deprecated]. Text markup. See [cmd emph] for the canonical 368command to emphasize text. 369 370[call [cmd subsection] [arg name]] 371 372Text structure. This command starts a new named subsection of a 373section. The argument has to be plain text. Implicitly closes the last 374paragraph coming before it and also implicitly opens the first 375paragraph of the new subsection. 376 377[call [cmd syscmd] [arg text]] 378 379Text markup. The argument text is marked up as the name of an external 380command. The text may have other markup already applied to it. Main 381use is the highlighting of external commands in free-form text. 382 383[call [cmd term] [arg text]] 384 385Text markup. The argument is marked up as unspecific terminology. The 386text may have other markup already applied to it. Main use is the 387highlighting of important terms and concepts in free-form text. 388 389[call [cmd titledesc] [arg desc]] 390 391Document information. Header. Optional. Registers the plain text 392argument as the title of the manpage. Defaults to the value registered 393by [cmd moddesc]. 394 395[call [cmd tkoption_def] [arg name] [arg dbname] [arg dbclass]] 396 397Text structure. List element. Widget option list. Automatically closes 398the previous list element. Specifies the [arg name] of the option as 399used in scripts, the name used by the option database ([arg dbname]), 400and its class ([arg dbclass]), i.e. its type. It is expected that the 401name is marked up using [cmd option]. 402 403[call [cmd type] [arg text]] 404 405Text markup. The argument is marked up as the name of a 406[term {data type}]. The text may have other markup already applied to 407it. Main use is the highlighting of data types in free-form text. 408 409[call [cmd uri] [arg text] [opt [arg text]]] 410 411Text markup. The argument is marked up as an [term uri] (i.e. a 412[term {uniform resource identifier}]. The text may have other markup 413already applied to it. Main use is the highlighting of uris in 414free-form text. The second argument, should it be present, will be 415interpreted the human-readable description of the uri. In other words, 416as its label. Without an explicit label the uri will be its own label. 417 418[call [cmd usage] [arg args]] 419 420Text markup. See [cmd call] for the full description, this command is 421syntactically identical, as it is in its expectations for the markup 422of its arguments. 423 424In contrast to [cmd call] it is however not allowed to generate output 425where this command occurs in the text. The command is [term silent]. 426The formatted text may only appear in a different section of the 427output, for example a table of contents, or synopsis, depending on the 428output format. 429 430[call [cmd var] [arg text]] 431 432Text markup. The argument is marked up as the name of a 433[term variable]. The text may have other markup already applied to 434it. Main use is the highlighting of variables in free-form text. 435 436[call [cmd vset] [arg varname] [arg value] ] 437 438Templating. In this form the command sets the named document variable 439to the specified [arg value]. It does not generate output. I.e. the 440command is replaced by the empty string. 441 442[call [cmd vset] [arg varname]] 443 444Templating. In this form the command is replaced by the value of the 445named document variable 446 447[call [cmd widget] [arg text]] 448 449Text markup. The argument is marked up as the name of a 450[term widget]. The text may have other markup already applied to 451it. Main use is the highlighting of widget names in free-form text. 452 453[list_end] 454 455[section {BUGS, IDEAS, FEEDBACK}] 456 457This document, and the package it describes, will undoubtedly contain 458bugs and other problems. 459 460Please report such in the category [emph doctools] of the 461[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 462 463Please also report any ideas for enhancements you may have for either 464package and/or documentation. 465 466[see_also doctools_intro] 467[see_also doctools_lang_intro] 468[see_also doctools_lang_syntax] 469[see_also doctools_lang_faq] 470[keywords markup {semantic markup}] 471[keywords {doctools markup} {doctools language} {doctools commands}] 472[manpage_end] 473