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

NAME

8       doctools_lang_syntax - doctools language syntax
9

DESCRIPTION

11       This  document  contains  the formal specification of the syntax of the
12       doctools markup language, version 1 in Backus-Naur-Form. This  document
13       is intended to be a reference, complementing the doctools language com‐
14       mand reference.  A beginner should read the much more informally  writ‐
15       ten  doctools  language  introduction first before trying to understand
16       either this document or the command reference.
17

FUNDAMENTALS

19       In the broadest terms possible the doctools markup language  is  LaTeX-
20       like, instead of like SGML and similar languages. A document written in
21       this language consists primarily of text, with markup commands embedded
22       into it.
23
24       Each markup command is a just Tcl command surrounded by a matching pair
25       of [ and ]. Which commands are available,  and  their  arguments,  i.e.
26       syntax is specified in the doctools language command reference.
27
28       In this document we specify first the lexeme, and then the syntax, i.e.
29       how we can mix text and markup commands with each other.
30

LEXICAL DEFINITIONS

32       In the syntax rules listed in the next section
33
34       [1]    <TEXT> stands for all text except markup commands.
35
36       [2]    Any XXX stands for the markup command [xxx] including its  argu‐
37              ments.  Each  markup  command  is  a Tcl command surrounded by a
38              matching pair of [ and ]. Inside of these delimiters  the  usual
39              rules  for  a  Tcl  command apply with regard to word quotation,
40              nested commands, continuation lines, etc.
41
42       [3]    <WHITE> stands for all text consisting only of spaces, newlines,
43              tabulators and the comment markup command.
44

SYNTAX

46       The  rules  listed  here specify only the syntax of doctools documents.
47       The lexical level of the language was covered in the previous section.
48
49       Regarding the syntax of the (E)BNF itself
50
51       [1]    The construct { X } stands for zero or more occurrences of X.
52
53       [2]    The construct [ X ] stands for zero or one occurrence of X.
54
55       [3]    The  construct  LIST_BEGIN<X>  stands  for  the  markup  command
56              list_begin with X as its type argument.
57
58       The syntax:
59
60       manpage = defs
61                 MANPAGE_BEGIN
62                 header
63                 DESCRIPTION
64                 body
65                 MANPAGE_END
66                 { <WHITE> }
67
68       defs    = { INCLUDE | VSET | <WHITE> }
69
70       header  = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref }
71
72       xref    = KEYWORDS | SEE_ALSO | CATEGORY
73
74       body    = paras { SECTION    sbody  }
75       sbody   = paras { SUBSECTION ssbody }
76       ssbody  = paras
77
78       paras   = tblock { (PARA | NL) tblock }
79
80       tblock  = { <TEXT> | defs | markup | xref | an_example | a_list }
81
82       markup  = ARG     | CLASS | CMD     | CONST     | EMPH   | FILE
83               | FUN     | LB    | METHOD  | NAMESPACE | OPT    | OPTION
84               | PACKAGE | RB    | SECTREF | STRONG    | SYSCMD | TERM
85               | TYPE    | URI   | USAGE   | VAR       | WIDGET
86
87       example = EXAMPLE
88               | EXAMPLE_BEGIN extext EXAMPLE_END
89
90       extext  = { <TEXT> | defs | markup }
91
92       a_list  = LIST_BEGIN<arguments>   argd_list   LIST_END
93               | LIST_BEGIN<commands>    cmdd_list   LIST_END
94               | LIST_BEGIN<definitions> def_list    LIST_END
95               | LIST_BEGIN<enumerated>  enum_list   LIST_END
96               | LIST_BEGIN<itemized>    item_list   LIST_END
97               | LIST_BEGIN<options>     optd_list   LIST_END
98               | LIST_BEGIN<tkoptions>   tkoptd_list LIST_END
99
100       argd_list   = [ <WHITE> ] { ARG_DEF      paras }
101       cmdd_list   = [ <WHITE> ] { CMD_DEF      paras }
102       def_list    = [ <WHITE> ] { (DEF|CALL)   paras }
103       enum_list   = [ <WHITE> ] { ENUM         paras }
104       item_list   = [ <WHITE> ] { ITEM         paras }
105       optd_list   = [ <WHITE> ] { OPT_DEF      paras }
106       tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
107
108

BUGS, IDEAS, FEEDBACK

110       This  document,  will  undoubtedly  contain  bugs  and  other problems.
111       Please report such in the category doctools of the Tcllib  SF  Trackers
112       [http://sourceforge.net/tracker/?group_id=12883].   Please  also report
113       any ideas for enhancements you may have.
114

SEE ALSO

116       doctools_intro,    doctools_lang_cmdref,    doctools_lang_faq,     doc‐
117       tools_lang_intro
118

KEYWORDS

120       doctools commands, doctools language, doctools markup, doctools syntax,
121       markup, semantic markup
122

124       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
125
126
127
128
129doctools                              1.0              doctools_lang_syntax(n)
Impressum