2020-10-31: Some glossary terms are overloaded terms (have other meanings in this context)

[baileythegreen]

What is the appropriate way to address terms that have more than one meaning within the context represented by the scope of this glossary?

Element, for instance, is currently defined in relation to HTML/XML, but is also used to refer to the items inside of lists, sets, tuples, et cetera in different languages. Moreover, the definition for empty_vector currently reflects this second usage:

A vector that contains no elements. Empty vectors have a type such as logical or character, and are not the same as null.

What is the appropriate way to add multiple definitions? Can more than one def: > key be used per entry in the glossary?

This is not the only example where more than one meaning is possible, either.

[baileythegreen]

Is the model for the term graph what should be done?

 - slug: graph
  ref:
    - tree
  en:
    term: "graph"
    def: >
      1. A plot or a chart that displays data, or 2. a data structure in which
      [nodes](#node) are connected to one another by [edges](#edge).

[fmichonneau]

Thanks for bringing this up.

I think the format should be:

  en:
    term: "graph"
    def: >
      1. A plot or a chart that displays data.

      2. A data structure in which [nodes](#node) are connected to one
         another by [edges](#edge).

so we'll get a numbered list which would be more semantically correct and improve acceesibility.

[baileythegreen]

👍 I am happy to work on that (particularly as I have actually read through the entire glossary, which I imagine is rare). And I have a list I started of terms that are overloaded.

I would note though, that after going through the full thing, it seems like there is a different way some people have done this. Looking at the various feature_* entries, for example, you have:

- slug: feature_branch
  ref:
    - master_branch
  en:
    term: "feature branch"
    def: >
      A [branch](#branch) within a [Git](#git) [repository](#repository)
      containing [commits](#commit) dedicated to a specific feature, e.g., a
      [bug](#bug) fix or a new function. This branch can be merged into another branch.


- slug: feature_data
  en:
    term: "feature (in data)"
    def: >
      A variable or observable in a dataset.


- slug: feature_engineering
  en:
    term: "feature engineering"
    def: >
      The process of choosing the variables to be used as inputs to a [model](#model).
      Choosing good features often depends on [domain knowledge](#domain_knowledge).


- slug: feature_request
  en:
    term: "feature request"
    def: >
      A request to the maintainers or developers of a software program to add a
      specific functionality (a feature) to that program.


- slug: feature_software
  en:
    term: "feature (in software)"
    def: >
      Some aspect of software that was deliberately designed or built. A [bug](#bug)
      is an undesired feature.

I noticed this after creating this issue, but I think this method:

1. is confusing (because it is not immediately clear that these (some of these) define the term feature in different contexts (feature_branch, feature_engineering, and feature_request are actually terms, not a term + context));
2. makes it harder to know where internal links should point (particularly if two entries are somewhat-similar; and
3. does not reflect how actual dictionaries are written. The numbering method you propose is ore in-line with the standard.

I think the numbering system, with a way to specify context (see example image of different definitions of run, *noun*) is the way to go, but I imagine implementing this requires adding to the YAML parsing code used. (I haven't looked at this, yet, so don't even know what language it's written in.)