# ----------------------------------------------------------------------------
#
# 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 }