1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin doctools_lang_syntax n 1.0] 3[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[moddesc {Documentation tools}] 5[titledesc {doctools language syntax}] 6[category {Documentation tools}] 7[description] 8[para] 9 10This document contains the formal specification of the syntax of the 11doctools markup language, version 1 in Backus-Naur-Form. This document 12is intended to be a reference, complementing the 13[term {doctools language command reference}]. 14 15A beginner should read the much more informally written 16[term {doctools language introduction}] first before trying to 17understand either this document or the command reference. 18 19 20[section Fundamentals] 21 22In the broadest terms possible the [term {doctools markup language}] 23is LaTeX-like, instead of like SGML and similar languages. A document 24written in this language consists primarily of text, with markup 25commands embedded into it. 26 27[para] 28 29Each markup command is a just Tcl command surrounded by a matching 30pair of [const [lb]] and [const [rb]]. Which commands are available, 31and their arguments, i.e. syntax is specified in the 32[term {doctools language command reference}]. 33 34[para] 35 36In this document we specify first the lexeme, and then the syntax, 37i.e. how we can mix text and markup commands with each other. 38 39[section {Lexical definitions}] 40 41In the syntax rules listed in the next section 42 43[list_begin enumerated] 44[enum] 45<TEXT> stands for all text except markup commands. 46 47[enum] 48Any XXX stands for the markup command [lb]xxx[rb] including its 49arguments. Each markup command is a Tcl command surrounded by a 50matching pair of [const [lb]] and [const [rb]]. Inside of these 51delimiters the usual rules for a Tcl command apply with regard to word 52quotation, nested commands, continuation lines, etc. 53 54[enum] 55<WHITE> stands for all text consisting only of spaces, newlines, 56tabulators and the [cmd comment] markup command. 57[list_end] 58 59[section Syntax] 60 61The rules listed here specify only the syntax of doctools 62documents. The lexical level of the language was covered in the 63previous section. 64 65[para] 66 67Regarding the syntax of the (E)BNF itself 68 69[list_begin enumerated] 70[enum] 71The construct { X } stands for zero or more occurrences of X. 72[enum] 73The construct [lb] X [rb] stands for zero or one occurrence of X. 74[enum] 75The construct LIST_BEGIN<X> stands for the markup command 76[cmd list_begin] with [const X] as its type argument. 77[list_end] 78 79The syntax: 80 81[example { 82manpage = defs 83 MANPAGE_BEGIN 84 header 85 DESCRIPTION 86 body 87 MANPAGE_END 88 { <WHITE> } 89 90defs = { INCLUDE | VSET | <WHITE> } 91 92header = { TITLEDESC | MODDESC | COPYRIGHT | REQUIRE | defs | xref } 93 94xref = KEYWORDS | SEE_ALSO | CATEGORY 95 96body = paras { SECTION sbody } 97sbody = paras { SUBSECTION ssbody } 98ssbody = paras 99 100paras = tblock { (PARA | NL) tblock } 101 102tblock = { <TEXT> | defs | markup | xref | an_example | a_list } 103 104markup = ARG | CLASS | CMD | CONST | EMPH | FILE 105 | FUN | LB | METHOD | NAMESPACE | OPT | OPTION 106 | PACKAGE | RB | SECTREF | STRONG | SYSCMD | TERM 107 | TYPE | URI | USAGE | VAR | WIDGET 108 109example = EXAMPLE 110 | EXAMPLE_BEGIN extext EXAMPLE_END 111 112extext = { <TEXT> | defs | markup } 113 114a_list = LIST_BEGIN<arguments> argd_list LIST_END 115 | LIST_BEGIN<commands> cmdd_list LIST_END 116 | LIST_BEGIN<definitions> def_list LIST_END 117 | LIST_BEGIN<enumerated> enum_list LIST_END 118 | LIST_BEGIN<itemized> item_list LIST_END 119 | LIST_BEGIN<options> optd_list LIST_END 120 | LIST_BEGIN<tkoptions> tkoptd_list LIST_END 121 122argd_list = [ <WHITE> ] { ARG_DEF paras } 123cmdd_list = [ <WHITE> ] { CMD_DEF paras } 124def_list = [ <WHITE> ] { (DEF|CALL) paras } 125enum_list = [ <WHITE> ] { ENUM paras } 126item_list = [ <WHITE> ] { ITEM paras } 127optd_list = [ <WHITE> ] { OPT_DEF paras } 128tkoptd_list = [ <WHITE> ] { TKOPTION_DEF paras } 129}] 130 131 132[section {BUGS, IDEAS, FEEDBACK}] 133 134This document, will undoubtedly contain bugs and other problems. 135 136Please report such in the category [emph doctools] of the 137[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 138 139Please also report any ideas for enhancements you may have. 140 141[see_also doctools_intro] 142[see_also doctools_lang_intro] 143[see_also doctools_lang_cmdref] 144[see_also doctools_lang_faq] 145[keywords markup {semantic markup}] 146[keywords {doctools markup} {doctools language}] 147[keywords {doctools syntax} {doctools commands}] 148[manpage_end] 149