Introduction to Parameter Entities
This section describes each parameter entity in the Article Authoring Tag Set as well as
those in the base Suite that are used by this Tag Set, except those that are part of MathML,
the NISO JATS XHTML-inspired table structure, or the OASIS Interchange CALS table structure. (Note: The
MathML modules come from external sources; see the documentation provided by the authority
responsible for the MathML Tag Set. The NISO JATS XHTML-inspired Table Module is
maintained and defined as part of NISO JATS, but see also the W3C XHTML documentation. A separate Tag Library describing the OASIS Exchange CALS Table model is available at: https://jats.nlm.nih.gov/options/OASIS/tag-library/19990315/index.html)
A parameter entity is an XML syntactic construct that allows a name to be given to a
collection of elements, attributes, or attribute values so that they can be referred to by name
rather than have their members listed every time they are used. For example, the name
%person-name.class; stands for all the element components
of a person’s name, such as any title or honorific preceding the person’s name, a
given (first) name, a surname, and any suffix following the name (such as “Jr.”).
Parameter Entity Pages
Although the parameter entities are declared in many different modules, they are described
here in alphabetical order of their XML names (i.e., parameter entity type names). The XML name
is the shorter machine-readable name used in DTD fragments and schemas and by software; for
example, the XML name %app.class; is used for the
parameter entity named Just Appendix Class Elements. Parameter entity
names always begin with a percent sign and end with a semi-colon.
Each parameter entity is described by a separate HTML page, where the heading for the page
displays the parameter entity’s XML name followed by a more descriptive name. The rest
of the parameter entity description page discusses aspects of the parameter entity and its
usage. These sections within the page always appear in the following order although any given
parameter entity description may not contain all the sections:
Definition (untitled) | This section provides a narrative description of the parameter entity, describing what
it contains, what it does, or why and when it should be used. |
|---|---|
Remarks | For some parameter entities, this section provides additional useful information about
the parameter entity or its usage. |
Model | Contains a copy of the parameter entity’s declaration in XML syntax, i.e., the
“content” of the parameter entity. This may contain embedded parameters
entities, of the form
“%name;”. |
Expanded Model | Contains a copy of the parameter entity’s declaration in XML syntax, i.e., the
“content” of the parameter entity with all embedded parameter entities
expanded to their ultimate values. |
Parameter Entity Naming Conventions
This Tag Set and the Suite modules have used a series of design and naming conventions
consistently. While parsing software cannot enforce these parameter entity usage or naming
conventions, these conventions can make it much easier for a person to know how the content
models work. The Article Authoring Tag Set (and the entire JATS DTD Suite) use
the following usage and naming conventions.
- Classes — Classes are functional OR-groups of
elements. All class names end in the suffix “.class”. For
example:
<!ENTITY % list.class "def-list | list" >
Classes cannot be made empty; the class should just be removed from all models where you do not want the elements included. - Mixes — Mixes are OR-groups of classes. All
mixes must be declared after all classes, since mixes are composed of classes. (In best
practice, mixes never contain element names directly.) Mix names have no set suffix, and only
a few have been named “-mix”. Some mixes are inline to be
intermingled with #PCDATA in a mixed content model while other mixes are
grouping of block-level elements. All inline mixes begin with an OR bar. For example:
<!ENTITY % rendition-plus "| %emphasis.class; | %subsup.class;" > - Content — Content models and content model
overrides use mixes and classes for all OR groups. Only sequences are made up of element
names directly. Content models overrides are of two types, which are defined separately to
preserve the mixed-content or element-content nature of the models as an aid to interchange.
- -models — The override of a complete content
model will be named with a suffix “-model”. The override
contains the entire content model, including the enclosing
parentheses, for example:
<!ENTITY % kwd-group-model "(title?, (%kwd.class;)+ )" > - -elements — A grouping of elements to be mixed
with #PCDATA inside a mixed content model will be named with a suffix
“-elements”. For example, “%copyright-statement-elements;” would be used in the
model for the element <copyright-statement>.
All “-elements” overrides begin with an OR bar, so that a model
may exclude all elements and be reduced to #PCDATA. For example:
<!ENTITY % copyright-statement-elements "| %address-link.class; | %emphasis.class; | %phrase-content.class; | %subsup.class;" >Could be replaced by<!ENTITY % copyright-statement-elements " " >
- -models — The override of a complete content
model will be named with a suffix “-model”. The override
contains the entire content model, including the enclosing
parentheses, for example:
- Attribute lists — Attribute lists for a
particular element are named with the name of the element followed by the suffix
“-atts”, so, for example, the attributes for the <sec> element would be named %sec-atts;. Such lists are not reused as frequently as they
might be in many tag sets, to provide maximum flexibility. Attribute lists for different
elements are rarely tied together. The parameter entities contain at least one complete line
of an attribute list, excluding the ATTLIST Declaration.
<!ENTITY % sec-atts "%jats-common-atts; sec-type CDATA #IMPLIED specific-use CDATA #IMPLIED xml:lang NMTOKEN #IMPLIED" >