Difference between revisions of "Schema generation"
(ODD documentation) |
|||
| Line 14: | Line 14: | ||
;element & module inclusion, and element deletion section | ;element & module inclusion, and element deletion section | ||
| − | : <moduleRef></tt>s with <tt>@include</tt> or <tt>@except</tt>. If we had any <tt>schemaSpec/elementRef</tt> elements they would probably be here, too. | + | :<moduleRef></tt>s with <tt>@include</tt> or <tt>@except</tt>. If we had any <tt>schemaSpec/elementRef</tt> elements they would probably be here, too. |
;ODD/Schematron hack section | ;ODD/Schematron hack section | ||
| − | : section for top-level <tt><constraintSpec></tt>s. In looking at this now, it should either be re-named or divided into two sections (and renamed). | + | :section for top-level <tt><constraintSpec></tt>s. In looking at this now, it should either be re-named or divided into two sections (and renamed). |
;element renaming section | ;element renaming section | ||
| − | : set of <tt><elementSpec></tt> elements for cases in which the primary change being made is to change the name of the element. Often other changes are made, as well, but they are usually “minor” changes. E.g., the <tt><titlePage></tt> element is changed to the <tt><titleBlock></tt> element here, but also has a controlled vocabulary for its <tt>@type</tt> established here. (Fnote: this is because you cannot have two <tt><elementSpec></tt> elements with the same <tt>@ident</tt> and <tt>@ns</tt> attributes in a single ODD, yet.) | + | :set of <tt><elementSpec></tt> elements for cases in which the primary change being made is to change the name of the element. Often other changes are made, as well, but they are usually “minor” changes. E.g., the <tt><titlePage></tt> element is changed to the <tt><titleBlock></tt> element here, but also has a controlled vocabulary for its <tt>@type</tt> established here. (Fnote: this is because you cannot have two <tt><elementSpec></tt> elements with the same <tt>@ident</tt> and <tt>@ns</tt> attributes in a single ODD, yet.) |
| − | |||
| − | |||
| − | |||
;element addition section | ;element addition section | ||
| + | :new elements we have added. Note that this should be a subsection of the EXTENSIONS section, below. | ||
;class deletion section | ;class deletion section | ||
| + | :for deletion of entire classes (“scorched earth” approach for attribute deletion; we do not delete any model classes) | ||
;attribute deletion section | ;attribute deletion section | ||
| + | :for removing attributes from elements or classes (the “selective thinning” and “repossession” approaches to attribute removal) | ||
;class addition section | ;class addition section | ||
| + | :for addition of '''attribute''' classes. The '''model''' classes are added in the “new class subsection” of the “EXPANSIONS” section, not sure why. | ||
;other class and macro manipulation section | ;other class and macro manipulation section | ||
| + | :changes to datatypes, macros, and classes | ||
;section for changes to content models of "normal" TEI elements | ;section for changes to content models of "normal" TEI elements | ||
| − | ;required element section | + | :in some cases the change is only to attributes, not content model |
| − | ;attribute constraint section | + | ;required element section |
| − | ; | + | :a complex Schematron check to require certain elements that are optional in TEI |
| − | ;class manipulation subsection | + | ;attribute constraint section |
| − | ;new class subsection | + | :constraining some attributes further than vanilla TEI, e.g. constrained value list or required instead of optional |
| + | ;EXPANSIONS | ||
| + | :Changes in this section need to be in a non-TEI namespace. Since our entire markup language is in our own non-TEI namespace, this doesn't really mean much to us. But most such changes are segregated to here in order to make changing this to a TEI-conformant customization a bit easier. | ||
| + | :;class manipulation subsection | ||
| + | ::non-conformant changes to classes | ||
| + | :;new class subsection | ||
| + | ::added model classes | ||
;macro addition section | ;macro addition section | ||
| + | :macros we added (to make writing the ODD easier) | ||
;stuff leftover from EMPB that I still need to look at | ;stuff leftover from EMPB that I still need to look at | ||
| − | ;miscellaneous section | + | :I guess |
| + | ;miscellaneous section | ||
| + | :as it says | ||
;XInclude section | ;XInclude section | ||
| + | :the XInclude attributes defined in ODD | ||
Revision as of 17:28, 10 September 2020
Generating Schemas (and Documentation) from ODD
The ODD itself
The source customization ODD file for the wwp-store encoding language is in our textbase Subversion repository in textbase/schema/wwp-store.odd. It should be valid against the current or the development version of tei_odds. It should almost be valid against either the current or the development version of tei_customization. (There are a few “errors”, as that schema is designed to help write the ODD, not validate it.) In all 4 of those cases it should also be valid against the associated Schematron rules.
The edition number is stored on /TEI/teiHeader/fileDesc/editionStmt/edition/@n in major.minor.fix format. Any change to the ODD that represents a deliberate change to the set of documents validated by the schema ups the minor version number. Changes to only prose or class names or such may be reflected in only the fix number. The major number is reserved for overhauls or other very significant changes. (The last one, e.g., was the change from the TEI ODD language to the TEI PureODD language — i.e., purging (most of) the RELAX NG from the ODD.) The edition number is usually also reflected on the @n of the <change> element describing the change that brings the ODD up to the specified version.
The Subversion $Id:$ is also stored as the content of that <edition. In general it should not be updated by hand, but rather by Subversion on check-in. (This requires that the svn:keywords property be set, which it is.)
Currently the <schemaSpec> element is stored in <body>; someday soon I would like to move it to <back>, reserving the body for prose discussion.
The ODD file is loosely divided into “sections” delimited by nothing other than box comments. A list of those sections follows, in the order they currently occur in the ODD file. (But since the order of the specification children of <schemaSpec> is not constrained by TEI and is insignificant to an ODD processor, it may have changed in the ODD with no effect.)
- element & module inclusion, and element deletion section
- <moduleRef>s with @include or @except. If we had any schemaSpec/elementRef elements they would probably be here, too.
- ODD/Schematron hack section
- section for top-level <constraintSpec>s. In looking at this now, it should either be re-named or divided into two sections (and renamed).
- element renaming section
- set of <elementSpec> elements for cases in which the primary change being made is to change the name of the element. Often other changes are made, as well, but they are usually “minor” changes. E.g., the <titlePage> element is changed to the <titleBlock> element here, but also has a controlled vocabulary for its @type established here. (Fnote: this is because you cannot have two <elementSpec> elements with the same @ident and @ns attributes in a single ODD, yet.)
- element addition section
- new elements we have added. Note that this should be a subsection of the EXTENSIONS section, below.
- class deletion section
- for deletion of entire classes (“scorched earth” approach for attribute deletion; we do not delete any model classes)
- attribute deletion section
- for removing attributes from elements or classes (the “selective thinning” and “repossession” approaches to attribute removal)
- class addition section
- for addition of attribute classes. The model classes are added in the “new class subsection” of the “EXPANSIONS” section, not sure why.
- other class and macro manipulation section
- changes to datatypes, macros, and classes
- section for changes to content models of "normal" TEI elements
- in some cases the change is only to attributes, not content model
- required element section
- a complex Schematron check to require certain elements that are optional in TEI
- attribute constraint section
- constraining some attributes further than vanilla TEI, e.g. constrained value list or required instead of optional
- EXPANSIONS
- Changes in this section need to be in a non-TEI namespace. Since our entire markup language is in our own non-TEI namespace, this doesn't really mean much to us. But most such changes are segregated to here in order to make changing this to a TEI-conformant customization a bit easier.
- class manipulation subsection
- non-conformant changes to classes
- new class subsection
- added model classes
- macro addition section
- macros we added (to make writing the ODD easier)
- stuff leftover from EMPB that I still need to look at
- I guess
- miscellaneous section
- as it says
- XInclude section
- the XInclude attributes defined in ODD