Glossary of Terms

[Gedare Bloom]

On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> 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).
>
Later when a new term is added for something not in c-user, then the
c-user should be updated to also derive its glossary with :term:?
(Before that, we might need to double check if the current glossary
terms are all defined/used in c-user with :term:.)

> --
> 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.