Glossary of Terms

[Gedare Bloom]

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.

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