Glossary of Terms

[Joel Sherrill]

On Wed, Jan 8, 2020 at 12:36 PM Gedare Bloom <gedare at rtems.org> wrote:

> On Tue, Jan 7, 2020 at 11:34 PM Sebastian Huber
> <sebastian.huber at embedded-brains.de> wrote:
> >
> >
> >
> > 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.
> >
> Understood, although adding those :term: from the existing glossary
> seems like a good job for grep and sed to me.
>
> > 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.
> >
> Yes, putting the glossary terms in a parseable structure like YAML
> sounds sensible.
>

+1

I know I have said this to anyone who will listen in person but I think the
questions we are answering and infrastructure being built up to address
pre-qualification and high integrity development processes will be of
great value outside the RTEMS Project. As banal as glossary management
sounds, managing as recommended by DoDAF and doing it with open
source tools is a BIG deal. Similar with requirements and traceability.

Let's keep solving big problems in simple ways with open source tools. :)

--joel


>
> > --
> > 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.
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200108/c52bb868/attachment-0001.html>