Thanks for this. I saw just a few typos and grammatical fixes/suggestions.
On Wed, Aug 5, 2020 at 11:47 PM Sebastian Huber
<sebastian.hu...@embedded-brains.de> wrote:
>
> Update #3715.
> ---
> eng/req/howto.rst | 118 ++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 118 insertions(+)
>
> diff --git a/eng/req/howto.rst b/eng/req/howto.rst
> index 9a28427..475794c 100644
> --- a/eng/req/howto.rst
> +++ b/eng/req/howto.rst
> @@ -34,6 +34,124 @@ environment in your shell:
> cd rtems-qual
> . env/bin/activate
>
> +Application Configuration Options
> +---------------------------------
> +
> +The application configuration options and groups are maintained by
> +specification items in the directory :file:`spec/if/acfg`. Application
> +configuration options are grouped by
> +:ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be
> +stored in files using the :file:`spec/if/acfg/group-*.yml` pattern. Each
> +application configuration options shall link to exactly one group item with
> the
s/options/option
> +:ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`. There are four
> +application option item types available which cover all existing options:
> +
> +* The *feature enable options* enable feature. If the option is not defined
> by
"The *feature enable options* let the application enable a feature option."
I like the wording in the third/fourth bullets, mirror it here and
below for consistency.
> + the application configuration, then the feature is simply not available or
delete "by the application configuration" it is implied?
> + active. There should be no feature-specific code linked to the application
> + if the option is not defined. Examples are options which enable a device
> + driver like ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``. These options
> are
> + specified by
> + :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` items.
> +
> +* The *feature options* enable a feature if the option is defined by the
> + application configuration, otherwise another feature is active. If the
> + option is not defined, then feature-specific code may linked to the
"The *feature options* let the application enable a specific feature
option. If the option is not defined, then a default feature option is
used. Feature-specific code may be linked"
Note "may be"
> + application. Examples are options which disable a feature if the option is
> + defined such as ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` and options
> + which provide a stub implementation of a feature by default and a full
> + implementation if the option is defined such as
> + ``CONFIGURE_IMFS_ENABLE_MKFIFO``. These options are specified by
> + :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` items.
> +
> +* The *integer value options* let the application define a specific value
> for a
> + system parameter. If the option is not defined, then a default value is
> used
> + for the system parameter. Examples are options which define the maximum
> + count of objects available for application use such as
> + ``CONFIGURE_MAXIMUM_TASKS``. These options are specified by
> + :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items.
> +
> +* The *initializer options* let the application define a specific initializer
> + for a system parameter. If the option is not defined, then a default
> setting
> + is used for the system parameter. An example option of this type is
> + ``CONFIGURE_INITIAL_EXTENSIONS``. These options are specified by
> + :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items.
> +
> +From the specification items Sphinx documentation sources and header files
> with
> +Doxygen markup are generated. The descriptions in the items shall use a
English grammar reads better when the subject comes first, and putting
the prepositional phrase ("from") closer to its action verb:
"Sphinx documentation sources and header files with Doxygen markup are
generated from the specification items."
> +restricted Sphinx formatting. Emphasis via one asterix ("*"), strong
> emphasis
s/asterix/asterisk
> +via two asterix ("**"), code samples via blockquotes ("``"), code blocks ("..
s/asterix/asterisks
> +code-block:: c") and lists are allowed. References to interface items are
> also
> +allowed, for example "${appl-needs-clock-driver:/name}" and
> +"${../rtems/tasks/create:/name}". References to other parts of the
> +documentation are possible, however, they are currently provided by
> hard-coded
> +tables in :file:`rtemsspec/applconfig.py`.
> +
> +Modify an Existing Group
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Search for the group by its section header and edit the specification item
> +file. For example:
> +
> +.. code-block:: none
> +
> + $ grep -rl "name: General System Configuration" spec/if/acfg
> + spec/if/acfg/group-general.yml
> + $ vi spec/if/acfg/group-general.yml
> +
> +Modify an Existing Option
> +^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Search for the option by its define name and edit the specification item
> file.
May be clearer to say "CPP define" or "#define"?
> +For example:
> +
> +.. code-block:: none
> +
> + $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/if/acfg
> + spec/if/acfg/appl-needs-clock-driver.yml
> + $ vi spec/if/acfg/appl-needs-clock-driver.yml
> +
> +Add a New Group
> +^^^^^^^^^^^^^^^
> +
> +Let ``new`` be the UID name part of the new group. Create the file
> +:file:`spec/if/acfg/group-new.yml` and provide all attributes for an
> +:ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example:
> +
> +.. code-block:: none
> +
> + $ vi spec/if/acfg/group-new.yml
> +
> +Add a New Option
> +^^^^^^^^^^^^^^^^
> +
> +Let ``my-new-option`` be the UID name of the option. Create the file
> +:file:`if/acfg/my-new-option.yml` and provide all attributes for an
> appropriate
> +refinement of :ref:`SpecTypeApplicationConfigurationOptionItemType`. For
> +example:
> +
> +.. code-block:: none
> +
> + $ vi spec/if/acfg/my-new-option.yml
> +
> +Generate Content after Changes
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Once you are done with the modifications of an existing item or the creation
> of
The rest of this document is in the third person or second-person
understood (meaning, we never say "you" but it is understood that
"you" do the things). It may be more consistent to remove these "you":
"After modification of an existing item ..."
> +a new item, the changes need to be propagated to generated source files.
> This
> +is done by the :file:`spec2doc.py` script. Before you call this script, make
"Before calling this script, ..."
> +sure the Git submodules are up-to-date.
> +
> +.. code-block:: none
> +
> + $ ./spec2doc.py
> +
> +The script modifies or creates source files in :file:`modules/rtems` and
> +:file:`modules/rtems-docs`. Create patch sets for these changes just as
> these
s/as/as if
> +where work done by a human and follow the normal patch review process
> described
s/where/were
> +in the *RTEMS User Manual*. When the changes are integrated, update the Git
> +submodules and check in the changed items.
> +
> Glossary Specification
> ----------------------
>
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel@rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
