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

NAME

8       doctools_lang_cmdref - doctools language command reference
9

SYNOPSIS

11       arg text
12
13       arg_def type name ?mode?
14
15       bullet
16
17       call args
18
19       category text
20
21       class text
22
23       cmd text
24
25       cmd_def command
26
27       comment plaintext
28
29       const text
30
31       copyright text
32
33       def text
34
35       description
36
37       enum
38
39       emph text
40
41       example text
42
43       example_begin
44
45       example_end
46
47       file text
48
49       fun text
50
51       image name ?label?
52
53       include filename
54
55       item
56
57       keywords args
58
59       lb
60
61       list_begin what
62
63       list_end
64
65       lst_item text
66
67       manpage_begin command section version
68
69       manpage_end
70
71       method text
72
73       moddesc text
74
75       namespace text
76
77       nl
78
79       opt text
80
81       opt_def name ?arg?
82
83       option text
84
85       package text
86
87       para
88
89       rb
90
91       require package ?version?
92
93       section name
94
95       sectref id ?text?
96
97       sectref-external text
98
99       see_also args
100
101       strong text
102
103       subsection name
104
105       syscmd text
106
107       term text
108
109       titledesc desc
110
111       tkoption_def name dbname dbclass
112
113       type text
114
115       uri text ?text?
116
117       usage args
118
119       var text
120
121       vset varname value
122
123       vset varname
124
125       widget text
126
127______________________________________________________________________________
128

DESCRIPTION

130       This document specifies both names and syntax of all the commands which
131       together are the doctools markup language, version 1.  As this document
132       is  intended  to be a reference the commands are listed in alphabetical
133       order, and the descriptions are relatively short.   A  beginner  should
134       read  the  much  more informally written doctools language introduction
135       first.
136

COMMANDS

