<div dir="auto"><div><br><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom <<a href="mailto:gedare@rtems.org">gedare@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Fri, Jan 3, 2020 at 3:25 AM Sebastian Huber<br>
<<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank" rel="noreferrer">sebastian.huber@embedded-brains.de</a>> wrote:<br>
><br>
> On 03/01/2020 10:42, <a href="mailto:Andrew.Butterfield@cs.tcd.ie" target="_blank" rel="noreferrer">Andrew.Butterfield@cs.tcd.ie</a> wrote:<br>
> > Hello all, and Happy New Year!<br>
> ><br>
> >> On 3 Jan 2020, at 08:10, Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank" rel="noreferrer">sebastian.huber@embedded-brains.de</a>> wrote:<br>
> >><br>
> >><br>
> >> 1. Should we use one shared glossary which is included in all documents?<br>
> >><br>
> >> 2. Do we want to use document-specific glossaries and maintain copy-and-paste entries by hand?<br>
> >><br>
> >> 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.<br>
> >><br>
> >> What do you think?<br>
> >><br>
> ><br>
> > Can we fuse 1+2 - keep a single (master) glossary file with added tags "glos1", "glos2" (or whatever)<br>
> > We then have a script that generates the different glossaries from that one master?<br>
> ><br>
> > I guess the issue is how easy it is to run that script from within the various document build workflows.<br>
><br>
> Yes, we can also add our own scripts to automate this. The question is<br>
> if we want to develop special case solutions or try to fix it in the<br>
> upstream Sphinx project. Using our own scripts would be much probably<br>
> much easier, unless someone is familiar with the Sphinx internals.<br>
><br>
> We could for example get the terms used in a document and based on this<br>
> generate a document-specific glossary from a master template, e.g.<br>
><br>
> grep -r --include='*.rst' ':term:`[^`]*`' -o<br>
> eng/req-eng.rst::term:`GNAT`<br>
> eng/req-eng.rst::term:`EARS`<br>
> eng/req-eng.rst::term:`API`<br>
> eng/req-eng.rst::term:`ABI`<br>
> eng/req-eng.rst::term:`source code`<br>
> eng/req-eng.rst::term:`CCB`<br>
> eng/req-eng.rst::term:`ISVV`<br>
> eng/req-eng.rst::term:`ReqIF`<br>
> eng/req-eng.rst::term:`Doorstop`<br>
> eng/req-eng.rst::term:`Doorstop`<br>
> eng/req-eng.rst::term:`YAML`<br>
> c-user/key_concepts.rst::term:`thread`<br>
> c-user/symmetric_multiprocessing_services.rst::term:`TLS`<br>
> c-user/symmetric_multiprocessing_services.rst::term:`C11`<br>
> c-user/symmetric_multiprocessing_services.rst::term:`MCS`<br>
> c-user/symmetric_multiprocessing_services.rst::term:`FIFO`<br>
> c-user/symmetric_multiprocessing_services.rst::term:`NUMA`<br>
> c-user/symmetric_multiprocessing_services.rst::term:`TCB`<br>
> c-user/symmetric_multiprocessing_services.rst::term:`TTAS`<br>
> c-user/glossary.rst::term:`C11`<br>
> c-user/glossary.rst::term:`C11`<br>
> c-user/glossary.rst::term:`C++11`<br>
> user/start/prefixes.rst::term:`prefix`<br>
> user/installation/project-sandboxing.rst::term:`prefix`<br>
> user/overview/index.rst::term:`RTEMS`<br>
> user/overview/index.rst::term:`SMP`<br>
> user/overview/index.rst::term:`APIs <API>`<br>
> user/overview/index.rst::term:`POSIX`<br>
> user/overview/index.rst::term:`C11`<br>
> user/overview/index.rst::term:`C++11`<br>
> user/overview/index.rst::term:`GCC`<br>
> user/overview/index.rst::term:`EMB²`<br>
> user/overview/index.rst::term:`OpenMP`<br>
> user/overview/index.rst::term:`Futex`<br>
> user/overview/index.rst::term:`OpenMP`<br>
> user/overview/index.rst::term:`OMIP`<br>
> user/overview/index.rst::term:`MrsP`<br>
> user/overview/index.rst::term:`TLS`<br>
> user/overview/index.rst::term:`EDF`<br>
> user/overview/index.rst::term:`EDF`<br>
> user/overview/index.rst::term:`APA`<br>
> user/overview/index.rst::term:`IMFS`<br>
> user/overview/index.rst::term:`FAT`<br>
> user/overview/index.rst::term:`RFS`<br>
> user/overview/index.rst::term:`NFSv2`<br>
> user/overview/index.rst::term:`JFFS2`<br>
> user/overview/index.rst::term:`YAFFS2`<br>
> user/hardware/architectures.rst::term:`ABI`<br>
> eclipse/overview.rst::term:`RTEMS`<br>
><br>
> An include if used policy is not followed by the Classic API Guide since<br>
> this feature was not available in the old texinfo framework as well.<br>
><br>
<br>
I prefer we use a centralized glossary/document to generate individual<br>
glossaries (via scripting or improving Sphinx). This will be a lot<br>
easier to maintain.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a singular artifacr across the project for consistencyt</div><div dir="auto"><br></div><div dir="auto"><a href="http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary">http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary</a><br></div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">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. </div><div dir="auto"><br></div><div dir="auto">--joel</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
> --<br>
> Sebastian Huber, embedded brains GmbH<br>
><br>
> Address : Dornierstr. 4, D-82178 Puchheim, Germany<br>
> Phone   : +49 89 189 47 41-16<br>
> Fax     : +49 89 189 47 41-09<br>
> E-Mail  : <a href="mailto:sebastian.huber@embedded-brains.de" target="_blank" rel="noreferrer">sebastian.huber@embedded-brains.de</a><br>
> PGP     : Public key available on request.<br>
><br>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.<br>
> _______________________________________________<br>
> devel mailing list<br>
> <a href="mailto:devel@rtems.org" target="_blank" rel="noreferrer">devel@rtems.org</a><br>
> <a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank" rel="noreferrer">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a></blockquote></div></div></div>