Glossary of Terms

[Sebastian Huber]

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.

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