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.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.