Glossary of Terms

[Sebastian Huber]

On 07/01/2020 17:21, Gedare Bloom wrote:
> 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:.)

The :term: is sparely used in c-user currently. It would require a bit 
of manual work to pull in all terms via this text role.

After one night, I don't like my proposal any more. I think it would be 
better to move the glossary terms to the RTEMS specification (e.g. in 
the RTEMS sources "spec/glossary/*.yml") and generate the glossary.rst 
for the documents with a script.  This gives us more flexibility and 
removes the need for the special parser code, see:

https://lists.rtems.org/pipermail/devel/2020-January/056811.html

The AV-2 mentioned by Joel wants the glossary terms in categories. We 
could add categories to the glossary specification items. This would be 
difficult with a master glossary in reST.

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