1doctools_lang_intro(n) Documentation tools doctools_lang_intro(n)
2______________________________________________________________________________
6
8 doctools_lang_intro - doctools language introduction
9
11 This document is an informal introduction to version 1 of the doctools
12 markup language based on a multitude of examples. After reading this a
13 writer should be ready to understand the two parts of the formal speci‐
14 fication, i.e. the doctools language syntax specification and the doc‐
15 tools language command reference.
16 FUNDAMENTALS
18 In the broadest terms possible the doctools markup language is LaTeX-
19 like, instead of like SGML and similar languages. A document written in
20 this language consists primarily of text, with markup commands embedded
21 into it.
22 Each markup command is a Tcl command surrounded by a matching pair of [
24 and ]. Inside of these delimiters the usual rules for a Tcl command ap‐
25 ply with regard to word quotation, nested commands, continuation lines,
26 etc. I.e.
27 ... [list_begin enumerated] ...
29 ... [call [cmd foo] \
33 [arg bar]] ...
34 ... [term {complex concept}] ...
38 ... [opt "[arg key] [arg value]"] ...
42 BASIC STRUCTURE
45 The most simple document which can be written in doctools is
46 [manpage_begin NAME SECTION VERSION]
49 [see_also doctools_intro]
50 [see_also doctools_lang_cmdref]
51 [see_also doctools_lang_faq]
52 [see_also doctools_lang_syntax]
53 [keywords {doctools commands}]
54 [keywords {doctools language}]
55 [keywords {doctools markup}]
56 [keywords {doctools syntax}]
57 [keywords markup]
58 [keywords {semantic markup}]
59 [description]
60 [vset CATEGORY doctools]
61 [include ../common-text/feedback.inc]
62 [manpage_end]
63 This also shows us that all doctools documents are split into two
65 parts, the header and the body. Everything coming before [description]
66 belongs to the header, and everything coming after belongs to the body,
67 with the whole document bracketed by the two manpage_* commands. Before
68 and after these opening and closing commands we have only whitespace.
69 In the remainder of this section we will discuss only the contents of
71 the header, the structure of the body will be discussed in the section
72 Text structure.
73 The header section can be empty, and otherwise may contain only an ar‐
75 bitrary sequence of the four so-called header commands, plus white‐
76 space. These commands are
77 titledesc
79 moddesc
81 require
83 copyright
85 They provide, through their arguments, additional information about the
87 document, like its title, the title of the larger group the document
88 belongs to (if applicable), the requirements of the documented packages
89 (if applicable), and copyright assignments. All of them can occur mul‐
90 tiple times, including none, and they can be used in any order. How‐
91 ever for titledesc and moddesc only the last occurrence is taken. For
92 the other two the specified information is accumulated, in the given
93 order. Regular text is not allowed within the header.
94 Given the above a less minimal example of a document is
96 [manpage_begin NAME SECTION VERSION]
99 [copyright {YEAR AUTHOR}]
100 [titledesc TITLE]
101 [moddesc MODULE_TITLE]
102 [require PACKAGE VERSION]
103 [require PACKAGE]
104 [description]
105 [manpage_end]
106 Remember that the whitespace is optional. The document
108 [manpage_begin NAME SECTION VERSION]
111 [copyright {YEAR AUTHOR}][titledesc TITLE][moddesc MODULE_TITLE]
112 [require PACKAGE VERSION][require PACKAGE][description]
113 [vset CATEGORY doctools]
114 [include ../common-text/feedback.inc]
115 [manpage_end]
116 has the same meaning as the example before.
118 On the other hand, if whitespace is present it consists not only of any
120 sequence of characters containing the space character, horizontal and
121 vertical tabs, carriage return, and newline, but it may contain comment
122 markup as well, in the form of the comment command.
123 [comment { ... }]
126 [manpage_begin NAME SECTION VERSION]
127 [copyright {YEAR AUTHOR}]
128 [titledesc TITLE]
129 [moddesc MODULE_TITLE][comment { ... }]
130 [require PACKAGE VERSION]
131 [require PACKAGE]
132 [description]
133 [manpage_end]
134 [comment { ... }]
135 ADVANCED STRUCTURE
138 In the simple examples of the last section we fudged a bit regarding
139 the markup actually allowed to be used before the manpage_begin command
140 opening the document.
141 Instead of only whitespace the two templating commands include and vset
143 are also allowed, to enable the writer to either set and/or import con‐
144 figuration settings relevant to the document. I.e. it is possible to
145 write
146 [include FILE]
149 [vset VAR VALUE]
150 [manpage_begin NAME SECTION VERSION]
151 [description]
152 [manpage_end]
153 Even more important, these two commands are allowed anywhere where a
155 markup command is allowed, without regard for any other structure. I.e.
156 for example in the header as well.
157 [manpage_begin NAME SECTION VERSION]
160 [include FILE]
161 [vset VAR VALUE]
162 [description]
163 [manpage_end]
164 The only restriction include has to obey is that the contents of the
166 included file must be valid at the place of the inclusion. I.e. a file
167 included before manpage_begin may contain only the templating commands
168 vset and include, a file included in the header may contain only header
169 commands, etc.
170 TEXT STRUCTURE
172 The body of the document consists mainly of text, possibly split into
173 sections, subsections, and paragraphs, with parts marked up to high‐
174 light various semantic categories of text, and additional structure
175 through the use of examples and (nested) lists.
176 This section explains the high-level structural commands, with every‐
178 thing else deferred to the following sections.
179 The simplest way of structuring the body is through the introduction of
181 paragraphs. The command for doing so is para. Each occurrence of this
182 command closes the previous paragraph and automatically opens the next.
183 The first paragraph is automatically opened at the beginning of the
184 body, by description. In the same manner the last paragraph automati‐
185 cally ends at manpage_end.
186 [manpage_begin NAME SECTION VERSION]
189 [description]
190 ...
191 [para]
192 ...
193 [para]
194 ...
195 [manpage_end]
196 Empty paragraphs are ignored.
198 A structure coarser than paragraphs are sections, which allow the
200 writer to split a document into larger, and labeled, pieces. The com‐
201 mand for doing so is section. Each occurrence of this command closes
202 the previous section and automatically opens the next, including its
203 first paragraph. The first section is automatically opened at the be‐
204 ginning of the body, by description (This section is labeled "DESCRIP‐
205 TION"). In the same manner the last section automatically ends at man‐
206 page_end.
207 Empty sections are not ignored. We are free to (not) use paragraphs
209 within sections.
210 [manpage_begin NAME SECTION VERSION]
213 [description]
214 ...
215 [section {Section A}]
216 ...
217 [para]
218 ...
219 [section {Section B}]
220 ...
221 [manpage_end]
222 Between sections and paragraphs we have subsections, to split sections.
224 The command for doing so is subsection. Each occurrence of this command
225 closes the previous subsection and automatically opens the next, in‐
226 cluding its first paragraph. A subsection is automatically opened at
227 the beginning of the body, by description, and at the beginning of each
228 section. In the same manner the last subsection automatically ends at
229 manpage_end.
230 Empty subsections are not ignored. We are free to (not) use paragraphs
232 within subsections.
233 [manpage_begin NAME SECTION VERSION]
236 [description]
237 ...
238 [section {Section A}]
239 ...
240 [subsection {Sub 1}]
241 ...
242 [para]
243 ...
244 [subsection {Sub 2}]
245 ...
246 [section {Section B}]
247 ...
248 [manpage_end]
249 TEXT MARKUP
252 Having handled the overall structure a writer can impose on the docu‐
253 ment we now take a closer at the text in a paragraph.
254 While most often this is just the unadorned content of the document we
256 do have situations where we wish to highlight parts of it as some type
257 of thing or other, like command arguments, command names, concepts,
258 uris, etc.
259 For this we have a series of markup commands which take the text to
261 highlight as their single argument. It should be noted that while their
262 predominant use is the highlighting of parts of a paragraph they can
263 also be used to mark up the arguments of list item commands, and of
264 other markup commands.
265 The commands available to us are
267 arg Its argument is a the name of a command argument.
269 class Its argument is a class name.
271 cmd Its argument is a command name (Tcl command).
273 const Its argument is a constant.
275 emph General, non-semantic emphasis.
277 file Its argument is a filename / path.
279 fun Its argument is a function name.
281 method Its argument is a method name
283 namespace
285 Its argument is namespace name.
286 opt Its argument is some optional syntax element.
288 option Its argument is a command line switch / widget option.
290 package
292 Its argument is a package name.
293 sectref
295 Its argument is the title of a section or subsection, i.e. a
296 section reference.
297 syscmd Its argument is a command name (external, system command).
299 term Its argument is a concept, or general terminology.
301 type Its argument is a type name.
303 uri Its argument is a uniform resource identifier, i.e an external
305 reference. A second argument can be used to specify an explicit
306 label for the reference in question.
307 usage The arguments describe the syntax of a Tcl command.
309 var Its argument is a variable.
311 widget Its argument is a widget name.
313 The example demonstrating the use of text markup is an excerpt from the
315 doctools language command reference, with some highlighting added. It
316 shows their use within a block of text, as the arguments of a list item
317 command (call), and our ability to nest them.
318 ...
321 [call [cmd arg_def] [arg type] [arg name] [opt [arg mode]]]
322 Text structure. List element. Argument list. Automatically closes the
324 previous list element. Specifies the data-[arg type] of the described
325 argument of a command, its [arg name] and its i/o-[arg mode]. The
326 latter is optional.
327 ...
328 ESCAPES
331 Beyond the 20 commands for simple markup shown in the previous section
332 we have two more available which are technically simple markup. How‐
333 ever their function is not the marking up of phrases as specific types
334 of things, but the insertion of characters, namely [ and ]. These com‐
335 mands, lb and rb respectively, are required because our use of [ and ]
336 to bracket markup commands makes it impossible to directly use [ and ]
337 within the text.
338 Our example of their use are the sources of the last sentence in the
340 previous paragraph, with some highlighting added.
341 ...
344 These commands, [cmd lb] and [cmd lb] respectively, are required
345 because our use of [lb] and [rb] to bracket markup commands makes it
346 impossible to directly use [lb] and [rb] within the text.
347 ...
348 CROSS-REFERENCES
351 The last two commands we have to discuss are for the declaration of
352 cross-references between documents, explicit and implicit. They are
353 keywords and see_also. Both take an arbitrary number of arguments, all
354 of which have to be plain unmarked text. I.e. it is not allowed to use
355 markup on them. Both commands can be used multiple times in a document.
356 If that is done all arguments of all occurrences of one of them are put
357 together into a single set.
358 keywords
360 The arguments of this command are interpreted as keywords de‐
361 scribing the document. A processor can use this information to
362 create an index indirectly linking the containing document to
363 all documents with the same keywords.
364 see_also
366 The arguments of this command are interpreted as references to
367 other documents. A processor can format them as direct links to
368 these documents.
369 All the cross-reference commands can occur anywhere in the document be‐
371 tween manpage_begin and manpage_end. As such the writer can choose
372 whether she wants to have them at the beginning of the body, or at its
373 end, maybe near the place a keyword is actually defined by the main
374 content, or considers them as meta data which should be in the header,
375 etc.
376 Our example shows the sources for the cross-references of this docu‐
378 ment, with some highlighting added. Incidentally they are found at the
379 end of the body.
380 ...
383 [see_also doctools_intro]
384 [see_also doctools_lang_syntax]
385 [see_also doctools_lang_cmdref]
386 [keywords markup {semantic markup}]
387 [keywords {doctools markup} {doctools language}]
388 [keywords {doctools syntax} {doctools commands}]
389 [manpage_end]
390 EXAMPLES
393 Where ever we can write plain text we can write examples too. For sim‐
394 ple examples we have the command example which takes a single argument,
395 the text of the argument. The example text must not contain markup. If
396 we wish to have markup within an example we have to use the 2-command
397 combination example_begin / example_end instead.
398 The first opens an example block, the other closes it, and in between
400 we can write plain text and use all the regular text markup commands.
401 Note that text structure commands are not allowed. This also means that
402 it is not possible to embed examples and lists within an example. On
403 the other hand, we can use templating commands within example blocks to
404 read their contents from a file (Remember section Advanced structure).
405 The source for the very first example in this document (see section
407 Fundamentals), with some highlighting added, is
408 [example {
411 ... [list_begin enumerated] ...
412 }]
413 Using example_begin / example_end this would look like
415 [example_begin]
418 ... [list_begin enumerated] ...
419 [example_end]
420 LISTS
423 Where ever we can write plain text we can write lists too. The main
424 commands are list_begin to start a list, and list_end to close one. The
425 opening command takes an argument specifying the type of list started
426 it, and this in turn determines which of the eight existing list item
427 commands are allowed within the list to start list items.
428 After the opening command only whitespace is allowed, until the first
430 list item command opens the first item of the list. Each item is a reg‐
431 ular series of paragraphs and is closed by either the next list item
432 command, or the end of the list. If closed by a list item command this
433 command automatically opens the next list item. A consequence of a list
434 item being a series of paragraphs is that all regular text markup can
435 be used within a list item, including examples and other lists.
436 The list types recognized by list_begin and their associated list item
438 commands are:
439 arguments
441 (arg_def) This opens an argument (declaration) list. It is a
442 specialized form of a term definition list where the term is an
443 argument name, with its type and i/o-mode.
444 commands
446 (cmd_def) This opens a command (declaration) list. It is a spe‐
447 cialized form of a term definition list where the term is a com‐
448 mand name.
449 definitions
451 (def and call) This opens a general term definition list. The
452 terms defined by the list items are specified through the argu‐
453 ment(s) of the list item commands, either general terms, possi‐
454 bly with markup (def), or Tcl commands with their syntax (call).
455 enumerated
457 (enum) This opens a general enumerated list.
458 itemized
460 (item) This opens a general itemized list.
461 options
463 (opt_def) This opens an option (declaration) list. It is a spe‐
464 cialized form of a term definition list where the term is an op‐
465 tion name, possibly with the option's arguments.
466 tkoptions
468 (tkoption_def) This opens a widget option (declaration) list. It
469 is a specialized form of a term definition list where the term
470 is the name of a configuration option for a widget, with its
471 name and class in the option database.
472 Our example is the source of the definition list in the previous para‐
474 graph, with most of the content in the middle removed.
475 ...
478 [list_begin definitions]
479 [def [const arg]]
480 ([cmd arg_def]) This opens an argument (declaration) list. It is a
482 specialized form of a definition list where the term is an argument
483 name, with its type and i/o-mode.
484 [def [const itemized]]
486 ([cmd item])
488 This opens a general itemized list.
489 ...
491 [def [const tkoption]]
492 ([cmd tkoption_def]) This opens a widget option (declaration) list. It
494 is a specialized form of a definition list where the term is the name
495 of a configuration option for a widget, with its name and class in the
496 option database.
497 [list_end]
499 ...
500 Note that a list cannot begin in one (sub)section and end in another.
502 Differently said, (sub)section breaks are not allowed within lists and
503 list items. An example of this illegal construct is
504 ...
507 [list_begin itemized]
508 [item]
509 ...
510 [section {ILLEGAL WITHIN THE LIST}]
511 ...
512 [list_end]
513 ...
514
517 Now that this document has been digested the reader, assumed to be a
518 writer of documentation should be fortified enough to be able to under‐
519 stand the formal doctools language syntax specification as well. From
520 here on out the doctools language command reference will also serve as
521 the detailed specification and cheat sheet for all available commands
522 and their syntax.
523 To be able to validate a document while writing it, it is also recom‐
525 mended to familiarize oneself with one of the applications for the pro‐
526 cessing and conversion of doctools documents, i.e. either Tcllib's easy
527 and simple dtplite, or Tclapps' ultra-configurable dtp.
528
530 This document, and the package it describes, will undoubtedly contain
531 bugs and other problems. Please report such in the category doctools
532 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
533 also report any ideas for enhancements you may have for either package
534 and/or documentation.
535 When proposing code changes, please provide unified diffs, i.e the out‐
537 put of diff -u.
538 Note further that attachments are strongly preferred over inlined
540 patches. Attachments can be made by going to the Edit form of the
541 ticket immediately after its creation, and then using the left-most
542 button in the secondary navigation bar.
543
545 doctools_intro, doctools_lang_cmdref, doctools_lang_faq, doc‐
546 tools_lang_syntax
547
549 doctools commands, doctools language, doctools markup, doctools syntax,
550 markup, semantic markup
551
553 Documentation tools
554
556 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
557tcllib 1.0 doctools_lang_intro(n)