Definitions about rdm

[johndgiese]

@orwonthe I pushed this issue into v1, since it would be nice to use it in the docs. Please write out how you plan on implementing it in this issue first, before implementing it, so we can discuss.

[orwonthe]

It will be implemented as a AutoDefinition object that is created if auto_definition is in the list of filters in post_filters attribute of system.yml

The AutoDefinition object will have two sequential processes.

The first process starts with a dictionary of pre-defined terms.
It then scans the document to see which pre-defined terms are used in the document.
A dictionary is produced which contains only the terms actually used.

The second process locates a specially marked definition section.
It scans that section for other already existing definitions (Call them in-line definitions).
Pre-defined definitions are merged alphabetically with the in-line definitions.

Initially, two different formats will be available.
A plain text format simply inserts text with the defined word or phrase marked in bold:

A foobot is an automated process that implements foo.

A tabular format uses the defined word as a prefix to a shortened definition.

foobot: Automated process that implements foo.

The begin marker for the start of definitions should specify a format.
The dictionary of predefined terms should provide both formats.
In-line definitions should separate individual definitions with blank lines and mark the defined word,
and only the defined word, as bold text.
The word or phrase can appear more than once in the definition but no other words should be bold.

In-line definitions that are not in alphabetical order will raise an exception.
Missing or unmatched definition section end markers will raise an exception.
In-line definitions with no bold keyword or multiple conflicting keywords will raise exceptions.

If the begin marker provides a list of formats, the process will search the pre-defined dictionary will with each format until a definition is found.

Predefined definitions are not used if the same term exists in-line.

[orwonthe]

Input dictionary.yml:
definitions:

• keyword: 'apple'
  plain: An apple is a type of quasi-spherical red or green fruit.
  formatted: apple: Type of fruit.
• keyword: 'apple computer'
  plain: An apple compputer is a popular brand of computer.
  formatted: apple computer: Brand of computer.
• keyword: 'banana'
  plain: A banana is a type of yellow fruit.
  formatted: banana: Type of fruit.
• keyword: 'pit'
  plain: A pit is a hole in the ground.
  formatted: pit: Hole in ground.
• keyword: 'technician'
  plain: A technician is any trained person participating in a procedure.
  formatted: technician: Trained person participating in a procedure.

Input spec.md:

Eyelashectomy Patient Preparation

Prior to the procedure the patient should be offered an apple or a cherry.
Patient should NOT be offered a banana as the peel may be slippery.
To avoid choking hazards technician should ensure cherry has no pit.

Definitions

RDM_DEFINITIONS_BEGIN format=plain exclude=technician

A cherry is a small red fruit.

A pit is the stone or seed inside of a cherry.

RDM_DEFINITIONS_END

Output release/spec.md

Eyelashectomy Patient Preparation

Prior to the procedure the patient should be offered an apple or a cherry.
Patient should NOT be offered a banana as the peel may be slippery.
To avoid choking hazards technician should ensure cherry has no pit.

Definitions

An apple is a type of quasi-spherical red or green fruit.

A banana is a type of yellow fruit.

A cherry is a small red fruit.

A pit is the stone or seed inside of a cherry.