#3853 closed enhancement (fixed)

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: qualification
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 (12)

comment:1 Changed on 01/08/20 at 06:38:00 by Sebastian Huber

Description: modified (diff)

comment:2 Changed on 02/24/20 at 13:58:46 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 02/27/20 at 12:15:10 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 03/02/20 at 07:14:50 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 03/02/20 at 07:14:52 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 03/02/20 at 07:14:54 by Sebastian Huber <sebastian.huber@…>

In d2acbca/rtems-docs:

c-user: Sort glossary terms

Update #3853.

comment:7 Changed on 03/02/20 at 07:14:56 by Sebastian Huber <sebastian.huber@…>

In 9965922/rtems-docs:

c-user: Merge parition term definitions

Update #3853.

comment:8 Changed on 03/02/20 at 07:14:58 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 03/02/20 at 07:15:00 by Sebastian Huber <sebastian.huber@…>

In 7d05a3d/rtems-docs:

eng: Add glossary

Update #3853.

comment:10 Changed on 03/03/20 at 06:19:02 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

comment:11 Changed on 06/18/21 at 09:24:45 by Sebastian Huber

Keywords: qualification added

comment:12 Changed on 06/18/21 at 09:46:18 by Sebastian Huber

Resolution: fixed
Status: assignedclosed

Glossary term handling is implemented in:

https://git.rtems.org/rtems-central/

Note: See TracTickets for help on using tickets.