# CTAO Computing glossary

This is the source for the CTAO Computing Department Glossary, used in documents as well as in a stand-alone release  under the document number: **CTA-LIS-COM-000000-0001**.

Official releases can be found on the [Computing-info Redmine DMS](https://redmine.cta-observatory.org/projects/computing-info/dmsf?folder_id=1947) and in the [CTAO Document Repository](https://ctaoobservatory.sharepoint.com/:b:/r/sites/CTAODocumentRepository/Shared%20Documents/CTA-LIS-COM-000000-0001/CTA-LIS-COM-000000-0001_1a_Computing_Glossary.pdf?csf=1&web=1&e=1rhfvR)


### :book: Automatically Generated Drafts:
 [![pipeline status](https://gitlab.cta-observatory.org/cta-computing/documentation/cta-computing-glossary/badges/main/pipeline.svg)](https://gitlab.cta-observatory.org/cta-computing/documentation/cta-computing-glossary/-/commits/main)

  Download document drafts built from this repository:
 * [CTA-LIS-COM-000000-0001_Computing_Glossary_DRAFT.pdf](https://gitlab.cta-observatory.org/cta-computing/documentation/cta-computing-glossary/-/jobs/artifacts/main/file/FullGlossary/build/CTA-LIS-COM-000000-0001_Computing_Glossary_DRAFT.pdf?job=build-docs)
 * [cta-computing-glossary.xlsx](https://gitlab.cta-observatory.org/cta-computing/documentation/cta-computing-glossary/-/jobs/artifacts/main/file/FullGlossary/build/ctao-computing-glossary.xlsx?job=build-docs) (Excel version of the glossary)
 * [example.pdf](https://gitlab.cta-observatory.org/cta-computing/documentation/cta-computing-glossary/-/jobs/artifacts/main/file/ExampleLaTeX/build/example.pdf?job=build-docs)

-----

## About this repository

This repo contains a glossary of terms for CTAO Computing in YAML format, with a converter
to dump them to LaTeX glossary format.

- [glossary-general.yaml](glossary-general.yaml):  terms from the CTAO glossary / science operations
- [glossary-computing.yaml](glossary-computing.yaml):  terms specific to the CTAO Computing department
- [glossary-dpps.yaml](glossary-dpps.yaml): terms specific to the DPPS 
- [glossary-suss.yaml](glossary-suss.yaml): terms specific to the SUSS 
- [glossary-simulations.yaml](glossary-simulations.yaml): terms related to simulations 
- [glossary-from-jama.yaml](glossary-from-jama.yaml): contains the old (outdated) JAMA glossary, converted to YAML format for reference
- [glossary-calibpipe.yaml](glossary-calibpipe.yaml): calibration-related terminology

In LaTeX, for terms with abbreviations, the full term will be used the first time
the entry is used, and the abbreviation will be used subsequently, for example:

    The \gls{dpps} processes the data, and each data center will have an instance of
    a \gls{dpps} node.

Will appear in the text as:

    The Data Processing and Preservation System (DPPS) processes the data and each
    data center will have an instance of a DPPS node.

## Glossary format

The glossary is dictionary of keys (identifiers used to reference an entry, but
not part of the text) and attributes for each entry. The file [](schema.yaml)
defines the format in JSONSchema format. It is used for validation. The format
is:

```yaml
KEY:  # replace KEY with a unique key to use in latex \gls{KEY}
  term:         # the long form of the entry
  abbreviation: # optional, the abbreviation or acronym. Will appear in the Acronyms list
  definition:   # text defining the term
  note:         # optional, explanatory note to be included in definition
  tags:         # optional, list of tags in [tag1, tag2] form
  source:       # optional, name of the source of this term
  source-url:   # optional, URL of source if available
  symbol:       # optional, the mathematical symbol to use for this term
  plural:       # optional, the plural form of the word, if not standard s/es
  see-also:     # optional, list of cross-referenced KEYs [KEY1, KEY2]
  comments:     # optional, list of  additional info not used in glossary
     - Comment 1
     - Comment 2
```

**KEYs**: the key should be a short and easy to type identifier. If the entry has an abbreviation, it is recommended to use the abbreviation as the key . It does not appaer anywhere in the text, but is used to refer to the entry in LaTeX, e.g. using the `\gls{KEY}` or `\glspl{KEY}` (plural) macros. 

**TAGS**:  tags are currently unused in the output, but can be useful in the futuer to group terminology.

A special section called `__common__` can be used to define default values for
all entries in a glossary file. It will then add the common attributes to all
entries in the glossary if and only if they do not exist already (so entry tags
set explicitly will not be overwritten by the common version).


## Usage:

environment required to run these scripts:

``` sh
conda create -c conda-forge -n cta-glossary python=3.11 ruamel.yaml jsonschema
conda activate cta-glossary
```


### Using the glossary in LaTeX

The `glossary-to-latex.py` program can be used to convert the glossary into LaTeX format. See the `LaTeXExample/` directory for an example Makefile and document using its output.

See also the [computing-latex-class](https://gitlab.cta-observatory.org/cta-computing/documentation/computing-latex-class) repository for detailed usage and a standard document template.



### Checking for potential glossary terms

The `suggest-glossary-items.py` script can be used to check a LaTeX file for potential terms from a glossary YAML file.  It will show both terms you have already used, and suggest ones that could be missing (it is not 100% accurate, but still helpful).

    ./suggest-glossary-terms.py --glossary "glossary-*.yaml" my-latex-file.tex
    
        
### Excel Output

To get a version of this glossary in Excel table format, use the `--write-excel
glossary.xlsx` option. This requires having pandas and at an Excel output
backend installed in the environment (either `xlsxwriter` or `openpyxl`)
    
   
    

### Editing glossaries in _emacs_:

the following snippet can be used with the `yasnippet` package to expand `glos[tab]` into a glossary entry in `yaml-mode`

```conf
# -*- mode: snippet -*-
# name: Glossary Entry
# uuid: 91940cee-9dab-11ee-bdff-d30aa6822f0f
# key: glos
# condition: t
# group: yaml-mode
# expand-env: ((yas-indent-line 'fixed))
# --

${1:key}:
  term: $2
  abbreviation: $3
  definition: $4
  tags: [$5]
  source: ctao-computing
  source-url:
  symbol: null
  plural: null
  see-also: []
```
