Skip to content

Add abbreviated terms, symbols and mnemonics to Clause 3 (#435) - #438

Merged
SteveLLamb merged 8 commits into
mainfrom
issues/0435-abbr-mnumonics
Sep 22, 2026
Merged

SteveLLamb merged 8 commits into
mainfrom
issues/0435-abbr-mnumonics

Conversation

@SteveLLamb

Copy link
Copy Markdown
Member

Clause 3 can now also list abbreviated terms, symbols and mnemonics, per
ISO Directives Part 2 Clause 17. Authors add up to three new optional
lists after terms-int-defs, in this order:

dl#terms-abbr abbreviated terms
dl#terms-symbols symbols
dl#terms-mnemonics mnemonics

The source stays flat. When any of these lists is present, rendering:

  • splits Clause 3 into subclauses: 3.1 Terms and definitions, then one
    subclause per list present (Abbreviated terms, Symbols, Mnemonics)
  • gives Clause 3 a composite title in ISO style, without a serial comma,
    e.g. "Terms, definitions and abbreviated terms"
  • numbers terms within 3.1 (3.1.1, ...); the dfn-* anchor ids do not
    change
  • adds a lead-in sentence to each subclause; the Mnemonics default is
    "The following data types are used for data specifications:" and the
    data-intro attribute replaces it
  • shows each list in two columns, with terms not numbered and not bold

Documents without the new lists render exactly as before.

Validation:

  • element order: ext-defs, int-defs, abbr, symbols, mnemonics
  • each entry is exactly one dt followed by one dd; no dfn, no duplicates
  • abbreviations and mnemonics must be in alphabetical order, ignoring
    case
  • symbols must follow the ISO 17.5 order (A, a, B, b; no index, then
    letter indices, then numeric indices; Latin, then Greek, then other);
    data-order="technical" skips this check for the symbols list only
  • every abbreviated term and symbol must be used in the text
  • data-intro must not be empty

Also resolves #8: an without a title gets its expansion from
terms-abbr, or from another with the same text written
inline in the document.

Includes 21 new validation fixtures and updates to doc/main.html.

Closes #435
Closes #8

Add optional dl#terms-abbr, dl#terms-symbols and dl#terms-mnemonics
lists. When any is present, Clause 3 is split into subclauses under
an ISO composite title and terms are numbered 3.1.n. Validation checks
element and entry order (ISO 17.5 order for symbols) and that entries
are used in the text. An <abbr> without a title now gets its expansion
from the list.

Closes #435
Closes #8
@github-actions

Copy link
Copy Markdown

An <a> without an href now resolves in this order:
1. a dfn, either in terms-int-defs or inline via data-lt (as before)
2. the matching entry in terms-abbr, terms-symbols or terms-mnemonics

Each list entry gets a generated id (abbr-, symbol-, mnemonic-).
Matching ignores case and accepts a trailing "s". When the link text
is a known abbreviation, the link also shows its expansion on hover.

Documents the resolution order in doc/main.html and adds the
terms-lists-links-valid fixture.

Refs #8
expansion must then match a synonym of the term, and the entry links
back to the term.
References now match common English plurals of the last word of a
term and of each data-lt form: +s, +es (s, x, z, ch, sh), y -> ies,
ex/ix -> ices, is -> es, um/on -> a. Generated forms never cause
duplicate definitions and yield to explicit terms. Irregular plurals
use data-lt. The same rules apply to abbreviated terms, symbols and
mnemonics, and the abbreviation usage check accepts plurals.

Closes #415
Most end tags are optional in HTML, so a broken end tag such as
"Identifier/dd>" parses as text and passes HTML validation, ending
up in the definition or abbreviation expansion. Report such
fragments anywhere in the body text, except inside pre, code, samp
and kbd.

Adds the malformed-end-tag-abbr-invalid and
malformed-end-tag-intdefs-invalid fixtures.
@SteveLLamb
SteveLLamb merged commit 13665e9 into main Sep 22, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for Abbreviations and Mnemonics Add support for abbr

2 participants