summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2020-06-04 13:55:17 +0200
committerSebastian Huber <sebastian.huber@embedded-brains.de>2020-06-08 08:53:02 +0200
commitca2f5e638459459868bebd270bda0f82433cf36d (patch)
treee8be84b97dc0200d26df67aa888f4269855ad4dd
parenteng: Add a specification type for actions (diff)
downloadrtems-docs-ca2f5e638459459868bebd270bda0f82433cf36d.tar.bz2
eng: Update specification how-to section
Update #3715.
-rw-r--r--eng/req/howto.rst75
1 files changed, 75 insertions, 0 deletions
diff --git a/eng/req/howto.rst b/eng/req/howto.rst
index de9b145..9a28427 100644
--- a/eng/req/howto.rst
+++ b/eng/req/howto.rst
@@ -5,6 +5,81 @@
How-To
======
+Getting Started
+---------------
+
+The RTEMS specification items and qualification tools are work in progress and
+not fully integrated in the RTEMS Project. The first step to work with the
+RTEMS specification and the corresponding tools is a clone of the following
+repository:
+
+.. code-block:: none
+
+ git clone git://git.rtems.org/sebh/rtems-qual.git
+ git submodule init
+ git submodule update
+
+The tools need a virtual Python 3 environment. To set it up use:
+
+.. code-block:: none
+
+ cd rtems-qual
+ make env
+
+Each time you want to use one of the tools, you have to activate the
+environment in your shell:
+
+.. code-block:: none
+
+ cd rtems-qual
+ . env/bin/activate
+
+Glossary Specification
+----------------------
+
+The glossary of terms for the RTEMS Project is defined by
+:ref:`SpecTypeGlossaryTermItemType` items in the :file:`spec/glossary`
+directory. For a new glossary term add a glossary item to this directory. As
+the file name use the term in lower case with all white space and special
+characters removed or replaced by alphanumeric characters, for example
+:file:`spec/glossary/magicpower.yml` for the term `magic power`.
+
+Use ``${uid:/attribute}`` substitutions to reference other parts of the
+specification.
+
+.. code-block:: yaml
+
+ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+ copyrights:
+ - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+ enabled-by: true
+ glossary-type: term
+ links:
+ - role: glossary-member
+ uid: ../glossary-general
+ term: magic power
+ text: |
+ Magic power enables a caller to create magic objects using a
+ ${magicwand:/term}.
+ type: glossary
+
+Define acronyms with the phrase `This term is an acronym for *.` in the
+``text`` attribute:
+
+.. code-block:: yaml
+
+ ...
+ term: MP
+ ...
+ text: |
+ This term is an acronym for Magic Power.
+ ...
+
+Once you are done with the glossary items, run the script :file:`spec2doc.py`
+to generate the derived documentation content. Send patches for the generated
+documentation and the specification to the :r:list:`devel` and follow the
+normal patch review process.
+
Interface Specification
-----------------------