Local copies of external definitions in Terminology

[gkellogg]

Currently, in the Terminology section, we include a number of local references to definitions from other specifications. For example, there is an entry for subject, which simply references the definition in RDF Concepts. Unlike terms defined within this specification, these cannot be referenced externally, and are not actually used for mentions of that term internally. For example the term mention set is defined in the specification, and is exported for reference from other specifications.

This issue is tracking if we want to continue this practice, or only list terms actually defined within the specification. The benefit of having them tracked in the Terminology section is for people reading the specification to have a single place to find common terminology used, whether or not it is actually defined within the spec. This practice is used, for example, in JSON-LD but is not actually that common elsewhere.

[iherman]

My personal preference would be (if it is not too much trouble) to separate the two editorially. Ie, list the terms defined by this specification (so that others may use the cross-referencing features, if necessary) and list, separately, the terms that are used by this spec and are defined formally by other specs. Something like

This specification also make use of the following terms, all defined by [RDF11-CONCEPTS]

• subject
• …

[TallTed]

I'm of mixed feeling on this separation.

A glossary is usually presented simply in alpha-sort order, so that every term is trivially located, with any needed info in its displayed editorial definition (such as whether its normative definition is within this document, or some external document).

Splitting the glossary into two sections, such that a human must refer to two locations to discover whether the term is defined/described here at all, does not feel user-friendly to me, for the usual purposes of such a glossary.

Perhaps it would be sufficient to apply some simple stylistic difference to the terms which are normatively defined here vs the terms which are normatively defined elsewher?

[gkellogg]

Note that the spec already has split sections. In Terminology the entries are all external (other than quad which should probably be in the N-Quads spec), although not alphabetically sorted, which is fairly easy to do ( data-sort="true").

There is also a section on Canonicalization Algorithm Terms, which are defined locally other than Unicode code point order; that definition could possibly be moved to Terminology, although it is really more of a point about the algorithms.

Note the handy auto-generated index if local and imported terms that ReSpec creates. It's largely for spec debugging, but it could remain long-term.

[iherman]

Note that the spec already has split sections. In Terminology the entries are all external (other than quad which should probably be in the N-Quads spec), although not alphabetically sorted, which is fairly easy to do ( data-sort="true").

I am not sure what you mean by 'split sections'. The terminology section, as of today, mixes the imported and local sections, and what I was proposing is to separate these in two sub-sections.

There is also a section on Canonicalization Algorithm Terms, which are defined locally other than Unicode code point order; that definition could possibly be moved to Terminology, although it is really more of a point about the algorithms.

Well, the whole document is about the algorithms :-) I think separating the local terms into its own subsection and merge it with the algorithm terms is a good idea.

[gkellogg]

Well, the whole document is about the algorithms :-) I think separating the local terms into its own subsection and merge it with the algorithm terms is a good idea.

Indeed. Modulo some local terms that should move to other specs (e.g., nquads and [quad](https://w3c.github.io/rdf-canon/spec/#dfn-quad, although nquads should probably be a variable, and not a definition, or at least aa locally-scoped definition), there's no reason that the Canonicalization Algorithm Terms can't be a sub-section within Terminology.

[gkellogg]

This was completed when we added text from RDF 1.2 N-Quads.