option.dtd-- Visualization of ../absy/option.dtd

<!-- file description --><!-- This is an html rendering of the DTD file 
         option.dtd
     This Xhtml file is DYNAMIC, using Java-script.
     The semantically relevant contents of the initial state 
     of this file DOES DIFFER from the input. 
       (pis omitted)
     This file has been created by the command line
          <JAVA> eu.bandm.tools.dtm.Tool --PIs offOn --source  \
             ../absy/option.dtd --result  \
             ../absy/doc-files/option.dtd-rendered.xhtml
     This file has been created at 2024-12-23_19h08m00 for public use.
     For info about this program see http://bandm.eu/metatools .
-->
<!-- collapse/expand --><!-- Click the opening symbols (angle brackets etc.) for collapsing/expanding.
     Click references for the definitions.
     Click element/attlist name position for the counterpart/next attlist. 
     Wait on a reference or on such a name for a tooltip.
     To control ALL declarations of one kind use these links:
     expand  all PIs  comments  elements  attlists  PEs  
     collaps all PIs  comments  elements  attlists  PEs  
-->
<!-- alphabetic indexes --><!-- =========================================================



Element declarations (FIXME undef references)
and  bool  comment  condition  constant  defaults  desc  dirOnly
enum  enumSetContains  enumeration  enumitem  enumset
float  int  isMeta  noGui  not  notDir  optarg  option
optionlist  or  printout_title  rat  rep  simpletypes
string  testequal  testgreater  text  type  uri  v  writable


Parameter entity declarations (FIXME undef references)
%conditions  %int  %primecondition  %simpletypes  %sorting  %testvalues


General entity declarations (FIXME undef references)

 ========================================================= --->


<!-- analyses --><!-- =========================================================

Parameter entities appearing DIRECTLY in content models:
%simpletypes  %testvalues  %conditions  

Parameter entities appearing INdirectly in content models:
%primecondition  

Parameter entities referred to, NOT in a content model,  :
%sorting  

Entities defined, but nowhere referred to:
%int  

Common attributes, identical name and type (ignoring value)
   in increasing frequency (minimally 1) :
one appearance of value :: NMTOKEN:
enumSetContains  

one appearance of required :: (yes | no):
option  

one appearance of compilable :: NMTOKEN:
enumitem  

one appearance of format :: (dez | hexI | hexIO):
int  

one appearance of abbrev :: NMTOKEN:
option  

one appearance of kind :: (plus | star):
rep  

one appearance of fragmentedLists :: (yes | no):
optionlist  

one appearance of defaultSorting :: (source | 0AaB | 0ABa | AaB0 | ABa0 | AaB | ABa):
optionlist  

one appearance of default :: NMTOKENS:
enumset  

one appearance of lang :: NMTOKEN:
text  

one appearance of setterFunctions :: (yes | no):
optionlist  

2 appearances of value :: CDATA:
constant  enumitem  

2 appearances of option :: NMTOKEN:
optarg  enumSetContains  

2 appearances of number :: NMTOKEN:
optarg  enumSetContains  

3 appearances of default :: CDATA:
rat  string  uri  

4 appearances of default :: NMTOKEN:
bool  float  enum  int  

5 appearances of name :: NMTOKEN:
comment  enumeration  enum  option  enumset  



Possible candidate elements for being declared abstract:
condition  not  simpletypes  

Content model entity candidates for abstract declaration:
%primecondition  %simpletypes  %testvalues  
 ========================================================= --->


<!-- entity usage graph --><!-- =========================================================

 ========================================================= --->
<!-- element containment graph --><!-- =========================================================

 ========================================================= --->
<!--  --><!-- XML 1.1 DTD  SYSTEM = "../option/absy/option.dtd" -->
<!--  --><!-- HAND-written dtd, due to bootstrapping. -->

<!-- ?tdom --><?tdom doc - Source format for the Option compiler, for command line parsing, GUI input, 
 generation of documentation, etc.
 <br/> See also the 
<a href="http://bandm.eu/metatools/docs/usage/option.html">option compiler user documentation</a>.
 <br/>
?>

<!--  --><!-- 
This relative link could be used, if we were sure, that the generated documentation
 (Java API Doc and dtd rendering) will only be viewed in the context of the meta-tools 
 user documentation file trees:
<a href="{@docRoot}/../usage/option.html">mt option compiler user documentation</a>. 
-->


<!-- ?tdom --><?tdom default private?>
<!-- ?tdom --><?tdom xmlns="http://bandm.eu/doctypes/option" ?>

<!-- %int --><!ENTITY % int 'NMTOKEN'>

