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
61              manpage = defs
62                        MANPAGE_BEGIN
63                        header
64                        DESCRIPTION
65                        body
66                        MANPAGE_END
67                        { <WHITE> }
68
69              defs    = { INCLUDE | VSET | <WHITE> }
70
71              header  = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref }
72
73              xref    = KEYWORDS | SEE_ALSO | CATEGORY
74
75              body    = paras { SECTION    sbody  }
76              sbody   = paras { SUBSECTION ssbody }
77              ssbody  = paras
78
79              paras   = tblock { (PARA | NL) tblock }
80
81              tblock  = { <TEXT> | defs | markup | xref | an_example | a_list }
82
83              markup  = ARG     | CLASS | CMD     | CONST     | EMPH   | FILE
84                      | FUN     | LB    | METHOD  | NAMESPACE | OPT    | OPTION
85                      | PACKAGE | RB    | SECTREF | STRONG    | SYSCMD | TERM
86                      | TYPE    | URI   | USAGE   | VAR       | WIDGET
87
88              example = EXAMPLE
89                      | EXAMPLE_BEGIN extext EXAMPLE_END
90
91              extext  = { <TEXT> | defs | markup }
92
93              a_list  = LIST_BEGIN<arguments>   argd_list   LIST_END
94                      | LIST_BEGIN<commands>    cmdd_list   LIST_END
95                      | LIST_BEGIN<definitions> def_list    LIST_END
96                      | LIST_BEGIN<enumerated>  enum_list   LIST_END
97                      | LIST_BEGIN<itemized>    item_list   LIST_END
98                      | LIST_BEGIN<options>     optd_list   LIST_END
99                      | LIST_BEGIN<tkoptions>   tkoptd_list LIST_END
100
101              argd_list   = [ <WHITE> ] { ARG_DEF      paras }
102              cmdd_list   = [ <WHITE> ] { CMD_DEF      paras }
103              def_list    = [ <WHITE> ] { (DEF|CALL)   paras }
104              enum_list   = [ <WHITE> ] { ENUM         paras }
105              item_list   = [ <WHITE> ] { ITEM         paras }
106              optd_list   = [ <WHITE> ] { OPT_DEF      paras }
107              tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras }
108
109

BUGS, IDEAS, FEEDBACK

111       This  document,  and the package it describes, will undoubtedly contain
112       bugs and other problems.  Please report such in the  category  doctools
113       of  the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].  Please
114       also report any ideas for enhancements you may have for either  package
115       and/or documentation.
116
117       When proposing code changes, please provide unified diffs, i.e the out‐
118       put of diff -u.
119
120       Note further that  attachments  are  strongly  preferred  over  inlined
121       patches.  Attachments  can  be  made  by  going to the Edit form of the
122       ticket immediately after its creation, and  then  using  the  left-most
123       button in the secondary navigation bar.
124

SEE ALSO

126       doctools_intro,     doctools_lang_cmdref,    doctools_lang_faq,    doc‐
127       tools_lang_intro
128

KEYWORDS

130       doctools commands, doctools language, doctools markup, doctools syntax,
131       markup, semantic markup
132

CATEGORY

134       Documentation tools
135

137       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
138
139
140
141
142tcllib                                1.0              doctools_lang_syntax(n)
Impressum