Tag Set and Suite Naming Conventions

XML Component Naming Conventions

Basic Element and Attribute Naming Rules

  • CASE — All XML names originating in this Tag Set or in the Suite are to be in lower case. Such names include element names, attribute names, parameter entity names, notation names, and IDs. The casing and interior punctuation of element-type names, attribute names, and parameter entity names inherited from PUBLIC models (such as the XHTML table model, MathML Tag Set, or the OASIS CALS Exchange Table Model) are unchanged. That means that they occur in the case in which they were found in the original module, and so may be in mixed case or upper case (e.g., %Flow.mix;).
  • TWO-WORD NAMES — When two or more words are concatenated into an element name, attribute name, or parameter entity name, a hyphen is placed between the words, for example, <verse-group>, <article-title>, <word-count>.
  • WORD STANDARDIZATION — Abbreviations may be used when words are used in combination. When a word stands alone as a name, it is not abbreviated. Thus, the element <subject> uses the full word “subject”, but the subject combination, Subject Group, uses the abbreviation “subj”. Abbreviations are standardized so that, for example, “figure” is always used as “fig” (as in the element <fig-group>) and group is not abbreviated (as in the elements <fig-group>, <kwd-group>, and <fn-group>).
  • The typographic emphasis elements are spelled out in full, for example, <bold> (rather than “<b>”), <italic>, and <underline> instead of being differentiated using attribute values on an element such as <emphasis>. Superscript and subscript are not considered to be purely typographic, and each is a separate element: <sub> and <sup>.

The following table contains a growing list of abbreviations/names to be used in combined tag names (element type names), attribute names, and parameter entity names. (Words in the list below that are not abbreviated are displayed in italics.)

ORIGINAL WORD ABBREVIATION
acknowledgment ack
abstract abs
address addr
affiliation aff
alternate/alternative alt
article article
attribution attrib
author author
biography bio
chemical chem
communication communication
conference conf
contributor/contribution contrib
corresponding corresp
count count
cross x (no hyphen)
definition def
description desc
display disp
editor editor
end end
equal equal
external ext
figure fig
first f (no hyphen; <fpage>)
footnote fn
formula formula
government gov
graphic graphic
group/grouping group
heading/header head
identifier/ID id
inline inline
institution institution
item item
journal journal
keyword kwd
last l (no hyphen; <lpage>)
link link
list list
location loc
material material
metadata meta
number num
page page
paragraph p
prefix prefix
proceedings proceedings
publication pub
publisher publisher
quote quote
reference ref
related related
section sec
sequence/sequential seq
series series
size size
standard std
start start
statement statement
structure struct
subject subj
subscript sub (note: not inferior)
suffix suffix
superscript sup (note: not superior)
supplement supplement
supplementary supplementary
table table
title title
translated/translator trans
type type
underline underline
version version
volume vol
word word
wrapper wrap

File Naming Conventions

DTD — This Tag Library describes the components for the Book and Book Collection Tag Sets. These Tag Sets are described in an XML DTD. The base DTD modules (delivered as the files book.dtd and collection.dtd) call in all the other DTD fragment modules as external parameter entities. Each module specific to this Tag Set (therefore, not part of the Suite) takes the prefix “bookcustom-” or the prefix “book-”.

Each DTD and DTD fragment module has been assigned a unique formal public identifier (fpi). File names are never referenced directly in the comments in the DTD; the file is referred to by the name of the external parameter entity, which names the fpi and a system name for the file. The external parameter entity has been set to the initial delivery filename.

The Book and Book Collection Tag Sets, the individual DTD-fragment modules of the DTDs and the Suite have been given DOS/Windows 3-digit suffixes indicating their type:

*.dtd

A module that can be used as the top level of an XML hierarchy. Used for the Book and Book Collection Tag Set top levels, book.dtd and bookcollection.dtd, but also taken unchanged for public tag set modules that have been included in these Tag Sets such as the MathML Tag Set and the XHTML table model.

*.ent

A DTD fragment for incorporation into a full DTD. May contain element declarations, entity declarations, etc., for example, articlemeta.ent.

*.mod

A DTD fragment for incorporation into a full DTD. May contain element declarations, entity declarations, etc. This extension has the same meaning as *.ent and is only used to maintain the extension names dictated by the inclusion of PUBLIC tag set and/or schema fragments, for example, mathml2-qname-1.mod.

In version 3.0, for the first time, the module filenames reflect the version number, for example, a module whose name in previous versions was %list.ent; is now named list3.ent. The current plan is that future dot releases (3.1, 3.2, etc.) will not be reflected in the filename (not list3-1.ent, list3-2.ent, etc.) but will remain named with a single digit “3” (list3.ent), which will not change until the next major release, 4.0 will be list4.ent.

While the Tag Set cannot dictate graphic file names, the comments do suggest that best practice for naming graphic files in documents tagged according to this Suite would be to limit the names and path names to these characters: letters (both upper and lower case), numbers, underscore, hyphen, and period. All such names will be assumed to be case sensitive. DOS-style file extensions may be used.