<!-- %sorting --><!ENTITY % sorting '( source | 0AaB | 0ABa | AaB0 | ABa0 | AaB | ABa )'>
<!--  --><!-- 
    sort styles containing "0" = sort by short names,
       followed by those without short names
    position of "0"-character indicates position of numeric keys.
    sort styles not containing "0" = sort by long keys,
       followed by those without long names, finally numbers-only
    AaB means not respecting case
    ABa means respecting case
-->

<!-- ?tdom --><?tdom public optionlist?>
<!-- ?tdom --><?tdom doc optionlist Sequence of a collection of command line options, to
be compiled into GUI mask, online help method, parsing method, etc. 
(In several contexts, the sequential order is significant.) ?>
<!-- ?tdom --><?tdom doc optionlist@fragmentedLists Whether reperated option arguments may be continued
following some other option(s). ?>
<!-- ?tdom --><?tdom doc optionlist@setterFunctions Whether setter methods will be synthesized
for editing the value of an option instance ?>
<!-- EL optionlist --><!ELEMENT optionlist  (printout_title?, (enumeration | option | comment)*) >
<!-- @optionlist --><!ATTLIST optionlist  defaultSorting %sorting; "source"
                      fragmentedLists (yes|no) 'no' 
                      setterFunctions (yes|no) 'no' 
>


<!-- EL printout_title --><!ELEMENT printout_title (text)+>
<!-- ?tdom --><?tdom doc printout_title The text to be printed as a header line in the "usage()" function.
Can be specified for several languages. ?>

