Glossary of Terms

Fri Jan 3 17:16:48 UTC 2020

On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom <gedare at rtems.org> wrote:

> On Fri, Jan 3, 2020 at 3:25 AM Sebastian Huber
> <sebastian.huber at embedded-brains.de> wrote:
> >
> > On 03/01/2020 10:42, Andrew.Butterfield at cs.tcd.ie wrote:
> > > Hello all, and Happy New Year!
> > >
> > >> On 3 Jan 2020, at 08:10, Sebastian Huber <
> sebastian.huber at embedded-brains.de> wrote:
> > >>
> > >>
> > >> 1. Should we use one shared glossary which is included in all
> documents?
> > >>
> > >> 2. Do we want to use document-specific glossaries and maintain
> copy-and-paste entries by hand?
> > >>
> > >> With option 1. the glossary may contain a lot of things which are
> unrelated to a specific document. However, if the Sphinx glossary support
> gets improved, this problem may vanish. With 2. we have a maintenance
> problem, e.g. keeping the copy and paste definitions in synchronization.
> > >>
> > >> What do you think?
> > >>
> > >
> > > Can we fuse 1+2 - keep a single (master) glossary file with added tags
> "glos1", "glos2" (or whatever)
> > > We then have a script that generates the different glossaries from
> that one master?
> > >
> > > I guess the issue is how easy it is to run that script from within the
> various document build workflows.
> >
> > Yes, we can also add our own scripts to automate this. The question is
> > if we want to develop special case solutions or try to fix it in the
> > upstream Sphinx project. Using our own scripts would be much probably
> > much easier, unless someone is familiar with the Sphinx internals.
> >
> > We could for example get the terms used in a document and based on this
> > generate a document-specific glossary from a master template, e.g.
> >
> > grep -r --include='*.rst' ':term:`[^`]*`' -o
> > eng/req-eng.rst::term:`GNAT`
> > eng/req-eng.rst::term:`EARS`
> > eng/req-eng.rst::term:`API`
> > eng/req-eng.rst::term:`ABI`
> > eng/req-eng.rst::term:`source code`
> > eng/req-eng.rst::term:`CCB`
> > eng/req-eng.rst::term:`ISVV`
> > eng/req-eng.rst::term:`ReqIF`
> > eng/req-eng.rst::term:`Doorstop`
> > eng/req-eng.rst::term:`Doorstop`
> > eng/req-eng.rst::term:`YAML`
> > c-user/key_concepts.rst::term:`thread`
> > c-user/symmetric_multiprocessing_services.rst::term:`TLS`
> > c-user/symmetric_multiprocessing_services.rst::term:`C11`
> > c-user/symmetric_multiprocessing_services.rst::term:`MCS`
> > c-user/symmetric_multiprocessing_services.rst::term:`FIFO`
> > c-user/symmetric_multiprocessing_services.rst::term:`NUMA`
> > c-user/symmetric_multiprocessing_services.rst::term:`TCB`
> > c-user/symmetric_multiprocessing_services.rst::term:`TTAS`
> > c-user/glossary.rst::term:`C11`
> > c-user/glossary.rst::term:`C11`
> > c-user/glossary.rst::term:`C++11`
> > user/start/prefixes.rst::term:`prefix`
> > user/installation/project-sandboxing.rst::term:`prefix`
> > user/overview/index.rst::term:`RTEMS`
> > user/overview/index.rst::term:`SMP`
> > user/overview/index.rst::term:`APIs <API>`
> > user/overview/index.rst::term:`POSIX`
> > user/overview/index.rst::term:`C11`
> > user/overview/index.rst::term:`C++11`
> > user/overview/index.rst::term:`GCC`
> > user/overview/index.rst::term:`EMB²`
> > user/overview/index.rst::term:`OpenMP`
> > user/overview/index.rst::term:`Futex`
> > user/overview/index.rst::term:`OpenMP`
> > user/overview/index.rst::term:`OMIP`
> > user/overview/index.rst::term:`MrsP`
> > user/overview/index.rst::term:`TLS`
> > user/overview/index.rst::term:`EDF`
> > user/overview/index.rst::term:`EDF`
> > user/overview/index.rst::term:`APA`
> > user/overview/index.rst::term:`IMFS`
> > user/overview/index.rst::term:`FAT`
> > user/overview/index.rst::term:`RFS`
> > user/overview/index.rst::term:`NFSv2`
> > user/overview/index.rst::term:`JFFS2`
> > user/overview/index.rst::term:`YAFFS2`
> > user/hardware/architectures.rst::term:`ABI`
> > eclipse/overview.rst::term:`RTEMS`
> >
> > An include if used policy is not followed by the Classic API Guide since
> > this feature was not available in the old texinfo framework as well.
> >
>
> 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.

--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
> _______________________________________________
> 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/20200103/43cdba80/attachment-0001.html>