1doctools_lang_intro(n)        Documentation tools       doctools_lang_intro(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       doctools_lang_intro - doctools language introduction
9

DESCRIPTION

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

FURTHER READING

597       Now  that  this  document has been digested the reader, assumed to be a
598       writer of documentation should be fortified enough to be able to under‐
599       stand  the  formal doctools language syntax specification as well. From
600       here on out the doctools language command reference will also serve  as
601       the  detailed  specification and cheat sheet for all available commands
602       and their syntax.
603
604       To be able to validate a document while writing it, it is  also  recom‐
605       mended to familiarize oneself with one of the applications for the pro‐
606       cessing and conversion of doctools documents, i.e. either Tcllib's easy
607       and simple dtplite, or Tclapps' ultra-configurable dtp.
608

BUGS, IDEAS, FEEDBACK

610       This  document,  and the package it describes, will undoubtedly contain
611       bugs and other problems.  Please report such in the  category  doctools
612       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
613       also report any ideas for enhancements you may have for either  package
614       and/or documentation.
615
616       When proposing code changes, please provide unified diffs, i.e the out‐
617       put of diff -u.
618
619       Note further that  attachments  are  strongly  preferred  over  inlined
620       patches.  Attachments  can  be  made  by  going to the Edit form of the
621       ticket immediately after its creation, and  then  using  the  left-most
622       button in the secondary navigation bar.
623

SEE ALSO

625       doctools_intro,     doctools_lang_cmdref,    doctools_lang_faq,    doc‐
626       tools_lang_syntax
627

KEYWORDS

629       doctools commands, doctools language, doctools markup, doctools syntax,
630       markup, semantic markup
631

CATEGORY

633       Documentation tools
634
636       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
637
638
639
640
641tcllib                                1.0               doctools_lang_intro(n)
Impressum