1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin doctools_lang_intro n 1.0] 3[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Documentation tools}] 5[titledesc {doctools language introduction}] 6[category {Documentation tools}] 7[description] 8[para] 9 10This document is an informal introduction to version 1 of the doctools 11markup language based on a multitude of examples. After reading this a 12writer should be ready to understand the two parts of the formal 13specification, i.e. the [term {doctools language syntax}] specification 14and the [term {doctools language command reference}]. 15 16[subsection Fundamentals] 17 18In the broadest terms possible the [term {doctools markup language}] 19is LaTeX-like, instead of like SGML and similar languages. A document 20written in this language consists primarily of text, with markup 21commands embedded into it. 22 23[para] 24 25Each markup command is a Tcl command surrounded by a matching pair of 26[const [lb]] and [const [rb]]. Inside of these delimiters the usual 27rules for a Tcl command apply with regard to word quotation, nested 28commands, continuation lines, etc. I.e. 29 30[para] 31[example { 32 ... [list_begin enumerated] ... 33}] 34 35[example { 36 ... [call [cmd foo] \\ 37 [arg bar]] ... 38}] 39 40[example { 41 ... [term {complex concept}] ... 42}] 43 44[example { 45 ... [opt "[arg key] [arg value]"] ... 46}] 47 48 49[subsection {Basic structure}] 50 51The most simple document which can be written in doctools is 52 53[example { 54 [manpage_begin NAME SECTION VERSION] 55 [description] 56 [manpage_end] 57}] 58 59This also shows us that all doctools documents are split into two 60parts, the [term header] and the [term body]. Everything coming before 61[lb][cmd description][rb] belongs to the header, and everything coming 62after belongs to the body, with the whole document bracketed by the 63two [cmd manpage_*] commands. Before and after these opening and 64closing commands we have only [term whitespace]. 65 66[para] 67 68In the remainder of this section we will discuss only the contents of 69the header, the structure of the body will be discussed in the section 70[sectref {Text structure}]. 71 72[para] 73 74The header section can be empty, and otherwise may contain only an 75arbitrary sequence of the four so-called [term header] commands, plus 76[term whitespace]. These commands are 77 78[list_begin commands] 79[cmd_def titledesc] 80[cmd_def moddesc] 81[cmd_def require] 82[cmd_def copyright] 83[list_end] 84 85They provide, through their arguments, additional information about 86the document, like its title, the title of the larger group the 87document belongs to (if applicable), the requirements of the 88documented packages (if applicable), and copyright assignments. All of 89them can occur multiple times, including none, and they can be used in 90any order. 91 92However for [cmd titledesc] and [cmd moddesc] only the last occurrence 93is taken. For the other two the specified information is accumulated, 94in the given order. Regular text is not allowed within the header. 95 96[para] 97 98Given the above a less minimal example of a document is 99 100[example_begin] 101[lb]manpage_begin NAME SECTION VERSION[rb] 102[lb][cmd {copyright {YEAR AUTHOR}}][rb] 103[lb][cmd {titledesc TITLE}][rb] 104[lb][cmd {moddesc MODULE_TITLE}][rb] 105[lb][cmd {require PACKAGE VERSION}][rb] 106[lb][cmd {require PACKAGE}][rb] 107[lb]description[rb] 108[lb]manpage_end[rb] 109[example_end] 110 111Remember that the whitespace is optional. The document 112 113[example { 114 [manpage_begin NAME SECTION VERSION] 115 [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE] 116 [require PACKAGE VERSION][require PACKAGE][description] 117 [manpage_end] 118}] 119 120has the same meaning as the example before. 121 122[para] 123 124On the other hand, if [term whitespace] is present it consists not 125only of any sequence of characters containing the space character, 126horizontal and vertical tabs, carriage return, and newline, but it may 127contain comment markup as well, in the form of the [cmd comment] 128command. 129 130[example_begin] 131[lb][cmd {comment { ... }}][rb] 132[lb]manpage_begin NAME SECTION VERSION[rb] 133[lb]copyright {YEAR AUTHOR}[rb] 134[lb]titledesc TITLE[rb] 135[lb]moddesc MODULE_TITLE[rb][lb][cmd {comment { ... }}][rb] 136[lb]require PACKAGE VERSION[rb] 137[lb]require PACKAGE[rb] 138[lb]description[rb] 139[lb]manpage_end[rb] 140[lb][cmd {comment { ... }}][rb] 141[example_end] 142 143 144[subsection {Advanced structure}] 145 146In the simple examples of the last section we fudged a bit regarding 147the markup actually allowed to be used before the [cmd manpage_begin] 148command opening the document. 149 150[para] 151 152Instead of only whitespace the two templating commands [cmd include] 153and [cmd vset] are also allowed, to enable the writer to either set 154and/or import configuration settings relevant to the document. I.e. it 155is possible to write 156 157[example_begin] 158[lb][cmd {include FILE}][rb] 159[lb][cmd {vset VAR VALUE}][rb] 160[lb]manpage_begin NAME SECTION VERSION[rb] 161[lb]description[rb] 162[lb]manpage_end[rb] 163[example_end] 164 165Even more important, these two commands are allowed anywhere where a 166markup command is allowed, without regard for any other 167structure. I.e. for example in the header as well. 168 169[example_begin] 170[lb]manpage_begin NAME SECTION VERSION[rb] 171[lb][cmd {include FILE}][rb] 172[lb][cmd {vset VAR VALUE}][rb] 173[lb]description[rb] 174[lb]manpage_end[rb] 175[example_end] 176 177The only restriction [cmd include] has to obey is that the contents of 178the included file must be valid at the place of the inclusion. I.e. a 179file included before [cmd manpage_begin] may contain only the 180templating commands [cmd vset] and [cmd include], a file included in 181the header may contain only header commands, etc. 182 183 184[subsection {Text structure}] 185 186The body of the document consists mainly of text, possibly split into 187sections, subsections, and paragraphs, with parts marked up to 188highlight various semantic categories of text, and additional 189structure through the use of examples and (nested) lists. 190 191[para] 192 193This section explains the high-level structural commands, with 194everything else deferred to the following sections. 195 196[para] 197 198The simplest way of structuring the body is through the introduction 199of paragraphs. The command for doing so is [cmd para]. Each occurrence 200of this command closes the previous paragraph and automatically opens 201the next. The first paragraph is automatically opened at the beginning 202of the body, by [cmd description]. In the same manner the last 203paragraph automatically ends at [cmd manpage_end]. 204 205[example_begin] 206[lb]manpage_begin NAME SECTION VERSION[rb] 207[lb]description[rb] 208 ... 209[lb][cmd para][rb] 210 ... 211[lb][cmd para][rb] 212 ... 213[lb]manpage_end[rb] 214[example_end] 215 216Empty paragraphs are ignored. 217 218[para] 219 220A structure coarser than paragraphs are sections, which allow the 221writer to split a document into larger, and labeled, pieces. The 222command for doing so is [cmd section]. Each occurrence of this command 223closes the previous section and automatically opens the next, 224including its first paragraph. The first section is automatically 225opened at the beginning of the body, by [cmd description] (This 226section is labeled "DESCRIPTION"). In the same manner the last section 227automatically ends at [cmd manpage_end]. 228 229[para] 230 231Empty sections are [emph not] ignored. We are free to (not) use 232paragraphs within sections. 233 234[example_begin] 235[lb]manpage_begin NAME SECTION VERSION[rb] 236[lb]description[rb] 237 ... 238[lb][cmd {section {Section A}}][rb] 239 ... 240[lb]para[rb] 241 ... 242[lb][cmd {section {Section B}}][rb] 243 ... 244[lb]manpage_end[rb] 245[example_end] 246 247Between sections and paragraphs we have subsections, to split sections. 248 249The command for doing so is [cmd subsection]. Each occurrence of this 250command closes the previous subsection and automatically opens the 251next, including its first paragraph. A subsection is automatically 252opened at the beginning of the body, by [cmd description], and at the 253beginning of each section. In the same manner the last subsection 254automatically ends at [cmd manpage_end]. 255 256[para] 257 258Empty subsections are [emph not] ignored. We are free to (not) use 259paragraphs within subsections. 260 261[example_begin] 262[lb]manpage_begin NAME SECTION VERSION[rb] 263[lb]description[rb] 264 ... 265[lb]section {Section A}[rb] 266 ... 267[lb][cmd {subsection {Sub 1}}][rb] 268 ... 269[lb]para[rb] 270 ... 271[lb][cmd {subsection {Sub 2}}][rb] 272 ... 273[lb]section {Section B}[rb] 274 ... 275[lb]manpage_end[rb] 276[example_end] 277 278 279[subsection {Text markup}] 280 281Having handled the overall structure a writer can impose on the 282document we now take a closer at the text in a paragraph. 283 284[para] 285 286While most often this is just the unadorned content of the document we 287do have situations where we wish to highlight parts of it as some type 288of thing or other, like command arguments, command names, concepts, 289uris, etc. 290 291[para] 292 293For this we have a series of markup commands which take the text to 294highlight as their single argument. It should be noted that while 295their predominant use is the highlighting of parts of a paragraph they 296can also be used to mark up the arguments of list item commands, and 297of other markup commands. 298 299[para] 300 301The commands available to us are 302 303[list_begin commands] 304[cmd_def arg] Its argument is a the name of a command argument. 305[cmd_def class] Its argument is a class name. 306[cmd_def cmd] Its argument is a command name (Tcl command). 307[cmd_def const] Its argument is a constant. 308[cmd_def emph] General, non-semantic emphasis. 309[cmd_def file] Its argument is a filename / path. 310[cmd_def fun] Its argument is a function name. 311[cmd_def method] Its argument is a method name 312[cmd_def namespace] Its argument is namespace name. 313[cmd_def opt] Its argument is some optional syntax element. 314[cmd_def option] Its argument is a command line switch / widget option. 315[cmd_def package] Its argument is a package name. 316[cmd_def sectref] Its argument is the title of a section or subsection, 317 i.e. a section reference. 318[cmd_def syscmd] Its argument is a command name (external, system command). 319[cmd_def term] Its argument is a concept, or general terminology. 320[cmd_def type] Its argument is a type name. 321[cmd_def uri] Its argument is a uniform resource identifier, i.e an 322 external reference. A second argument can be used 323 to specify an explicit label for the reference in 324 question. 325[cmd_def usage] The arguments describe the syntax of a Tcl command. 326[cmd_def var] Its argument is a variable. 327[cmd_def widget] Its argument is a widget name. 328[list_end] 329 330The example demonstrating the use of text markup is an excerpt from 331the [term {doctools language command reference}], with some 332highlighting added. 333 334It shows their use within a block of text, as the arguments of a list 335item command ([cmd call]), and our ability to nest them. 336 337[example_begin] 338 ... 339 [lb]call [lb][cmd {cmd arg_def}][rb] [lb][cmd {arg type}][rb] [lb][cmd {arg name}][rb]] [lb][cmd opt] [lb][cmd {arg mode}][rb][rb][rb] 340 341 Text structure. List element. Argument list. Automatically closes the 342 previous list element. Specifies the data-[lb][cmd {arg type}][rb] of the described 343 argument of a command, its [lb][cmd {arg name}][rb] and its i/o-[lb][cmd {arg mode}][rb]. The 344 latter is optional. 345 ... 346[example_end] 347 348 349[subsection Escapes] 350 351Beyond the 20 commands for simple markup shown in the previous section 352we have two more available which are technically simple markup. 353 354However their function is not the marking up of phrases as specific 355types of things, but the insertion of characters, namely [const [lb]] 356and [const [rb]]. 357 358These commands, [cmd lb] and [cmd rb] respectively, are required 359because our use of [lb] and [rb] to bracket markup commands makes it 360impossible to directly use [lb] and [rb] within the text. 361 362[para] 363 364Our example of their use are the sources of the last sentence in the 365previous paragraph, with some highlighting added. 366 367[example_begin] 368 ... 369 These commands, [lb]cmd lb[rb] and [lb]cmd lb[rb] respectively, are required 370 because our use of [lb][cmd lb][rb] and [lb][cmd rb][rb] to bracket markup commands makes it 371 impossible to directly use [lb][cmd lb][rb] and [lb][cmd rb][rb] within the text. 372 ... 373[example_end] 374 375 376[subsection Cross-references] 377 378The last two commands we have to discuss are for the declaration of 379cross-references between documents, explicit and implicit. They are 380[cmd keywords] and [cmd see_also]. Both take an arbitrary number of 381arguments, all of which have to be plain unmarked text. I.e. it is not 382allowed to use markup on them. Both commands can be used multiple 383times in a document. If that is done all arguments of all occurrences 384of one of them are put together into a single set. 385 386[list_begin definitions] 387[def [cmd keywords]] 388 389The arguments of this command are interpreted as keywords describing 390the document. A processor can use this information to create an index 391indirectly linking the containing document to all documents with the 392same keywords. 393 394[def [cmd see_also]] 395 396The arguments of this command are interpreted as references to other 397documents. A processor can format them as direct links to these 398documents. 399 400[list_end] 401 402[para] 403 404All the cross-reference commands can occur anywhere in the document 405between [cmd manpage_begin] and [cmd manpage_end]. As such the writer 406can choose whether she wants to have them at the beginning of the 407body, or at its end, maybe near the place a keyword is actually 408defined by the main content, or considers them as meta data which 409should be in the header, etc. 410 411[para] 412 413Our example shows the sources for the cross-references of this 414document, with some highlighting added. Incidentally they are found 415at the end of the body. 416 417[example_begin] 418 ... 419 [lb][cmd {see_also doctools_intro}][rb] 420 [lb][cmd {see_also doctools_lang_syntax}][rb] 421 [lb][cmd {see_also doctools_lang_cmdref}][rb] 422 [lb][cmd {keywords markup {semantic markup}}][rb] 423 [lb][cmd {keywords {doctools markup} {doctools language}}][rb] 424 [lb][cmd {keywords {doctools syntax} {doctools commands}}][rb] 425 [lb]manpage_end[rb] 426[example_end] 427 428 429[subsection Examples] 430 431Where ever we can write plain text we can write examples too. For 432simple examples we have the command [cmd example] which takes a single 433argument, the text of the argument. The example text must not contain 434markup. If we wish to have markup within an example we have to use the 4352-command combination [cmd example_begin] / [cmd example_end] instead. 436 437[para] 438 439The first opens an example block, the other closes it, and in between 440we can write plain text and use all the regular text markup commands. 441Note that text structure commands are not allowed. This also means 442that it is not possible to embed examples and lists within an example. 443On the other hand, we [emph can] use templating commands within 444example blocks to read their contents from a file (Remember section 445[sectref {Advanced structure}]). 446 447[para] 448 449The source for the very first example in this document (see section 450[sectref Fundamentals]), with some highlighting added, is 451 452[example_begin] 453 [lb][cmd example] { 454 ... [lb]list_begin enumerated[rb] ... 455 }[rb] 456[example_end] 457 458Using [cmd example_begin] / [cmd example_end] this would look like 459 460[example_begin] 461 [lb][cmd example_begin][rb] 462 ... [lb]list_begin enumerated[rb] ... 463 [lb][cmd example_end][rb] 464[example_end] 465 466 467[subsection Lists] 468 469Where ever we can write plain text we can write lists too. The main 470commands are [cmd list_begin] to start a list, and [cmd list_end] to 471close one. The opening command takes an argument specifying the type 472of list started it, and this in turn determines which of the eight 473existing list item commands are allowed within the list to start list 474items. 475 476[para] 477 478After the opening command only whitespace is allowed, until the first 479list item command opens the first item of the list. Each item is a 480regular series of paragraphs and is closed by either the next list 481item command, or the end of the list. If closed by a list item command 482this command automatically opens the next list item. A consequence of 483a list item being a series of paragraphs is that all regular text 484markup can be used within a list item, including examples and other 485lists. 486 487[para] 488 489The list types recognized by [cmd list_begin] and their associated 490list item commands are: 491 492[list_begin definitions] 493[def [const arguments]] 494 495([cmd arg_def]) This opens an [term {argument (declaration) list}]. It 496is a specialized form of a term definition list where the term is an 497argument name, with its type and i/o-mode. 498 499[def [const commands]] 500 501([cmd cmd_def]) This opens a [term {command (declaration) list}]. It 502is a specialized form of a term definition list where the term is a 503command name. 504 505[def [const definitions]] 506 507([cmd def] and [cmd call]) This opens a general 508[term {term definition list}]. The terms defined by the list items are 509specified through the argument(s) of the list item commands, either 510general terms, possibly with markup ([cmd def]), or Tcl commands with 511their syntax ([cmd call]). 512 513[def [const enumerated]] 514 515([cmd enum]) This opens a general [term {enumerated list}]. 516 517[def [const itemized]] 518 519([cmd item]) 520This opens a general [term {itemized list}]. 521 522[def [const options]] 523 524([cmd opt_def]) This opens an [term {option (declaration) list}]. It 525is a specialized form of a term definition list where the term is an 526option name, possibly with the option's arguments. 527 528[def [const tkoptions]] 529 530([cmd tkoption_def]) This opens a 531[term {widget option (declaration) list}]. It is a specialized form of 532a term definition list where the term is the name of a configuration 533option for a widget, with its name and class in the option database. 534 535[list_end] 536 537Our example is the source of the definition list in the previous 538paragraph, with most of the content in the middle removed. 539 540[example_begin] 541 ... 542 [lb][cmd list_begin] definitions[rb] 543 [lb][cmd def] [lb]const arg[rb][rb] 544 545 ([lb]cmd arg_def[rb]) This opens an argument (declaration) list. It is a 546 specialized form of a definition list where the term is an argument 547 name, with its type and i/o-mode. 548 549 [lb][cmd def] [lb]const itemized[rb][rb] 550 551 ([lb]cmd item[rb]) 552 This opens a general itemized list. 553 554 ... 555 [lb][cmd def] [lb]const tkoption[rb][rb] 556 557 ([lb]cmd tkoption_def[rb]) This opens a widget option (declaration) list. It 558 is a specialized form of a definition list where the term is the name 559 of a configuration option for a widget, with its name and class in the 560 option database. 561 562 [lb][cmd list_end][rb] 563 ... 564[example_end] 565 566Note that a list cannot begin in one (sub)section and end in 567another. Differently said, (sub)section breaks are not allowed within 568lists and list items. An example of this [emph illegal] construct is 569 570[example_begin] 571 ... 572 [lb]list_begin itemized[rb] 573 [lb]item[rb] 574 ... 575 [lb][cmd {section {ILLEGAL WITHIN THE LIST}}][rb] 576 ... 577 [lb]list_end[rb] 578 ... 579[example_end] 580 581 582[section {FURTHER READING}] 583 584Now that this document has been digested the reader, assumed to be a 585[term writer] of documentation should be fortified enough to be able 586to understand the formal [term {doctools language syntax}] 587specification as well. From here on out the 588[term {doctools language command reference}] will also serve as the 589detailed specification and cheat sheet for all available commands and 590their syntax. 591 592[para] 593 594To be able to validate a document while writing it, it is also 595recommended to familiarize oneself with one of the applications for 596the processing and conversion of doctools documents, i.e. either 597Tcllib's easy and simple [syscmd dtplite], or Tclapps' 598ultra-configurable [syscmd dtp]. 599 600 601[section {BUGS, IDEAS, FEEDBACK}] 602 603This document, will undoubtedly contain bugs and other problems. 604 605Please report such in the category [emph doctools] of the 606[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 607 608Please also report any ideas for enhancements you may have. 609 610[see_also doctools_intro] 611[see_also doctools_lang_syntax] 612[see_also doctools_lang_cmdref] 613[see_also doctools_lang_faq] 614[keywords markup {semantic markup}] 615[keywords {doctools markup} {doctools language}] 616[keywords {doctools syntax} {doctools commands}] 617[manpage_end] 618