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