On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom <ged...@rtems.org> wrote: > On Fri, Jan 3, 2020 at 3:25 AM Sebastian Huber > <sebastian.hu...@embedded-brains.de> wrote: > > > > On 03/01/2020 10:42, andrew.butterfi...@cs.tcd.ie wrote: > > > Hello all, and Happy New Year! > > > > > >> On 3 Jan 2020, at 08:10, Sebastian Huber < > sebastian.hu...@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.hu...@embedded-brains.de > > PGP : Public key available on request. > > > > Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. > > _______________________________________________ > > devel mailing list > > devel@rtems.org > > http://lists.rtems.org/mailman/listinfo/devel > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
