[RTEMS Project] #3853: Add and use project-wide glossary to documentation

[RTEMS trac]

#3853: Add and use project-wide glossary to documentation
-----------------------------+------------------------------
 Reporter:  Sebastian Huber  |       Owner:  Sebastian Huber
     Type:  enhancement      |      Status:  assigned
 Priority:  normal           |   Milestone:  5.1
Component:  doc              |     Version:  5
 Severity:  normal           |  Resolution:
 Keywords:                   |  Blocked By:
 Blocking:                   |
-----------------------------+------------------------------
Description changed by Sebastian Huber:

Old description:

> See discussion:
>
> https://lists.rtems.org/pipermail/devel/2020-January/056728.html
>
> Use c-user/glossary.rst as the project-wide glossary. Generate document-
> specific glossaries from this file and the use of :term: in the specific
> document.  Add new waf target "./waf regenerate" to carry out the
> glossary generation.

New description:

 See discussion:

 https://lists.rtems.org/pipermail/devel/2020-January/056728.html

 == Approach A

 Use c-user/glossary.rst as the project-wide glossary. Generate document-
 specific glossaries from this file and the use of :term: in the specific
 document.  Add new waf target "./waf regenerate" to carry out the glossary
 generation.

 == Approach B

 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 of the DoD Architecture Framework (DoDAF) 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.

--

--
Ticket URL: <http://devel.rtems.org/ticket/3853#comment:1>
RTEMS Project <http://www.rtems.org/>
RTEMS Project