Glossary of Terms

[Sebastian Huber]

On 03/01/2020 18:16, Joel Sherrill wrote:
> 
> 
> On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom <gedare at rtems.org 
> <mailto:gedare at rtems.org>> wrote:
[...]
>     I prefer we use a centralized glossary/document to generate individual
>     glossaries (via scripting or improving Sphinx). This will be a lot
>     easier to maintain.
> 
> 
> The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a 
> singular artifacr across the project for consistencyt
> 
> http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary
> 
> That said, you need glossaries in documents and automating pulling 
> definitions and acronyms out automatically producing a glossary and 
> acronym list from the master AV-2 is desirable. No one wants to 
> reference a standalone glossary.
> 
> There can be issues if definitions change over time because the single 
> AV-2 can't deal with old and new. It gets confusing. I have seen a 
> project where the AV-2 included history like the Oxford English 
> Dictionary. It was dreadful.
> 
> That's a lot of background to say this isn't a RTEMS unique problem. A 
> central database of acronyms and definitions would be a good thing. If 
> grep is sufficient to find word use to trigger inclusion in a document 
> specific glossary, great.

Good, so my proposal is this:

1. I move c-user/glossary.rst to common/glossary.rst and include this 
file as is in c-user.

2. The glossary.rst for the other documents is generated from 
common/glossary.rst based on the :term: usage. This can start simple, 
e.g. only look at the *.rst files in the document directory (e.g. no 
recursive includes).

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.