Closed johndgiese closed 5 years ago
johndgiese
commented
5 years ago @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
commented
5 years ago 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
commented
5 years ago Input dictionary.yml:
definitions:
Input spec.md:
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.
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
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.
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.
It would be nice to have a custom jinja tag for keeping up with definitions and abbreviations.
In particular, we typically use the same definitions in across different documents, but only want to include the relevant definitions in the documents where they are used.
To avoid duplication across different templates, it would be nice if we:
data/definitions.yml) and abbreviations (data/abbreviations.yml).