138       arg text
139              Text markup. The argument text is marked up as the argument of a
140              command.  Main uses are the highlighting of command arguments in
141              free-form text, and for the argument parameters  of  the  markup
142              commands call and usage.
143
144       arg_def type name ?mode?
145              Text  structure.  List  element.  Argument  list.  Automatically
146              closes the previous list element. Specifies the data-type of the
147              described  argument of a command, its name and its i/o-mode. The
148              latter is optional.
149
150       bullet Deprecated. Text structure. List  element.  Itemized  list.  See
151              item  for  the canonical command to open a list item in an item‐
152              ized list.
153
154       call args
155              Text structure. List  element.  Definition  list.  Automatically
156              closes  the previous list element. Defines the term as a command
157              and its arguments.  The first argument is the name of  the  com‐
158              mand  described  by  the following free-form text, and all argu‐
159              ments coming after that are descriptions of the command's  argu‐
160              ments.   It  is  expected  that the arguments are marked up with
161              arg, method, option etc., as is appropriate, and that  the  com‐
162              mand itself is marked up with cmd.  It is expected that the for‐
163              matted term is not only printed in place, but also in the  table
164              of  contents of the document, or synopsis, depending on the out‐
165              put format.
166
167       category text
168              Document information. Anywhere. This command registers its plain
169              text arguments as the category this document belongs to. If this
170              command is used multiple times the last value specified is used.
171
172       class text
173              Text markup. The argument is marked up as the name of  a  class.
174              The  text  may have other markup already applied to it. Main use
175              is the highlighting of class names in free-form text.
176
177       cmd text
178              Text markup. The argument text is marked up as the name of a Tcl
179              command.  The  text may have other markup already applied to it.
180              Main uses are the highlighting of commands  in  free-form  text,
181              and  for  the command parameters of the markup commands call and
182              usage.
183
184       cmd_def command
185              Text structure. List element. Command list. Automatically closes
186              the  previous  list  element. The argument specifies the name of
187              the Tcl command to be described by the list element. Expected to
188              be marked up in the output as if it had been formatted with cmd.
189
190       comment plaintext
191              Text  markup. The argument text is marked up as a comment stand‐
192              ing outside of the actual text of the document. Main use  is  in
193              free-form text.
194
195       const text
196              Text  markup. The argument is marked up as a constant value. The
197              text may have other markup already applied to it.  Main  use  is
198              the highlighting of constants in free-form text.
199
200       copyright text
201              Document  information. Anywhere. The command registers the plain
202              text argument as a copyright assignment for  the  manpage.  When
203              invoked more than once the assignments are accumulated.
204
205       def text
206              Text  structure.  List  element.  Definition list. Automatically
207              closes the previous list element. The argument text is the  term
208              defined  by  the new list element. Text markup can be applied to
209              it.
210
211       description
212              Document structure. This command separates the header  from  the
213              document  body.  Implicitly starts a section named "DESCRIPTION"
214              (See command section).
215
216       enum   Text structure. List  element.  Enumerated  list.  Automatically
217              closes the previous list element.
218
219       emph text
220              Text  markup. The argument text is marked up as emphasized. Main
221              use is for general highlighting  of  pieces  of  free-form  text
222              without attaching special meaning to the pieces.
223
224       example text
225              Text  structure, Text markup. This command marks its argument up
226              as an example. Main use is the simple embedding of  examples  in
227              free-form  text.  It should be used if the example does not need
228              special markup of its own. Otherwise use  a  sequence  of  exam‐
229              ple_begin ... example_end.
230
231       example_begin
232              Text  structure. This commands starts an example. All text until
233              the next example_end belongs to the example. Line  breaks,  spa‐
234              ces, and tabs have to be preserved literally. Examples cannot be
235              nested.
236
237       example_end
238              Text structure. This command closes the example started  by  the
239              last example_begin.
240
241       file text
242              Text  markup.  The argument is marked up as a file or directory,
243              i.e. in general a path. The text may have other  markup  already
244              applied  to  it.  Main use is the highlighting of paths in free-
245              form text.
246
247       fun text
248              Text markup. The argument is marked up as the name  of  a  func‐
249              tion. The text may have other markup already applied to it. Main
250              use is the highlighting of function names in free-form text.
251
252       image name ?label?
253              Text markup. The argument is the symbolic name of an  image  and
254              replaced  with  the image itself, if a suitable variant is found
255              by the backend. The second argument, should it be present,  will
256              be  interpreted the human-readable description of the image, and
257              put into the output in a suitable position, if such is supported
258              by  the  format. The HTML format, for example, can place it into
259              the alt attribute of image references.
260
261       include filename
262              Templating. The contents of the named file  are  interpreted  as
263              text  written  in the doctools markup and processed in the place
264              of the include command. The markup in the file has to  be  self-
265              contained.  It is not possible for a markup command to cross the
266              file boundaries.
267
268       item   Text  structure.  List  element.  Itemized  list.  Automatically
269              closes the previous list element.
270
271       keywords args
272              Document  information.  Anywhere. This command registers all its
273              plain text arguments as keywords applying to this document. Each
274              argument  is  a single keyword. If this command is used multiple
275              times all the arguments accumulate.
276
277       lb     Text. The command is replaced with a left bracket. Use in  free-
278              form  text.   Required to avoid interpretation of a left bracket
279              as the start of a markup command.
280
281       list_begin what
282              Text structure. This command starts a list. The exact nature  of
283              the list is determined by the argument what of the command. This
284              further determines which commands are have to be used  to  start
285              the  list  elements.  Lists can be nested, i.e. it is allowed to
286              start a new list within a list element.
287
288              The allowed types (and their associated item commands) are:
289
290              arguments
291                     arg_def.
292
293              commands
294                     cmd_def.
295
296              definitions
297                     def and call.
298
299              enumerated
300                     enum
301
302              itemized
303                     item
304
305              options
306                     opt_def
307
308              tkoptions
309                     tkoption_def
310
311       Additionally the following names are recognized as shortcuts  for  some
312       of the regular types:
313
314              args   Short for arguments.
315
316              cmds   Short for commands.
317
318              enum   Short for enumerated.
319
320              item   Short for itemized.
321
322              opts   Short for options.
323
324       At  last the following names are still recognized for backward compati‐
325       bility, but are otherwise considered to be deprecated.
326
327              arg    Deprecated. See arguments.
328
329              bullet Deprecated. See itemized.
330
331              cmd    Deprecated. See commands.
332
333              opt    Deprecated. See options.
334
335              tkoption
336                     Deprecated. See tkoptions.
337
338
339       list_end
340              Text structure. This command closes the list opened by the  last
341              list_begin command coming before it.
342
343       lst_item text
344              Deprecated.  Text  structure. List element. Definition list. See
345              def for the canonical command to open a general list item  in  a
346              definition list.
347
348       manpage_begin command section version
349              Document  structure.  The  command to start a manpage. The argu‐
350              ments are the name of the command described by the manpage,  the
351              section of the manpages this manpage resides in, and the version
352              of the module containing the command. All arguments have  to  be
353              plain text, without markup.
354
355       manpage_end
356              Document  structure. Command to end a manpage/document. Anything
357              in the document coming after this command is in error.
358
359       method text
360              Text markup. The argument text is marked up as the  name  of  an
361              object  method,  i.e.  subcommand of a Tcl command. The text may
362              have other markup already applied to it. Main uses are the high‐
363              lighting  of method names in free-form text, and for the command
364              parameters of the markup commands call and usage.
365
366       moddesc text
367              Document information. Header. Registers the plain text  argument
368              as a short description of the module the manpage resides in.
369
370       namespace text
371              Text markup. The argument text is marked up as a namespace name.
372              The text may have other markup already applied to it.  Main  use
373              is the highlighting of namespace names in free-form text.
374
375       nl     Deprecated.  Text  structure. See para for the canonical command
376              to insert paragraph breaks into the text.
377
378       opt text
379              Text markup. The argument text is marked  up  as  optional.  The
380              text  may  have  other markup already applied to it. Main use is
381              the highlighting of optional arguments, see the command arg arg.
382
383       opt_def name ?arg?
384              Text structure. List element. Option list. Automatically  closes
385              the  previous  list element. Specifies name and arguments of the
386              option described by the list element. It is  expected  that  the
387              name is marked up using option.
388
389       option text
390              Text  markup.  The argument is marked up as option. The text may
391              have other markup already applied to it. Main use is  the  high‐
392              lighting  of  options, also known as command-switches, in either
393              free-form text, or the arguments of the call and usage commands.
394
395       package text
396              Text markup. The argument is marked up as the name of a package.
397              The  text  may have other markup already applied to it. Main use
398              is the highlighting of package names in free-form text.
399
400       para   Text structure. This command breaks free-form  text  into  para‐
401              graphs.  Each  command closes the paragraph coming before it and
402              starts a new paragraph for the text  coming  after  it.  Higher-
403              level forms of structure are sections and subsections.
404
405       rb     Text. The command is replaced with a right bracket. Use in free-
406              form text.  Required to avoid interpretation of a right  bracket
407              as the end of a markup command.
408
409       require package ?version?
410              Document  information.  Header. This command registers its argu‐
411              ment package as the name of a package or application required by
412              the  described  package or application. A minimum version can be
413              provided as well. This argument can  be  marked  up.  The  usual
414              markup is opt.
415
416       section name
417              Text  structure.  This  command starts a new named document sec‐
418              tion. The argument has to be plain text. Implicitly  closes  the
419              last  paragraph  coming  before it and also implicitly opens the
420              first paragraph of the new section.
421
422       sectref id ?text?
423              Text markup. Formats a reference to the  section  identified  by
424              id.  If no text is specified the title of the referenced section
425              is used in the output, otherwise text is used.
426
427       sectref-external text
428              Text markup. Like sectref, except that the section is assumed to
429              be  in  a  different  document  and therefore doesn't need to be
430              identified, nor are any checks for existence made. Only the text
431              to format is needed.
432
433       see_also args
434              Document  information.  Anywhere.  The  command  defines  direct
435              cross-references to other documents. Each argument  is  a  plain
436              text  label identifying the referenced document. If this command
437              is used multiple times all the arguments accumulate.
438
439       strong text
440              Deprecated. Text markup. See emph for the canonical  command  to
441              emphasize text.
442
443       subsection name
444              Text  structure. This command starts a new named subsection of a
445              section. The argument has to be plain  text.  Implicitly  closes
446              the  last  paragraph  coming before it and also implicitly opens
447              the first paragraph of the new subsection.
448
449       syscmd text
450              Text markup. The argument text is marked up as the  name  of  an
451              external command. The text may have other markup already applied
452              to it. Main use is the  highlighting  of  external  commands  in
453              free-form text.
454
455       term text
456              Text  markup.  The argument is marked up as unspecific terminol‐
457              ogy.  The text may have other markup already applied to it. Main
458              use is the highlighting of important terms and concepts in free-
459              form text.
460
461       titledesc desc
462              Document information. Header. Optional. Registers the plain text
463              argument as the title of the manpage. Defaults to the value reg‐
464              istered by moddesc.
465
466       tkoption_def name dbname dbclass
467              Text structure. List element. Widget option list.  Automatically
468              closes  the previous list element. Specifies the name of the op‐
469              tion as used in scripts, the name used by  the  option  database
470              (dbname), and its class (dbclass), i.e. its type. It is expected
471              that the name is marked up using option.
472
473       type text
474              Text markup. The argument is marked up as the  name  of  a  data
475              type. The text may have other markup already applied to it. Main
476              use is the highlighting of data types in free-form text.
477
478       uri text ?text?
479              Text markup. The argument is marked up as an uri (i.e. a uniform
480              resource  identifier. The text may have other markup already ap‐
481              plied to it. Main use is the highlighting of uris  in  free-form
482              text.  The second argument, should it be present, will be inter‐
483              preted the human-readable  description  of  the  uri.  In  other
484              words,  as  its label. Without an explicit label the uri will be
485              its own label.
486
487       usage args
488              Text markup. See call for the full description, this command  is
489              syntactically  identical,  as  it is in its expectations for the
490              markup of its arguments.  In contrast to call it is however  not
491              allowed  to  generate  output  where  this command occurs in the
492              text. The command is silent.  The formatted text may only appear
493              in  a  different  section  of the output, for example a table of
494              contents, or synopsis, depending on the output format.
495
496       var text
497              Text markup. The argument is marked up as the name  of  a  vari‐
498              able. The text may have other markup already applied to it. Main
499              use is the highlighting of variables in free-form text.
500
501       vset varname value
502              Templating. In this form the command  sets  the  named  document
503              variable  to  the  specified value. It does not generate output.
504              I.e. the command is replaced by the empty string.
505
506       vset varname
507              Templating. In this form the command is replaced by the value of
508              the named document variable
509
510       widget text
511              Text  markup. The argument is marked up as the name of a widget.
512              The text may have other markup already applied to it.  Main  use
513              is the highlighting of widget names in free-form text.
514

BUGS, IDEAS, FEEDBACK

516       This  document,  and the package it describes, will undoubtedly contain
517       bugs and other problems.  Please report such in the  category  doctools
518       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
519       also report any ideas for enhancements you may have for either  package
520       and/or documentation.
521
522       When proposing code changes, please provide unified diffs, i.e the out‐
523       put of diff -u.
524
525       Note further that  attachments  are  strongly  preferred  over  inlined
526       patches.  Attachments  can  be  made  by  going to the Edit form of the
527       ticket immediately after its creation, and  then  using  the  left-most
528       button in the secondary navigation bar.
529

SEE ALSO

531       doctools_intro,     doctools_lang_faq,     doctools_lang_intro,    doc‐
532       tools_lang_syntax
533

KEYWORDS

535       doctools commands, doctools language, doctools markup, markup, semantic
536       markup
537

CATEGORY

539       Documentation tools
540
542       Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>
543
544
545
546
547tcllib                                1.0              doctools_lang_cmdref(n)
Impressum