Glossary of Terms

[Sebastian Huber]

Hello,

we have currently only two glossary of terms in the RTEMS documentation set:

https://docs.rtems.org/branches/master/user/glossary/index.html

https://docs.rtems.org/branches/master/c-user/glossary.html

We also need one in the RTEMS Software Engineering manual. Sphinx has 
currently some limitations in the way glossary terms are managed:


https://github.com/sphinx-doc/sphinx/issues/3559

It would be nice if it worked like the TeX acronym package:

https://ctan.org/pkg/acronym?lang=en

The problem is that the Sphinx maintainer is not really interested in 
this feature and I don't have enough knowledge/time/skill to implement 
it myself.


How do we want to deal with glossaries in the documentation?

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?

A proper glossary is very important from my point of view, especially 
for the pre-qualification activity. Different standards define terms 
differently. We need a clear definition of terms for the RTEMS Project, 
otherwise the will have a lot of confusion if people from different 
domains task with each other.


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

Re: Glossary of Terms

[Sebastian Huber]

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

Re: Glossary of Terms

[Gedare Bloom]

On Fri, Jan 3, 2020 at 3:25 AM Sebastian Huber
 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 
> >>  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 `
> 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.

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

Re: Glossary of Terms

[Joel Sherrill]

On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  wrote:

> On Fri, Jan 3, 2020 at 3:25 AM Sebastian Huber
>  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 `
> > 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
glos

Re: Glossary of Terms

[Sebastian Huber]

On 03/01/2020 18:16, Joel Sherrill wrote:



On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom > 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).


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

Re: Glossary of Terms

[Gedare Bloom]

On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
 wrote:
>
> On 03/01/2020 18:16, Joel Sherrill wrote:
> >
> >
> > On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  > > 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:.)

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

Re: Glossary of Terms

[Sebastian Huber]

On 07/01/2020 17:21, Gedare Bloom wrote:

On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
  wrote:

On 03/01/2020 18:16, Joel Sherrill wrote:


On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom 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.


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.


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

Re: Glossary of Terms

[Gedare Bloom]

On Tue, Jan 7, 2020 at 11:34 PM Sebastian Huber
 wrote:
>
>
>
> On 07/01/2020 17:21, Gedare Bloom wrote:
> > On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
> >   wrote:
> >> On 03/01/2020 18:16, Joel Sherrill wrote:
> >>>
> >>> On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  >>> > 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

Re: Glossary of Terms

[Joel Sherrill]

On Wed, Jan 8, 2020 at 12:36 PM Gedare Bloom  wrote:

> On Tue, Jan 7, 2020 at 11:34 PM Sebastian Huber
>  wrote:
> >
> >
> >
> > On 07/01/2020 17:21, Gedare Bloom wrote:
> > > On Tue, Jan 7, 2020 at 2:09 AM Sebastian Huber
> > >   wrote:
> > >> On 03/01/2020 18:16, Joel Sherrill wrote:
> > >>>
> > >>> On Fri, Jan 3, 2020, 10:22 AM Gedare Bloom  > >>> > 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.
>

+1

I know I have said this to anyone who will listen in person but I think the
questions we are answering and infrastructure being built up to address
pre-qualification and high integrity development processes will be of
great value outside the RTEMS Project. As banal as glossary management
sounds, managing as recommended by DoDAF and doing it with open
source tools is a BIG deal. Similar with requirements and traceability.

Let's keep solving big problems in simple ways with open source tools. :)

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

[PATCH 0/5] Rework glossary of terms

[Sebastian Huber]

This patch set reworks the glossary of terms so that it can be automatically
generated from specification items.

Sebastian Huber (5):
  c-user: Use four spaces per indent level
  c-user: Clarify return code related terms
  c-user: Sort glossary terms
  c-user: Merge parition term definitions
  c-user: Add copyrights to glossary

 c-user/glossary.rst | 1295 ++-
 1 file changed, 653 insertions(+), 642 deletions(-)

-- 
2.16.4

___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel