quantum-espresso/dev-tools/helpdoc.schema

566 lines
10 KiB
Plaintext

# ----------------------------------------------------------------------------
#
# This is the schema for helpdoc DEF files, written in its own schema-language
#
# ----------------------------------------------------------------------------
##############################################################################
# helpdoc schema-keywords:
# ------------------------
#
### toplevel keywords:
#
# # -- comment
# rootelement -- used to describe a root element
# element -- used to describe an element
# attribute -- used to describe an attribute
# @ -- used to describe a special "@" prefixed elements that are allowed within the text
#
### keywords describing the content/data of leaf elements:
#
# empty -- tells that the element is empty, i.e., it is w/o content
# word -- tells that the content of an element is a single word (i.e. without spaces, \t, \n, \r)
# varname -- tells that the content of an element is a variable name; varname is a word with more a
# restrictive set of allowed characters; current regexp == (\w+([%]\w+)*)
# string -- tells that the content of an element or attribute is a string (it can contain spaces,
# i.e., string can be seen as a plain simple text)
# text -- tells that the content of an element is a text
# (text can contain special @ref and @link elements, which are
# expanded to <ref></ref> and <link></link> XML elements by helpdoc)
# clist -- tells that the content of an element or attribute is a comma-separated list
# (i.e. "word1, word2, word3, ...")
# plist -- tells that the content of an element or attribute is a pipe-separated list
# (i.e. "word1 | word2 | word3 | ...");
# the plist is used, e.g., to specify exclusive options
#
# ident -- tells that element has an identifier (DEF syntax: myelem myIdent { ... })
# ident must be a "word" (see above)
#
### ref & define keywords:
#
# ref -- used to specify the reference to an element (but the element is defined elsewhere)
# define -- used to define a group of elements or ref's that can be later-on referenced
# (should be specified before referencing it)
#
### keywords specifying optionality, repeatably, interleaving, ....
#
# interleave -- used to mark that the order of enclosed elements is not important
# optional -- used to mark anything enclosed as optional
# choice -- used to mark alternatice choices
# ? -- zero or one repetition of instances of anything enclosed is allowed (synonymous with "optional")
# * -- zero or more repetitions of instances of anything enclosed is allowed
# + -- one or more repetitions of instances of anything enclosed is allowed
#
# ancestorElements -- mark that all the elements (with rules, such as, optional,
# conditional, and repetition) of the ancestor are allowed
#
#######################
# IMPLICIT ASSUMPTIONS:
#----------------------
# - order of attributes is not important
# - attributes are mandatory (when they are not, use: optional { ... } keyword)
# - order of elements is important (when it is not, use: interleave { ... } keyword)
# - elements are mandatory (when they are not, use: optional { ... } keyword)
# ------------------------------------------------------------------------
# toplevel element
rootelement input_description {
attribute distribution { string }
attribute package { string }
attribute program { string }
optional {
interleave {
element intro { text }
element toc {}
}
}
+ {
interleave {
optional {
ref group
ref namelist
ref supercard
ref card
ref linecard
ref table
ref label
ref message
ref if
ref choose
ref optional
ref conditional
ref section
ref subsection
ref subsubsection
ref paragraph
}
}
}
}
#
# definition of simple elements
#
element info { text }
element default { text }
element status { text }
element label { text }
element message { text }
element see { clist }
element keyword { ident }
#
# define what elements are used within var, dimension, ...
# (will be used many times)
#
define varTags {
interleave {
optional {
ref status
ref default
ref see
}
}
interleave {
* { ref info }
? { ref options }
}
}
#
# definition of complex elements
#
element options {
interleave {
* {
ref info
}
+ {
element opt {
attribute val { clist }
text
}
}
}
}
element list {
ident
attribute type { word }
interleave {
element format { string }
ref varTags
}
}
element var {
ident
attribute type { word }
ref varTags
}
element vargroup {
attribute type { word }
interleave {
+ { ref var }
ref varTags
}
}
element dimension {
ident
attribute type { word }
attribute start { word }
attribute end { word }
ref varTags
}
element multidimension {
ident
attribute type { word }
attribute indexes { clist }
attribute start { clist }
attribute end { clist}
ref varTags
}
element dimensiongroup {
attribute type { word }
attribute start { word }
attribute end { word }
interleave {
+ { ref dimension }
ref varTags
}
}
element multidimensiongroup {
attribute type { word }
attribute indexes { clist }
attribute start { clist }
attribute end { clist }
interleave {
+ { ref multidimension }
ref varTags
}
}
element table {
ident
choice {
element rows {
attribute start { word }
attribute end { word }
+ {
interleave {
optional {
ref col
ref optional
ref conditional
element colgroup {
attribute type { word }
interleave {
+ { ref col }
optional {
ref varTags
ref optional
ref conditional
}
}
}
}
}
}
}
element cols {
attribute start { word }
attribute end { word }
+ {
interleave {
optional {
ref row
ref optional
ref conditional
element rowgroup {
attribute type { word }
interleave {
+ { ref row }
optional {
ref varTags
ref optional
ref conditional
}
}
}
}
}
}
}
}
}
element col {
ident
optional {
attribute type { word }
ref varTags
}
}
element row {
ident
optional {
attribute type { word }
ref varTags
}
}
#
# higher level complex elements
#
element optional { ancestorElements }
element conditional { ancestorElements }
element group { ancestorElements }
element supercard {
ident
optional {
attribute starttag { word }
attribute endtag { word }
attribute remark { text }
}
interleave {
+ {
optional {
ref supercard
ref namelist
ref card
ref linecard
}
}
* {
optional {
ref if
ref choose
ref label
ref message
ref optional
ref conditional
}
}
}
}
element namelist {
ident
interleave {
+ {
optional {
ref var
ref vargroup
ref dimension
ref dimensiongroup
}
}
* {
optional {
ref group
ref label
ref message
ref if
ref choose
}
}
}
}
element card {
ident
optional {
attribute nameless { word }
ref flag
}
+ {
interleave {
optional {
ref syntax
ref choose
* {
ref if
ref label
ref message
}
}
}
}
}
element linecard {
interleave {
+ {
optional {
ref keyword
ref var
ref vargroup
ref list
}
}
optional {
ref optional
ref conditional
}
}
}
element flag {
ident
optional { attribute use { word } }
element enum { plist }
ref varTags
}
element syntax {
? { attribute flag { plist } }
+ {
interleave {
optional {
ref line
ref table
ref optional
ref conditional
}
}
}
}
element line {
+ {
interleave {
optional {
ref group
ref keyword
ref var
ref vargroup
ref list
ref if
ref choose
ref label
ref message
ref optional
ref conditional
}
}
}
}
element if {
attribute test { text }
optional { ref label }
ancestorElements
}
element choose {
element when {
attribute test { text }
optional { ref label }
ancestorElements
}
* {
element elsewhen {
attribute test { text }
optional { ref label }
ancestorElements
}
}
? {
element otherwise {
optional { ref label }
ancestorElements
}
}
}
#
# some text structure stuff
#
element section {
attribute title { text }
+ {
interleave {
optional {
ref subsection
ref subsubsection
ref paragraph
ref text
}
}
}
}
element subsection {
attribute title { text }
+ {
interleave {
optional {
ref subsubsection
ref paragraph
ref text
}
}
}
}
element subsubsection {
attribute title { text }
+ {
interleave {
optional {
ref paragraph
ref text
}
}
}
}
element paragraph {
attribute title { text }
ref text
}
element text { text }
#---------------
# Special @ prefixed elements that are allowed within the text
#
# within the text these are uses as:
# @tag -- for empty elements, defined below as @ tag { empty }
# @tag word -- for word and text elements, defined below as "@ tag { word }" or "@ tag { text }"
# @tag { many words text } -- for text elements, defined below as "@ tag { text }"
#
# ref: used inside text for referencing a variable inside a document (usage: @ref var)
@ ref { varname }; # varname is a word with more a restrictive set of
# allowed characters; current regexp == (\w+([%]\w+)*)
# link: used inside text to link to an external document (usage: @link doc)
@ link { word }
#--------------------
# let's support some basic HTML tags
# text-styles
@ b { text }
@ i { text }
@ tt { text }
@ u { text }
@ sub { text }
@ sup { text }
@ code { text }
@ pre { text }
# breaks, rule, paragraph ...
@ br { empty }
@ hr { empty }
@ p { empty }
## lists (currently disabled : nested @tag commands do not work properly)
#@ ol { text }
#@ ul { text }
#@ li { text }
#
#@ dl { text }
#@ dt { text }
#@ dd { text }