# ----------------------------------------------------------------------------
#
# 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 elemnt 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)
#   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 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 { string }
		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 dimensiongroup {
    attribute type  { word }
    attribute start { word }
    attribute end   { word }

    interleave {
	+ { ref dimension }
	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
@ ol { text }
@ ul { text }
@ li { text }

@ dl { text }
@ dt { text }
@ dd { text }