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
