Divergloss, short of "Diversity Glossary", is an instance of XML for handling glossary data -- succinct descriptions connected with terms which name certain concepts. A necessary question to answer up front is, why yet another XML format for glossaries? For example, there is the TBX format ("TermBase eXchange") by LISA, used widely in localization industry and submitted for adoption as ISO standard. Another option is the glossary document type of the Docbook format. To answer this, we must consider the goals behind Divergloss:

Conversely, Divergloss does not place much importance into the following:

In essence, Divergloss favors simplicity, ease of getting involved both in terms of cognitive effort and needed tools, at the expense of generality and formal correctness as viewed from pure data-encoding standpoint. This is in contrast with the aforementioned TBX, which is intended as end-all of glossary formats, and in practice mostly handled through features of dedicated glossary or CAT (Computer-Aided Translation) tools. Docbook glossary format, on the other hand, while offering similar simplicity, is too lightweight to cover all envisaged uses of Divergloss.

It is, however, possible that Divergloss could be made an instance of TBX, i.e. one of its XCS ("eXtensible Constraint Specification") customizations. This would facilitate the conversion of Divergloss into TBX glossaries, for use by existing CAT tools. Some sort of conversion to TBX is, of course, possible in any case, but no effort to that end has been undertaken as of yet.

Divergloss strives for language neutrality. There is no limitation on how many languages, and precisely in which fashion, may a single glossary document support. This need is highly dependent on locale and field of use: a glossary of pre-Columbian civilizations for American users may get away fully monolingual, a glossary of oceanic freight for German users may state English terms too, while a glossary of astronomy for Tunisian users may need to be fully Arabic-French bilingual (both descriptions and terms).

Within each language, Divergloss supports another level of diversity: in different environments, e.g. within two large companies doing similar business, same concepts may be named differently. An outsider may thus consider them synonymous, but a user within one of those environments should be primarily presented with the term native to it. "Fully" synonymous terms, in this sense, will have both the language and the environment same.

Aside from language and environment, each description and term can be equipped with a myriad of supplementary data. For example, the description may have an additional comment on source of the text, while a base term may come with few declinations which would be hard for user to guess by general rules of the language.

Bearing previous passages in mind, the entries in Divergloss documents are organized by concepts, not apriori linked to any of the terms. Instead, each concept is referenced by a unique key, and contains any number of descriptions and terms. Here is the simplest example of glossary with two terms in it:

<?xml version="1.0" encoding="UTF-8"?>
<glossary id="cosmogloss" lang="en">

  <metadata>
    <title>A Short Cosmic Glossary</title>
  </metadata>

  <keydefs>
    <languages>
      <language id="en">
        <name>English</name>
        <shortname>En.</shortname>
      </language>
    </languages>
  </keydefs>

  <concepts>

    <concept id="blackhole">
      <desc>
        The leftover core of a super massive star after a supernova,
        that exerts a tremendous gravitational pull.</desc>
      <term>black hole</term>
    </concept>

    <concept id="quasar">
      <desc>
        A distant energy source which gives off vast amounts of
        radiation, including radio waves and X-rays.</desc>
      <term>quasar</term>
    </concept>

  </concepts>

</glossary>

The glossary top node states the unique glossary identifier, by the id attribute. The default language used in the glossary is given by lang attribute, which applies to all text in the document where not locally overridden. The metadata node contains general info about the glossary, like title, description, etc. All keys in a Divergloss glossary, such as the language value to the lang attributes, are defined by the the keydefs node.

Glossary entries are grouped under the concepts node. Each concept node has an id attribute, a key which uniquely defines the concept. Each concept can contain any number of descriptions and terms, defined by desc and term nodes; each may override the default language using the lang attribute.

Let us now add terms in few other languages:

<concept id="blackhole">
  <desc>
    The leftover core of a super massive star after a supernova,
    that exerts a tremendous gravitational pull.</desc>
  <term>black hole</term>
  <term lang="fr">trou noir</term>
  <term lang="de">Schwarzes Loch</term>
</concept>

The term without a lang attribute is in English, which was stated as the default language, whereas the two other terms override the language to French and German. In a fully multilingual case, description nodes too could be stated in several languages in the same way.

How about different environments? Here's a tentative example from a computer glossary:

