#3853 assigned enhancement

Add and use project-wide glossary to documentation

Reported by: Sebastian Huber Owned by: Sebastian Huber
Priority: normal Milestone: 6.1
Component: doc Version: 6
Severity: normal Keywords:
Cc: Blocked By:
Blocking:

Description (last modified by Sebastian Huber)

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.

Change History (10)

comment:1 Changed on Jan 8, 2020 at 6:38:00 AM by Sebastian Huber

Description: modified (diff)

comment:2 Changed on Feb 24, 2020 at 1:58:46 PM by Sebastian Huber <sebastian.huber@…>

In 03facda/rtems-docs:

c-user: Rework glossary

Define exactly one term per definition. Use references for alternative
terms. Add :term: text roles to acronym definitions of glossary defined
terms.

Update #3853.

comment:3 Changed on Feb 27, 2020 at 12:15:10 PM by Sebastian Huber <sebastian.huber@…>

In 732c570/rtems-docs:

c-user: Canonicalize two glossary acronyms

Add :term: text roles to acronym definitions of glossary defined terms.

Update #3853.

comment:4 Changed on Mar 2, 2020 at 7:14:50 AM by Sebastian Huber <sebastian.huber@…>

In 43b7eeb/rtems-docs:

c-user: Use four spaces per indent level

Four spaces per indent level is used in most files.

Update #3853.

comment:5 Changed on Mar 2, 2020 at 7:14:52 AM by Sebastian Huber <sebastian.huber@…>

In 834dcf5/rtems-docs:

c-user: Clarify return code related terms

Remove duplicate "return code" definition. Add all related terms and
use references.

Update #3853.

comment:6 Changed on Mar 2, 2020 at 7:14:54 AM by Sebastian Huber <sebastian.huber@…>

In d2acbca/rtems-docs:

c-user: Sort glossary terms

Update #3853.

comment:7 Changed on Mar 2, 2020 at 7:14:56 AM by Sebastian Huber <sebastian.huber@…>

In 9965922/rtems-docs:

c-user: Merge parition term definitions

Update #3853.

comment:8 Changed on Mar 2, 2020 at 7:14:58 AM by Sebastian Huber <sebastian.huber@…>

In bba4a8c/rtems-docs:

c-user: Add copyrights to glossary

Use the file history to derive the copyright information.

Update #3853.

comment:9 Changed on Mar 2, 2020 at 7:15:00 AM by Sebastian Huber <sebastian.huber@…>

In 7d05a3d/rtems-docs:

eng: Add glossary

Update #3853.

comment:10 Changed on Mar 3, 2020 at 6:19:02 AM by Sebastian Huber

Milestone: 5.16.1
Version: 56

A prototype for the RTEMS Specification Items and Qualification Tools is available here:

https://git.rtems.org/sebh/rtems-qual.git/

https://github.com/sebhub/rtems-qual

Note: See TracTickets for help on using tickets.