# ------------------------------------------------------------------------
#
# This is the schema for helpdoc, written in its own schema-language
#
# ------------------------------------------------------------------------


# helpdoc schema-keywords: 
# ------------------------
#   #           -- comment
#   rootelement -- used to describe a root element
#   element     -- used to describe an element
#   attribute   -- used to describe an attribute
#   text        -- tells that the content of an element or attribute is a simple text
#   string      -- tells that the content of an element or attribute is a single word
#   ident       -- tells that element has an identifier (syntax: myelem myIdent { ... })
#   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 
#                  (should be specified before referencing it)
#   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
#   group       -- used for grouping items
#   ?           -- zero or one repetition of instances of anything enclosed is allowed
#   *           -- 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 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     { string }
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 info
	    ref see
	}
    }
}


#
# definition of complex elements
#

element list {
    ident 
    attribute type { string }

    interleave {
	element format { text }
	ref varTags
    }
}


element var {
    ident
    attribute type { string }        

    ref varTags
}
element vargroup {
    attribute type { string }            

    interleave {
	+ { ref var }
	ref varTags
    }
}


element dimension {
    ident
    attribute type  { string }   	
    attribute start { string }
    attribute end   { string }

    ref varTags
}
element dimensiongroup {
    attribute type  { string }
    attribute start { string }
    attribute end   { string }

    interleave {
	+ { ref dimension }
	ref varTags
    }
}


element table {
    ident
    
    choice {
	element rows {
	    attribute start { string }
	    attribute end   { string }
	    + {
		interleave {
		    optional {
			ref col
			ref optional
			ref conditional
			element colgroup {
			    attribute type { string }
			    interleave {
				+ { ref col }
				optional { 
				    ref varTags 
				    ref optional
				    ref conditional
				}			
			    }
			}
		    }
		}
	    }
	}
	element cols {
	    attribute start { string }
	    attribute end   { string }
	    + {
		interleave {
		    optional {
			ref row
			ref optional
			ref conditional
			element rowgroup {
			    attribute type { string }
			    interleave {
				+ { ref row }
				optional { 
				    ref varTags
				    ref optional
				    ref conditional
				}	
			    }
			}
		    }
		}
	    }
	}
    }
}

element col {
    ident
    optional {
	attribute type { string }
	ref varTags
    }
}
element row {
    ident
    optional {
	attribute type { string }
	ref varTags
    }
}


#
# higher level complex elements
#

element optional    { ancestorElements }
element conditional { ancestorElements }
element group       { ancestorElements }


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 { string }
	ref flag 
    }	
    
    + {
	interleave {
	    optional {
		ref syntax
		ref choose
		* { 
		    ref if 
		    ref label
		    ref message
		}
	    }    
	}
    }
}

element linecard {    
    interleave {
	+ {
	    optional {
		ref var
		ref vargroup
		ref list
	    }
	}
	optional {
	    ref optional
	    ref conditional
	}
    }
}

element flag { 
    ident
    optional { attribute use { string } }	    
    element enum { text }
    ref varTags
}

element syntax { 
    ? { attribute flag { text } }
    + {
	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 }