<concept id="directory">
  <desc>
    An entity in a file system which contains a group of files
    and other directories.</desc>
  <term>directory</term>
  <term env="mac">folder</term>
  <term env="amiga">drawer</term>
</concept>

Here, the first term, as before, defines no environment. Other two terms define an environment by use of env attribute. The value of env attribute is not a text that may be shown to the user, but an environment key. It must be defined elsewhere in the document, together with proper environment name (see the environments node). Same as with language, it depends on the client how the environment information will be used when presenting concepts to the user. For example, if the user is reading the glossary on an Amiga, the application may show "drawer" as primary term.

In the last example, the description text itself mentioned the word "directories". If the user is using an Amiga, shouldn't he see "drawers" instead? When this occurs in a multienvironment glossary, the descriptions too can be specialized by environment. Furthermore, the terms should be properly crossreferenced, so that the client may allow the user to click on the term in description and go to corresponding concept. Putting it all together, we get:

<concept id="directory">
  <desc>
    An entity in a <ref c="filesystem">file system</r> which contains
    a group of <ref c="file">files</r> and other directories.</desc>
  <desc env="mac">
    An entity in a <ref c="filesystem">file system</r> which contains
    a group of <ref c="file">files</r> and other folders.</desc>
  <desc env="amiga">
    An entity in a <ref c="filesystem">file system</r> which contains
    a group of <ref c="file">files</r> and other drawers.</desc>
  <term>directory</term>
  <term env="mac">folder</term>
  <term env="amiga">drawer</term>
</concept>

The reference node tag ref points to a concept key by its c attribute. If duplication of descriptions due to different terms by environment is to be frequently expected, alternatively the terse embedded selection can be used.

Descriptions and terms may also credit the person who added them into the glossary. This person is an editor of the glossary, not necessarily the one who wrote the description, or coined the term. The editor's credit is assigned using the by attribute, for example:

<desc by="hal">
  An instruction by a superior factor which, if improperly formulated,
  can cause a sentient being to undertake unethical actions.</desc>
<term by="hal">order</term>

where "hal" is the person key, possibly made out of the person's initials. These keys and corresponding editors' real names and contact data are defined within the editors node.

A Divergloss document is divided into the following top-level sections:

<glossary id="glosskey" lang="xx" env="yyyy">
  <metadata>
    ...
  </metadata>

  <keydefs>
    ...
  </keydefs>

  <concepts>
    ...
  </concepts>
</glossary>

A particular combination of values to id, lang, and env attributes, should uniquely determine the glossary within the ecosystem of other published Divergloss glossaries. The lang and env attributes are not mandatory; if provided, their values apply to all subnodes where meaningfull and not locally overridden.

The metadata node provides information about the glossary in general. These include the following child nodes:

All child nodes except the title are optional. The title and desc can have the attributes of language (lang) and environment (env), and can be repeated for unique combinations of those. The values of these attributes are keys defined by the keydefs node.

The main body of the glossary, concepts and terms naming them, is given by the concepts node. This node is mandatory -- not much point in a glossary without a single concept.

Within metadata and concepts, many keyword-valued attributes may be used, which denote global data in the glossary: languages, environments, editors, topics, etc. These keywords are defined by the the keydefs node, where also the user-presentable info on them is stated. This node is not mandatory, but will be needed for all but the simplest glossaries.

keydefs and concepts nodes can actually appear more than once, each instance containing the data as described previously. In this way the document can be chunked into files, such that each file can still remain a valid XML. E.g. files containing groups of concepts, categorized in some way, can all start with their own concepts root element.

Concept nodes reside within the concepts node of the glossary:

<glossary id="glosskey" lang="en">
  ...
  <concepts>

    <concept id="ckey1">
      ...
    </concept>

    <concept id="ckey2">
      ...
    </concept>

    ...

  </concepts>
  ...
</glossary>

The ordering of concepts is not important, and each concept key, given by id attribute, must be unique. The keys are best chosen mnemonically, for easier crossreferencing.

The concept node may have the following optional attributes:

An example of a concept node equipped with several attributes:

<concept id="saturnv"
         topic="apollo spacerace" level="newbie" related="n1 proton">
  <desc>
    A multistage liquid-fuel expendable rocket used by NASA's Apollo
    and Skylab programs. Popularly known as the Moon Rocket.</desc>
  <term>Saturn V</term>
</concept>

