<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jan 8, 2020 at 12:36 PM Gedare Bloom <<a href="mailto:gedare@rtems.org">gedare@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Tue, Jan 7, 2020 at 11:34 PM Sebastian Huber<br>
<<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a>> wrote:<br>
><br>
><br>
><br>
> On 07/01/2020 17:21, Gedare Bloom wrote:<br>
> > On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber<br>
> > <<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a>>  wrote:<br>
> >> On 03/01/2020 18:16, Joel Sherrill wrote:<br>
> >>><br>
> >>> On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom <<a href="mailto:gedare@rtems.org" target="_blank">gedare@rtems.org</a><br>
> >>> <mailto:<a href="mailto:gedare@rtems.org" target="_blank">gedare@rtems.org</a>>> wrote:<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>
> >>><br>
> >>><br>
> >>> The DoD Architecture Framework (DoDAF) calls this an AV-2 which is a<br>
> >>> singular artifacr across the project for consistencyt<br>
> >>><br>
> >>> <a href="http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary" rel="noreferrer" target="_blank">http://acqnotes.com/acqnote/tasks/av-2-integrated-dictionary</a><br>
> >>><br>
> >>> That said, you need glossaries in documents and automating pulling<br>
> >>> definitions and acronyms out automatically producing a glossary and<br>
> >>> acronym list from the master AV-2 is desirable. No one wants to<br>
> >>> reference a standalone glossary.<br>
> >>><br>
> >>> There can be issues if definitions change over time because the single<br>
> >>> AV-2 can't deal with old and new. It gets confusing. I have seen a<br>
> >>> project where the AV-2 included history like the Oxford English<br>
> >>> Dictionary. It was dreadful.<br>
> >>><br>
> >>> That's a lot of background to say this isn't a RTEMS unique problem. A<br>
> >>> central database of acronyms and definitions would be a good thing. If<br>
> >>> grep is sufficient to find word use to trigger inclusion in a document<br>
> >>> specific glossary, great.<br>
> >> Good, so my proposal is this:<br>
> >><br>
> >> 1. I move c-user/glossary.rst to common/glossary.rst and include this<br>
> >> file as is in c-user.<br>
> >><br>
> >> 2. The glossary.rst for the other documents is generated from<br>
> >> common/glossary.rst based on the :term: usage. This can start simple,<br>
> >> e.g. only look at the *.rst files in the document directory (e.g. no<br>
> >> recursive includes).<br>
> >><br>
> > Later when a new term is added for something not in c-user, then the<br>
> > c-user should be updated to also derive its glossary with :term:?<br>
> > (Before that, we might need to double check if the current glossary<br>
> > terms are all defined/used in c-user with :term:.)<br>
><br>
> The :term: is sparely used in c-user currently. It would require a bit<br>
> of manual work to pull in all terms via this text role.<br>
><br>
Understood, although adding those :term: from the existing glossary<br>
seems like a good job for grep and sed to me.<br>
<br>
> After one night, I don't like my proposal any more. I think it would be<br>
> better to move the glossary terms to the RTEMS specification (e.g. in<br>
> the RTEMS sources "spec/glossary/*.yml") and generate the glossary.rst<br>
> for the documents with a script.  This gives us more flexibility and<br>
> removes the need for the special parser code, see:<br>
><br>
> <a href="https://lists.rtems.org/pipermail/devel/2020-January/056811.html" rel="noreferrer" target="_blank">https://lists.rtems.org/pipermail/devel/2020-January/056811.html</a><br>
><br>
> The AV-2 mentioned by Joel wants the glossary terms in categories. We<br>
> could add categories to the glossary specification items. This would be<br>
> difficult with a master glossary in reST.<br>
><br>
Yes, putting the glossary terms in a parseable structure like YAML<br>
sounds sensible.<br></blockquote><div><br></div><div>+1</div><div><br></div><div>I know I have said this to anyone who will listen in person but I think the</div><div>questions we are answering and infrastructure being built up to address</div><div>pre-qualification and high integrity development processes will be of</div><div>great value outside the RTEMS Project. As banal as glossary management</div><div>sounds, managing as recommended by DoDAF and doing it with open</div><div>source tools is a BIG deal. Similar with requirements and traceability.</div><div><br></div><div>Let's keep solving big problems in simple ways with open source tools. :)</div><div><br></div><div>--joel</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);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">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">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a></blockquote></div></div>