◇◆
Introduction to Parameter Entities
This section describes each parameter entity used by the Archiving Tag Set, except
those that are part of MathML. (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 XML vocabularies
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:
Description (untitled)
|
This section provides a narrative description of the parameter entity,
describing what it contains, what it does, or why and when it has been used.
|
---|---|
Usage/Remarks
|
For some parameter entities, this section provides additional useful
information about the parameter entity or its usage.
Design Notes are instructions aimed at implementors, so they may better
appreciate the rationale underlying a design decision such as the inclusion of an
OR bar within a parameter entity. For example, inline-mix parameter entities
always begin with an OR bar to ease customization for those organizations wishing
only character data rather than a mixed content model for a particular element.
|
Declaration
|
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 Declaration
|
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
JATS uses 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 Journal Archiving 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 groupings of block-level elements. All
inline mixes begin with an OR bar. For example:
<!ENTITY % rendition-plus "| %all-phrase;" >
-
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 "(label?, title?, ((%kwd.class; | %x.class;)+ | (%unstructured-kwd-group.class;)* ) )" >
-
-elements — A group of elements to
be mixed with #PCDATA inside a mixed content model will be
named with a suffix “-elements”. For example,
%copyright-holder-elements; will be used in the model for the element <copyright-holder>.
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-holder-elements "| %institution-wrap.class; | %subsup.class; | %x.class;" >
Could be replaced by<!ENTITY % copyright-holder-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 <abstract> element would be
named “abstract-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 (JATS common atts being an exception). The parameter entities
contain at least one complete line of
an attribute list, excluding the ATTLIST Declaration.
<!ENTITY % abstract-atts "%jats-common-atts; abstract-type CDATA #IMPLIED specific-use CDATA #IMPLIED xml:lang NMTOKEN #IMPLIED %multi-lang-atts;" >