All children nodes of the concept may have the attributes lang, env, and by. The client should use these attributes to decide, possibly based on the execution environment, how and which information to present to the user.

Furthermore, description and term nodes may have the src attribute, which unlike the by attribute, defines the source of description or term: another glossary, publication in the field, etc. The source value is a key, with the source data behind it defined by the sources node.

There can be one or several description nodes, or even none. When two descriptions have the same values of lang and env attributes, they are to be considered as different takes at same explanation. Similarly, the concept may be named by one or several terms (with term nodes being detailed in their own section); but there may also be no terms, for concepts which are as of yet unnamed. The following is a valid concept definition:

<concept id="alexq" topic="arch">
  <desc>The quality without a name.</desc>
</concept>

Other than descriptions and terms, concept node can have the following children nodes:

Each concept may be named by several terms, given by term child node of concept node. In the simplest case of a traditional glossary, these terms would be synonymous. In a Divergloss glossary, clients should consider as synonymous only those terms with equal language and environment attributes.

All attributes to the term node are optional, and are as follows:

Terms may sometimes need additional information, in which case the extended eterm node is used. It has the same attributes as the ordinary term node, but branches into child nodes, where the nominal form of the term is stated by the nom child node:

<eterm>
  <nom>phenomenon</nom>
  ...
</eterm>

Other, optional child nodes of the extended term include:

An example of a term with some of the extended data:

<eterm>
  <nom>phenomenon</nom>
  <decl gr="plu">phenomena</decl>
  <stem>phenomen</stem>
  <origin src="dictcom">
    From Greek "phainómenon", over Late Latin "phaenomenon",
    to appear.</origin>
</eterm>

All the various keys used in concepts and terms are collected and defined within this node, by sections:

<keydefs>
  <languages>
    ...
  </languages>
  <environments>
    ...
  </environments>
  ...
</keydefs>

The keys themselves are always defined by the id attribute of the respective key definition node.

Each node that has a text value, within any of the key definition sections, may be equipped with lang and env attributes, and repeated for different combinations of them. Clients should use this info to select the text to present to the user as a description behind a particular key.

The key definition sections are as follows:

Some nodes may contain larger bodies of text, where additional markup is advantageous (e.g. referencing). Such nodes are desc, comment, origin, etc. The following markup can be applied within text contents of such nodes:

Although glossary texts should be kept short and to the point, sometimes the text content could still be long enough to warrant splitting into several paragraphs, and other higher level groupings. All nodes which could reasonably benefit from such structure have an l* variant, which contain structured text content:

<ldesc>
  <para>
    A huge cloud which is thought to surround our solar system and
    reach over halfway to the nearest star.</para>
  <para>
    Comets originate in the Oort cloud.</para>
</ldesc>

Such nodes are: ldesc, lcomment, and lorigin. These can be used everywhere instead of their simpler counterparts. For the moment, the only structuring element are paragraphs (the para nodes), but more may be introduced in the future.

Sometimes a lot of text may need duplicating due to a single phrase in it differing across environments, typically in description nodes -- see an earlier example. To prevent this duplication, clients will support special embedded text selection by environment. Using embedded selection, the mentioned example can be rewritten as:

<concept id="directory">
  <desc>
    An entity in a <ref c="filesystem">file system</r> which
    contains a group of <ref c="file">files</r> and other
    ~directories|mac:folders|amiga:drawers~.</desc>
  <term>directory</term>
  <term env="mac">folder</term>
  <term env="amiga">drawer</term>
</concept>

i.e. the embedded selector is of the form ~env1:phrase1|env2:phrase2|...~, where if one of the environment keys is empty or omitted (as in the example), that phrase inherits the surrounding text's environment. Instead of a single environment key, a whitespace separated list can also be given. The tilde character (~) cannot be a part of ordinary text by itself, but it can be escaped by doubling it (~~). This kind of special-form selection is unusual by XML standards, but has been introduced due to being more human-readable and editable in the running text than e.g. a selection node with subnodes per environment: <select><for env="env1">phrase1</for><for env="env2">phrase2</for>...</select>.

$ git clone https://github.com/caslav-ilic/divergloss.git

$ cd divergloss/
$ git pull

$ dgproc.py gloss.xml

$ dgproc.py html-bidict gloss.xml -solang:en -stlang:de -sfile:gloss.html

$ dgproc.py tbx gloss.xml -sfile:gloss.tbx