1doctools_fmt(n) Documentation tools doctools_fmt(n)
2______________________________________________________________________________
6
8 doctools_fmt - Specification of a simple Tcl Markup Language for Man‐
9 pages
10
12 comment text
13 include filename
15 vset varname value
17 vset varname
19 lb
21 rb
23 manpage_begin command section version
25 manpage_end
27 moddesc desc
29 titledesc desc
31 copyright text
33 description
35 require pkg ?version?
37 section name
39 subsection name
41 para
43 see_also args
45 keywords args
47 arg text
49 cmd text
51 opt text
53 emph text
55 strong text
57 sectref text ?label?
59 syscmd text
61 method text
63 namespace text
65 option text
67 widget text
69 fun text
71 type text
73 package text
75 class text
77 var text
79 file text
81 uri text ?text?
83 term text
85 const text
87 nl
89 example_begin
91 example_end
93 example text
95 list_begin what
97 list_end
99 bullet
101 enum
103 lst_item text
105 call args
107 arg_def type name ?mode?
109 opt_def name ?arg?
111 cmd_def command
113 tkoption_def name dbname dbclass
115 usage args
117_________________________________________________________________
119
121 This document specifies version 1 of a text format for man pages. The
122 name of this format is doctools and it provides all the necessary com‐
123 mands to write a manpage. It is complemented by both the doctoc format
124 for writing tables of contents and the docidx format for writing key‐
125 word indices. The formal specifications for these two formats can be
126 found in the companion documents doctoc_fmt and docidx_fmt. A third
127 companion document describes the package doctools, which provides com‐
128 mands for the processing of text in doctools format.
129 Like for the formats doctoc and docidx a generic framework for the con‐
131 version of doctools to any number of different output formats is pro‐
132 vided. This framework is provided by the package doctools.
133 Anyone who wishes to write a toc formatting engine which plugs into
135 this framework has to read the document doctools_api. This is the for‐
136 mal specification of the API between the framework and its engines.
137
139 OVERVIEW
140 doctools is similar to LaTeX. Input written in this format consists
141 primarily of text, with markup commands embedded into it. The format
142 used to mark commands is different from LaTeX however. All text between
143 matching pairs of [ and ] is a command, possibly with arguments. Note
144 that both brackets have to be on the same line for a command to be rec‐
145 ognized.
146 In contrast to both doctoc and docidx this format does allow arbitrary
148 text between markup commands. Only some places are restricted to only
149 white space.
150 GRAMMAR
152 The overall syntax of a manpage is best captured in a formal context-
153 free grammar. Our notation for the grammar is EBNF. Strings will stand
154 for markup commands, however their arguments (if they have any) are not
155 part of the grammar. Our grammar contains lexical elements as well.
156 First we specify the whitespace and other text at the lexical level,
158 which also includes comments.
159 COMMENT ::= "comment"
161 WHITE ::= { '\n' | '\t' | ' ' | '\r' | COMMENT }
162 TEXT ::= { All characters except '[' }
163 Then we define rules for all the keywords. Here we introduce our knowl‐
166 edge that some commands allow only whitespace after them.
167 BEGIN ::= "manpage_begin" WHITE
169 END ::= "manpage_end"
170 TITLE ::= "titledesc" WHITE
171 MODULE ::= "moddesc" WHITE
172 REQUIRE ::= "require" WHITE
173 COPYRIGHT ::= "copyright" WHITE
174 DESC ::= "description"
175 SECTION ::= "section"
177 SUBSEC ::= "subsection"
178 PARA ::= "para"
179 NL ::= "nl"
180 SEE_ALSO ::= "see_also"
181 KEYWORDS ::= "keywords"
182 ARG ::= "arg"
184 CMD ::= "cmd"
185 OPT ::= "opt"
186 EMPH ::= "emph"
187 STRONG ::= "strong"
188 SECTREF ::= "sectref"
189 USAGE ::= "usage"
190 SYSCMD ::= "syscmd"
191 METHOD ::= "method"
192 NAMESPACE ::= "namespace"
193 OPTION ::= "option"
194 WIDGET ::= "widget"
195 FUN ::= "fun"
196 TYPE ::= "type"
197 PACKAGE ::= "package"
198 CLASS ::= "class"
199 VAR ::= "var"
200 FILE ::= "file"
201 URI ::= "uri"
202 TERM ::= "term"
203 CONST ::= "const"
204 LB ::= "lb"
205 RB ::= "rb"
206 EX_BEGIN ::= "example_begin"
207 EX_END ::= "example_end"
208 EXAMPLE ::= "example"
209 LIST_BEGIN ::= "list_begin" WHITE
211 LIST_END ::= "list_end"
212 LIST_ITEM ::= "lst_item"
213 BULLET ::= "bullet"
214 ENUM ::= "enum"
215 CALL ::= "call"
216 ARGDEF ::= "arg_def"
217 OPTDEF ::= "opt_def"
218 CMDDEF ::= "cmd_def"
219 TKODEF ::= "tkoption_def"
220 INCLUDE ::= "include"
222 VSET ::= "vset"
223 DEFUN ::= { INCLUDE | VSET }
224 At last we can specify the whole manpage. Here we introduce our knowl‐
226 edge that inclusion of other files may happen essentially everywhere,
227 like the definition of document variables and comments. The content of
228 any included file has to fit into the including file according to the
229 location in the grammar the inclusion is at.
230 MANPAGE ::= DEFUN BEGIN HEADER DESC BODY END
232 HEADER ::= { TITLE | MODULE | COPYRIGHT } { REQUIRE }
234 BODY ::= REGULAR_TEXT { SECTION SECBODY }
235 SECBODY ::= REGULAR_TEXT { SUBSEC SUBSECBODY }
236 SUBSECBODY ::= REGULAR_TEXT
237 REGULAR_TEXT ::= TEXT_CHUNK { PARA TEXT_CHUNK }
239 TEXT_CHUNK ::= { TEXT | DEFUN | XREF | MARKUP | COMMENT | A_LIST | AN_EXAMPLE }
240 A_LIST ::= LIST_BEGIN { ( LIST_ITEM | CALL ) LIST_TEXT } LIST_END
242 | LIST_BEGIN { BULLET LIST_TEXT } LIST_END
243 | LIST_BEGIN { ENUM LIST_TEXT } LIST_END
244 | LIST_BEGIN { ARGDEF LIST_TEXT } LIST_END
245 | LIST_BEGIN { OPTDEF LIST_TEXT } LIST_END
246 | LIST_BEGIN { CMDDEF LIST_TEXT } LIST_END
247 | LIST_BEGIN { TKODEF LIST_TEXT } LIST_END
248 LIST_TEXT ::= TEXT_CHUNK { NL TEXT_CHUNK }
250 AN_EXAMPLE ::= EXAMPLE | EX_BEGIN EXAMPLE_TEXT EX_END
252 EXAMPLE_TEXT ::= { TEXT | DEFUN | MARKUP }
253 MARKUP ::= { BRACKETS | SEMANTIC }
255 XREF ::= SEE_ALSO | KEYWORDS
257 BRACKETS ::= LB | RB
258 SEMANTIC ::= ARG | EMPH | CLASS | STRONG | OPTION
259 | CMD | TYPE | CONST | METHOD | SECTREF
260 | OPT | TERM | FUN | SYSCMD | PACKAGE
261 | VAR | FILE | USAGE | WIDGET | NAMESPACE
262 | URI
263 COMMANDS
266 Here we specify the commands used in the grammar. Some commands speci‐
267 fied here were not used in the grammar at all. The usage of these com‐
268 mands is confined to the arguments of other commands.
269 comment text
271 The command declares that the argument text is a comment.
272 include filename
274 This command loads the contents of the file filename for pro‐
275 cessing at its own place.
276 vset varname value
278 This form of the command sets the document variable varname to
279 the specified value. It does not generate output.
280 vset varname
282 This form of the command returns the value associated with the
283 document variable varname.
284 lb This command adds a left bracket to the output. Note that the
286 bracket commands are necessary as plain brackets are used to
287 begin and end the formatting commands.
288 rb This command adds a right bracket to the output. Note that the
290 bracket commands are necessary as plain brackets are used to
291 begin and end the formatting commands.
292 manpage_begin command section version
294 This is the command to start a manpage. The arguments are the
295 name of the command described by the manpage, the section of the
296 manpages this manpage resides in, and the version of the module
297 containing the command.
298 manpage_end
300 This is the command to close a manpage.
301 moddesc desc
303 This command is optional. When used it will register its argu‐
304 ment desc as a short description of the module the manpage
305 resides in.
306 titledesc desc
308 This command is optional. When used it will register its argu‐
309 ment desc as the title of the manpage. When not used the infor‐
310 mation from moddesc will be used for the title as well.
311 copyright text
313 This command is optional. When used its argument text will
314 declare a copyright assignment for the manpage. When invoked
315 more than once the assignments are accumulated.
316 A doctools processor application (like dtplite) is allowed to
318 provide such information too, but a formatting engine has to
319 give the accumulated arguments of this command precedence over
320 the data coming from the application.
321 description
323 This is the command to separate the header part of the manpage
324 from the main body.
325 require pkg ?version?
327 This is the command to list the packages which are required by
328 an application or other library to import the described package
329 and its prerequisites.
330 section name
332 This is the command to partition the body of the manpage into
333 named sections. Note that the command description at the begin‐
334 ning of the manpage body implicitly starts a section named
335 "DESCRIPTION". A section command implicitly closes the last
336 paragraph coming before it and also implicitly opens the first
337 paragraph of the new section.
338 subsection name
340 This is the command to partition the body of a section into
341 named sub-sections. A subsection command implicitly closes the
342 last paragraph coming before it and also implicitly opens the
343 first paragraph of the new section.
344 para This is the command to partition the text in a section or sub-
346 section into paragraphs. Each invokation closes the paragraph
347 coming before it and opens a new paragraph for the text coming
348 after.
349 see_also args
351 This is the command to define direct cross-references to other
352 documents. Each argument is a label identifying the referenced
353 document. If this command is used multiple times all the argu‐
354 ments accumulate.
355 keywords args
357 This is the command to define the keywords applying to this doc‐
358 ument. Each argument is a single keyword. If this command is
359 used multiple times all the arguments accumulate.
360 arg text
362 Declares that the argument text is the name of a command argu‐
363 ment.
364 cmd text
366 Declares that the argument text is the name of a command.
367 opt text
369 Declares that the argument text is something optional. Most
370 often used in conjunction with arg to denote optional command
371 arguments. Example:
372 [arg foo]
374 A regular argument.
375 [opt [arg foo]]
377 An optional argument.
378 emph text
381 Emphasize the text.
382 strong text
384 Emphasize the text. Same as emph. Usage of this command is dis‐
385 couraged. The command is deprecated and present only for back‐
386 ward compatibility.
387 sectref text ?label?
389 Declares that the argument text is the name of a section some‐
390 where else in the document, and the current location should
391 refer to it. Without an explicit label for the reference within
392 the text the section title text is used.
393 syscmd text
395 Declares that the argument text is the name of a system command.
396 method text
398 Declares that the argument text is the name of an object method.
399 namespace text
401 Declares that the argument text is the name of a namespace.
402 option text
404 Declares that the argument text is the name of an option.
405 widget text
407 Declares that the argument text is the name of a widget.
408 fun text
410 Declares that the argument text is the name of a function.
411 type text
413 Declares that the argument text is the name of a data type.
414 package text
416 Declares that the argument text is the name of a package.
417 class text
419 Declares that the argument text is the name of a class.
420 var text
422 Declares that the argument text is the name of a variable.
423 file text
425 Declares that the argument text is a file .
426 uri text ?text?
428 Declares that the argument text is an uri. The second argument,
429 if it is present, is the human-readable description of the uri.
430 In other words, the label for the link. Without a labeling text
431 the uri is used as its own label.
432 term text
434 Declares that the argument text contains some unspecific termi‐
435 nology.
436 const text
438 Declares that the argument text is a constant value.
439 nl This command signals vertical space to separate blocks of text.
441 example_begin
443 This command begins an example block. Subsequent text belongs to
444 the example. Line breaks, spaces, and tabs have to be preserved
445 literally.
446 example_end
448 This command closes the example block.
449 example text
451 This command wraps its argument text into an example. In other
452 words, it is a simpler form of markup for the creation of an
453 example. It should be used if the example text does not need
454 need special markup.
455 list_begin what
457 This command starts new list. The value of the argument what
458 determines what type of list is opened. This also defines what
459 command has to be used to start an item in the new list. The
460 allowed types (and their associated item commands) are:
461 bullet bullet
463 enum enum
465 definitions
467 lst_item and call
468 arg arg_def
470 cmd cmd_def
472 opt opt_def
474 tkoption
476 tkoption_def
477 list_end
480 This command ends the list opened by the last list_begin.
481 bullet This command starts a new list item in a bulletted list. The
483 previous item is automatically closed.
484 enum This command starts a new list item in an enumerated list. The
486 previous item is automatically closed.
487 lst_item text
489 This command starts a new list item in a definition list. The
490 argument is the term to be defined. The previous item is auto‐
491 matically closed.
492 call args
494 This command starts a new list item in a definition list, but
495 the term defined by it is a command and its arguments. The pre‐
496 vious item is automatically closed. The first argument is the
497 name of the described command, and everything after that are
498 descriptions of the command arguments.
499 arg_def type name ?mode?
501 This command starts a new list item in an argument list. The
502 previous item is automatically closed. Specifies the data-type
503 of the described argument, its name and its i/o-mode. The latter
504 is optional.
505 opt_def name ?arg?
507 This command starts a new list item in an option list. The pre‐
508 vious item is automatically closed. Specifies the name of the
509 option and its arguments (arg). The latter is a list, and can be
510 left out.
511 cmd_def command
513 This command starts a new list item in a command list. The pre‐
514 vious item is automatically closed. Specifies the name of the
515 command.
516 tkoption_def name dbname dbclass
518 This command starts a new list item in a widget option list. The
519 previous item is automatically closed. Specifies the name of
520 the option, i.e. the name used in scripts, the name used by the
521 option database (dbname), and the class (type) of the option
522 (dbclass).
523 usage args
525 This command is like call, except that a formatting engine must
526 not generate output at the location of the command. In other
527 words, this command is silent. The data it defines may appear in
528 a different section of the output, for example a table of con‐
529 tents, or synopsis, depending on the formatting engine and its
530 output format.
531
533 The sources of this manpage can serve as an example for all of the
534 markup described by it. Almost every possible construct is used here.
535
537 docidx_fmt, doctoc_fmt, doctools, doctools_api
538
540 HTML, LaTeX, TMML, generic markup, manpage, markup, nroff
541
543 Copyright (c) 2002-2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
544doctools 1.0 doctools_fmt(n)