Defining common terms

[merkys]

OPTiMaDe specification has a section for term definitions. Terms defined there are supposed to be used throughout the document to refer to the same concepts. In discussions with @CasperWA (e.g. in #104) the following issues were stressed:

1. Do we typeset the terms specifically throughout the document to distinguish them (as is done in legal papers by capitalization)? For example, there is a need to distinguish 'Property' (~ an attribute of a Resource object) from 'property' (~ generic word). We already use special style to distinguish 'MUST' from 'must'
2. Should we repeat term definitions, or try to avoid that?
   • Reason to repeat:
     1. reduces the need of jumping between sections of the specification document
   • Reasons not to repeat:
     1. bloat
     2. term definition changes force one to update the definition in many places
     3. menace of out-of-sync definitions

@CasperWA please add more arguments if you feel like.

[CasperWA]

Thanks for opening this issue @merkys.

I feel strongly for section 6. Entry List being a look-up "encyclopedia", where all fields and properties are definitively defined. Hence, I would want, when going through this section, not to have to scroll back and forth in the document to understand the requirements and description of said fields and properties.

The main issue has been involving the term ID and the field id, since this is a special case, where the value of the field id is the term ID. In this context, the question came up whether to define the requirements of what the value of the field id under section 6. Entry List or under the initial Term Definitions at the top of the document.