<!-- EL text --><!ELEMENT text (#PCDATA)>

<!-- @text --><!ATTLIST text  lang  NMTOKEN #REQUIRED>
<!-- ?tdom --><?tdom doc text One translation into one particular language. 
(Its role and meaning depend on the enclosing context element.) ?>

<!-- EL desc --><!ELEMENT desc (text)+>
<!-- ?tdom --><?tdom doc desc One description, in several languages. 
(Its role and meaning depend on the enclosing context element.) ?>



<!--  --><!-- =========================================================================== -->

<!-- EL enumeration --><!ELEMENT enumeration (desc?, (enumitem)+) >
<!-- @enumeration --><!ATTLIST enumeration name NMTOKEN #REQUIRED>
<!-- ?tdom --><?tdom doc enumeration An enumeration type which can be used for several parameters of
 several options ?>
<!-- ?tdom --><?tdom doc enumeration@name  Used to refer to this enumeration when defining the type
 of option parameters ?>


<!-- EL enumitem --><!ELEMENT enumitem (desc)? >
<!-- @enumitem --><!ATTLIST enumitem value      CDATA #REQUIRED
                   compilable NMTOKEN #IMPLIED
>
<!-- ?tdom --><?tdom doc enumitem One position in an enumeration type (represented by the enclosing
 context element). ?>
<!-- ?tdom --><?tdom doc enumitem@value  Text as which this item appears to the user, on the command line, in
 a GUI, etc. 
 It maybe not a valid Java identifier. In this case {@code @compilable} must be given. ?>
<!-- ?tdom --><?tdom doc enumitem@compilable  Text as which this item is realized in the generated code.
 It must be a valid Java identifier, and must be present if {@code @value} is not. ?>


<!--  --><!-- =========================================================================== -->

<!-- EL comment --><!ELEMENT comment (text)+>
<!-- @comment --><!ATTLIST comment name  NMTOKEN #IMPLIED>
<!-- ?tdom --><?tdom doc comment Multi-Lingual text which separates groups of options and appears in 
 a GUI screen mask, etc.  Mostly used for further explanations and directives to the user. ?>
<!-- ?tdom --><?tdom doc comment@name  mangled into a variable name which gives access to the
 corresponding graphic sub-object  in the generated GUI class. ?>

<!--  --><!-- =========================================================================== -->

<!-- EL option --><!ELEMENT option (noGui?, isMeta?, desc, type, condition?) >  

<!-- EL noGui --><!ELEMENT noGui EMPTY>
<!-- ?tdom --><?tdom doc isMeta marks options which are not represented in a generated GUI mask,
like "suppress splash window" ?>

<!-- EL isMeta --><!ELEMENT isMeta EMPTY>
<!-- ?tdom --><?tdom doc isMeta marks options which only affect the way of presentation, but not
the payload execution, like "suppress splash window" ?>

<!-- @option --><!ATTLIST option name     NMTOKEN #IMPLIED
                 abbrev   NMTOKEN #IMPLIED 
                 required (yes|no) "no"   >
<!-- ?tdom --><?tdom doc option Definition of one particular option as it appears on a command line,
 in the GUI, etc. At least one of {@code @name} or {@code @abbrev} must be given! ?>
<!-- ?tdom --><?tdom doc option@name  the long name, entered in the commandline with two minus signs,
 like "{@code --help}". Must have more than one character. ?>
<!-- ?tdom --><?tdom doc option@abbrev   the short name, entered in the commandline with one minus sign,
 like "{@code -h}". Must have exactly one character. ?>
<!-- ?tdom --><?tdom doc option@required Says whether this option must be present on the command line. 
 Is used to synthesize  checking code. ?>

<!-- %simpletypes --><!ENTITY %  simpletypes '(int | float | rat | bool | string | uri | enum | enumset)'>
<!-- EL simpletypes --><!ELEMENT simpletypes (%simpletypes;)>

<!-- EL type --><!ELEMENT type ( (%simpletypes;)*, rep?   )>
<!-- ?tdom --><?tdom doc type Sequence of the types of all arguments of a particular option . ?>


<!-- EL int --><!ELEMENT int EMPTY>
<!-- @int --><!ATTLIST int default    NMTOKEN #IMPLIED
              format     (dez | hexI | hexIO) "dez"
>
<!-- ?tdom --><?tdom doc int Describes one integer argument in an option's list of argument types. 
 Please note that negative ints cannot be entered at the beginnig of a repetition group
 due to parsing ambiguity. ?>
<!-- ?tdom --><?tdom doc int@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!-- EL float --><!ELEMENT float EMPTY>
<!-- @float --><!ATTLIST float default    NMTOKEN #IMPLIED>
<!-- ?tdom --><?tdom doc float Describes one floating point argument in an option's list of argument types.
(Floats can be translated to Java "float" or "double", controlled by an operation parameter. ?>
<!-- ?tdom --><?tdom doc float@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!-- EL rat --><!ELEMENT rat EMPTY>
<!-- @rat --><!ATTLIST rat default    CDATA #IMPLIED>
<!-- ?tdom --><?tdom doc rat Describes one rational number argument in an option's list of argument types. ?>
<!-- ?tdom --><?tdom doc float@default Default value in case the option is missing completely.
Must be verbatim valid Java source text, eg. a call to "rat.valueOf(..)" . ?>

<!-- EL bool --><!ELEMENT bool EMPTY>
<!-- @bool --><!ATTLIST bool default    NMTOKEN #IMPLIED>
<!-- ?tdom --><?tdom doc bool Describes one boolean argument in an option's list of argument types. ?>
<!-- ?tdom --><?tdom doc bool@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!-- EL string --><!ELEMENT string EMPTY>
<!-- @string --><!ATTLIST string default    CDATA #IMPLIED>
<!-- ?tdom --><?tdom doc string Describes one string value argument in an option's list of argument types. ?>
<!-- ?tdom --><?tdom doc string@default Default value in case the option is missing completely.
Can be any string (without framing double quotes) which will be processed into a 
valid String constant. ?>


<!-- EL uri --><!ELEMENT uri ((dirOnly | notDir)?, writable?) >
<!-- @uri --><!ATTLIST uri default    CDATA    #IMPLIED>
<!-- ?tdom --><?tdom doc uri Describes one uri value argument in an option's list of argument types. 
Is mostly used for file system positions / files.?>
<!-- ?tdom --><?tdom doc uri@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!-- EL dirOnly --><!ELEMENT dirOnly EMPTY>
<!-- ?tdom --><?tdom doc dirOnly Only directories are valid values. ?>
<!-- EL notDir --><!ELEMENT notDir EMPTY>
<!-- ?tdom --><?tdom doc dirOnly Only normal files = not directories are valid values. ?>
<!-- EL writable --><!ELEMENT writable EMPTY>
<!-- ?tdom --><?tdom doc writable The file or directory must be writable. ?>


<!-- EL rep --><!ELEMENT rep ( (%simpletypes;)+, defaults?) >
<!-- @rep --><!ATTLIST rep kind     (plus|star) #REQUIRED>
<!-- ?tdom --><?tdom doc rep Describes a sequence of value types in an option's list of argument types which 
 can appear more than once. ?>
<!-- ?tdom --><?tdom doc rep@kind Whether the empty sequence is a valid input ("star", not "plus") ?>


<!-- EL defaults --><!ELEMENT defaults (v)+>
<!-- EL v --><!ELEMENT v (#PCDATA)>
<!-- ?tdom --><?tdom doc defaults gives the sequence of default values for a repetition group, is the
 option is completely omitted. The number of contained elements must be an integral
 multiple of the length of the containing repetion group. ?>
<!-- ?tdom --><?tdom doc v One single default value. Must be verbatim valid Java source text,
except for Strings, where it must be the unquoted String contents.
This includes wrapping a String constant in double quotes, but allows expressions. ?>

<!-- EL enum --><!ELEMENT enum  EMPTY>
<!-- @enum --><!ATTLIST enum name NMTOKEN    #REQUIRED
               default NMTOKEN  #IMPLIED>
<!-- ?tdom --><?tdom doc enum  Refers to an Enumeration as the type of the value of an option's argument. ?>
<!-- ?tdom --><?tdom doc enum@name The name of the enum, for referring. ?>
<!-- ?tdom --><?tdom doc enum@default The enumeration item which shall be used as 
 default value, if the option is missing completely. The text must be the Java identifier,
 i.e. the  compilable version, not the command line version. ?>

<!-- EL enumset --><!ELEMENT enumset  EMPTY>
<!-- @enumset --><!ATTLIST enumset name    NMTOKEN    #REQUIRED
                  default NMTOKENS   #IMPLIED>
<!-- ?tdom --><?tdom doc enumset  Refers to an Enumeration as the base type for a set type for 
 the value of an option's argument. ?>
<!-- ?tdom --><?tdom doc enumset@name The name of the enum, for referring. ?>
<!-- ?tdom --><?tdom doc enumset@default The enumeration items which make the set value be used as 
 default value, if the option is missing completely. The text must be a sequence of 
 Java identifiers, i.e. the  compilable versions, not the command line versions. ?>


<!--  --><!-- =========================================================================== -->

<!-- %primecondition --><!ENTITY % primecondition '(testequal| testgreater|optarg|enumSetContains)'>
<!-- %conditions --><!ENTITY % conditions '((%primecondition;) | and | or | not)'>

<!-- EL condition --><!ELEMENT condition (%conditions;) >
<!-- EL and --><!ELEMENT and       (%conditions;)+ >
<!-- EL or --><!ELEMENT or        (%conditions;)+ >
<!-- EL not --><!ELEMENT not       (%conditions;) >
<!-- ?tdom --><?tdom doc condition Enabling condition which "un-greys" the input fields of an option,
 if fulfilled. ?>
<!-- ?tdom --><?tdom doc and Conjuntive combination of two conditions for enabling an option. ?>
<!-- ?tdom --><?tdom doc or Disjuntive combination of two conditions for enabling an option. ?>
<!-- ?tdom --><?tdom doc not Negation of a condition for enabling an option. ?>

<!-- %testvalues --><!ENTITY % testvalues '(constant | optarg)'>

<!-- EL testequal --><!ELEMENT testequal (%testvalues;,%testvalues;)>
<!-- ?tdom --><?tdom doc testequal Enabling condition whether both arguments have the same numric value. ?>

<!-- EL testgreater --><!ELEMENT testgreater (%testvalues;,%testvalues;)>
<!-- ?tdom --><?tdom doc testequal Enabling condition whether first argument is strictly larger 
 than the second. ?>

<!-- EL constant --><!ELEMENT constant EMPTY>
<!-- @constant --><!ATTLIST constant value CDATA  #REQUIRED>
<!-- ?tdom --><?tdom doc constant Constant to test against some current option argument value,
for forming an enabling condition. Must be verbatim compilable Java source text. 
Must be subject to Java's "==" comparison.
?>

<!-- EL optarg --><!ELEMENT optarg EMPTY>
<!-- @optarg --><!ATTLIST optarg option NMTOKEN #REQUIRED
                 number NMTOKEN "0"
                >
<!-- ?tdom --><?tdom doc optarg Reference to some option's current argument value, to test it in an
enabling  condition. ?>
<!-- ?tdom --><?tdom doc optarg@option The option from which the current argument value is taken. 
It is identified either by its long name or its short abbrev value. ?>
<!-- ?tdom --><?tdom doc optarg@number The argument of the option by its (zero-based) position index.
The value of this argument is taken either directly as boolean condition, or as subject of a comparison. 
 (The argument values of a repetition group are currently not adressable; neither is its length.) ?>

<!-- EL enumSetContains --><!ELEMENT enumSetContains EMPTY>
<!-- @enumSetContains --><!ATTLIST enumSetContains option NMTOKEN #REQUIRED
                          number NMTOKEN "0"
                          value NMTOKEN #REQUIRED
                          >
<!-- ?tdom --><?tdom doc enumSetContains Boolean value whether an enumeration set contains a particular value ?>
<!-- ?tdom --><?tdom doc enumSetContains@option The option from which the current argument value is taken. 
It is identified either by its long name or its short abbrev value. ?>
<!-- ?tdom --><?tdom doc enumSetContains@number The argument of the option by its (zero-based) position index.
 The value of this argument is taken for comparison. ?>
<!-- ?tdom --><?tdom doc enumSetContains@value The enumeration item the set is tested for.
Must be given by compilable Java source, i.e. by "[Type].[item]"
 ?>

<!--  --><!-- eof -->