foal 0.0.2

Merge and lookup acronyms from a directory tree of definitions.

FOAL

FOAL (From Organization Acronyms Lookup) is a tool to lookup acronyms from a set of YAML files.

Given multiple YAML files that define acronyms and abbreviations, merge the dictionaries in a contextually-sensitive order and lookup acronyms.

• What
• Why
• About the data structure
• Installation
  • From PyPI
  • From source
• Development

What

Define acronyms and abbreviations in context-aware files, then merge and lookup definitions with the ability to prioritize the context.

For example, given these files:

# technology.yaml

acronyms:
    cpu:
        shortform: CPU
        longform: Central Processing Unit

    eps:
        shortform: EPS
        longform: Encapsulated Postscript

# finance.yaml

acronyms:
    cogs:
        shortform: COGS
        longform: Cost of Goods Sold

    cpu:
        shortform: CPU
        longform: Cost per Unit

    eps:
        shortform: EPS
        longform: Earnings per Share

Get a dictionary that prefers the technology context:

$ foal -p technology.yaml
[WARNING] prefer context: ['technology.yaml']
---
acronyms:
    cogs:
        shortform: COGS
        longform: Cost of Goods Sold
        source: finance.yaml
    cpu:
        shortform: CPU
        longform: Central Processing Unit
        source: technology.yaml
    eps:
        shortform: EPS
        longform: Encapsulated Postscript
        source: technology.yaml

Get a dictionary that prefers the finance context:

$ foal -p finance.yaml
[WARNING] prefer context: ['finance.yaml']
---
acronyms:
    cogs:
        shortform: COGS
        longform: Cost of Goods Sold
        source: finance.yaml
    cpu:
        shortform: CPU
        longform: Cost per Unit
        source: finance.yaml
    eps:
        shortform: EPS
        longform: Earnings per Share
        source: finance.yaml

Lookup specific acronyms that prefer the technology context:

$ foal -p technology.yaml -a cpu
[WARNING] prefer context: ['technology.yaml']
---
acronyms:
    cpu:
        shortform: CPU
        longform: Cost per Unit
        source: technology.yaml

Why

It is sometimes necessary to lookup acronyms from a canonical list to use in documentation. The acronyms (or abbreviations) can then be used in automated documentation tools via something like pandoc-acronyms.

Acronyms form a vocabulary that people use within their own frame of reference. The general acceptance of acronyms dependends on multiple factors, such as political landscape, technical expertise, regional differences, context, and native tongue.

For example, most people around the world recognize the United States of America as the USA, the United Kingdom as the UK, and Germany as the BRD (Bundesrepublik Deutschland). English speakers are more likely to recognize BRD when it is used in the context of Olympic competition or an international news broadcast than when BRD appears randomly in a document.

Take another example, CPU.

• People in Information Technology (IT) immediately think of Central Processing Unit.

• People in finance are likely to think of Cost per Unit, especially when CPU is used in a financial context.

Taken out of context, abbreviations are difficult to interpret and can lead to misunderstanding in important documents.

About the data structure

• global.yaml within a directory tree is authoritative.
  Acronyms and abbreviations within global.yaml override acronyms from other files. This is a global context reserved for acronyms that should have universal meaning across an organization. Names of products, BUs, and teams are all good choices for global.yaml.

• This format does not dictate the hierarchy of acronyms from other files in the git repo. Only global.yaml has special priority. Tool developers and authors may choose to incorporate the other files in whatever priority makes sense in a given context.

• The definition of "context" for files within a directory tree is left up to individual contributors (other than global.yaml). Be inclusive. TimTowtdi.

A formal Kwalify schema for the format is in schema/acronyms.yaml.

Installation

From PyPI

pip install --user foal

From source

pip install --user .

Development

Run:

sdlc/bootstrap
sdlc/build
sdlc/test

Please see CONTRIBUTING.md and TESTING.md.