On Tue, Jan 7, 2020 at 11:34 PM Sebastian Huber <sebastian.hu...@embedded-brains.de> wrote: > > > > On 07/01/2020 17:21, Gedare Bloom wrote: > > On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber > > <sebastian.hu...@embedded-brains.de> wrote: > >> On 03/01/2020 18:16, Joel Sherrill wrote: > >>> > >>> On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom <ged...@rtems.org > >>> <mailto:ged...@rtems.org>> wrote: > >> [...] > >>> 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. > >> Good, so my proposal is this: > >> > >> 1. I move c-user/glossary.rst to common/glossary.rst and include this > >> file as is in c-user. > >> > >> 2. The glossary.rst for the other documents is generated from > >> common/glossary.rst based on the :term: usage. This can start simple, > >> e.g. only look at the *.rst files in the document directory (e.g. no > >> recursive includes). > >> > > Later when a new term is added for something not in c-user, then the > > c-user should be updated to also derive its glossary with :term:? > > (Before that, we might need to double check if the current glossary > > terms are all defined/used in c-user with :term:.) > > The :term: is sparely used in c-user currently. It would require a bit > of manual work to pull in all terms via this text role. > Understood, although adding those :term: from the existing glossary seems like a good job for grep and sed to me.
> After one night, I don't like my proposal any more. I think it would be > better to move the glossary terms to the RTEMS specification (e.g. in > the RTEMS sources "spec/glossary/*.yml") and generate the glossary.rst > for the documents with a script. This gives us more flexibility and > removes the need for the special parser code, see: > > https://lists.rtems.org/pipermail/devel/2020-January/056811.html > > The AV-2 mentioned by Joel wants the glossary terms in categories. We > could add categories to the glossary specification items. This would be > difficult with a master glossary in reST. > Yes, putting the glossary terms in a parseable structure like YAML sounds sensible. > -- > 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
