Appendix C Documentation File Grammar

Conventions

module

denotes a non terminal

`--'

denotes a literal

IDENTIFIER

denotes a terminal

[ x ]

denotes zero or one occurrences of x.

{ x }

denotes zero or more occurrences of x.

(x | y)

means one of either x or y.

‘^’

denotes start of line

‘$’

denotes end of line

Grammar

• documentation → package
• package → package-line description {module | topic} [end-package-line]
• package-line → ^ `Package:' IDENTIFIER [`--' SHORT-DESCRIPTION] $
• end-package-line → ^ `End Package:' IDENTIFIER $
• description → { description-item }
• description-item → paragraph | code | remark | list | preformatted | image | table
• module → module-line description { note | notes } module-element-list [end-module-line]
• module-element-list → { element | elements | struct | topic }
• module-line → ^ `Module:' IDENTIFIER [`--' SHORT-DESCRIPTION] $
• end-module-line → ^ `End Module:' IDENTIFIER $
• topic → topic-line description { note | notes } { sub-topic }
• sub-topic → sub-topic-line description { note | notes }
• topic-line → ^ `Topic:' IDENTIFIER [`--' SHORT-DESCRIPTION] $
• sub-topic-line → ^ `Sub Topic:' IDENTIFIER [`--' SHORT-DESCRIPTION] $
• paragraph → { TEXT-LINE }
• code → code-line preformatted
• code-line → ^ `Code:' $
• remark → ^ `Remark:' SHORT-DESCRIPTION $
• list → ordered-list | unordered-list | definition-list
• definition-list → { definition-list-line }
• definition-list-line → ^ `::' TERM `--' DEFINITION $
• ordered-list → { ordered-list-line }
• ordered-list-line → ^ `+' TEXT $
• unordered-list → { unordered-list-line }
• unordered-list-line → ^ `-' TEXT $
• preformatted → { preformatted-line }
• preformatted-line → ^ `>' TEXT $
• image → ^ `Image:' FILE-NAME `--' CAPTION $
• table → [table-line] [table-header-line] { table-row-line }
• table-line → ^ `Table:' CAPTION $
• table-header-line → ^ `||' { CELL `|' } $
• table-row-line → ^ `|' { CELL `|' } $
• note → ^ `Note:' SHORT-DESCRIPTION $
• notes → notes-line { unordered-list }
• notes-line → ^ `Notes:' $
• element → element-line description element-extra [{errors | example | version}]
• element-extra → { sub-elements | result | see-also | note | notes }
• element-line → ^ `Element:' IDENTIFIER [`--' SHORT-DESCRIPTION] $
• elements → elements-line { elements-item-line }
• elements-line → ^ `Elements:' $
• elements-item-line → ^ `-' IDENTIFIER `--' [SHORT-DESCRIPTION] $
• struct → struct-line description struct-element-list [end-struct-line]
• struct-element-list → { element | elements | struct | topic }
• struct-line → ^ `Struct:' IDENTIFIER [`--' SHORT-DESCRIPTION] $
• end-struct-line → ^ `End Struct:' IDENTIFIER $
• errors → errors-line description
• errors-line → ^ `Errors:' $
• example → ^ `Example:' FILE-NAME $
• version → version-line description
• version-line → ^ `Version:' $
• sub-elements → sub-elements-line { sub-elements-item }
• sub-elements-line → ^ `Sub Elements:' $
• sub-elements-item → `-' IDENTIFIER `--' SHORT-DESCRIPTION
• result → ^ `Result:' SHORT-DESCRIPTION $
• see-also → ^ `See Also:' LINKS $