[PATCH 2/2] c-user: Canonicalize document internal references

Sebastian Huber sebastian.huber at embedded-brains.de
Tue Jul 7 11:06:14 UTC 2020 

This helps to generate Doxygen markup from the application configuration
option specification items.

Update #3994.
---
 c-user/config/classic-api.rst       |  7 +--
 c-user/config/general.rst           |  6 +-
 c-user/config/posix-api.rst         | 11 ++--
 c-user/config/scheduler-general.rst | 87 +++++++++++++----------------
 4 files changed, 49 insertions(+), 62 deletions(-)

diff --git a/c-user/config/classic-api.rst b/c-user/config/classic-api.rst
index b72ad30..07c79b2 100644
--- a/c-user/config/classic-api.rst
+++ b/c-user/config/classic-api.rst
@@ -356,11 +356,8 @@ NOTES:
 
     The calculations for the required memory in the RTEMS Workspace for tasks
     assume that each task has a minimum stack size and has floating point
-    support enabled.  The configuration parameter
-    ``CONFIGURE_EXTRA_TASK_STACKS`` is used to specify task stack requirements
-    *ABOVE* the minimum size required.  See :ref:`Reserve Task/Thread Stack
-    Memory Above Minimum` for more information about
-    ``CONFIGURE_EXTRA_TASK_STACKS``.
+    support enabled.  The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used
+    to specify task stack requirements *above* the minimum size required.
 
     The maximum number of POSIX threads is specified by
     :ref:`CONFIGURE_MAXIMUM_POSIX_THREADS`.
diff --git a/c-user/config/general.rst b/c-user/config/general.rst
index 08f2a92..d495c7a 100644
--- a/c-user/config/general.rst
+++ b/c-user/config/general.rst
@@ -216,9 +216,9 @@ NOTES:
     to perform the sequential system initialization before the multithreading
     is started.
 
-    The interrupt stacks are covered by the :ref:`stack checker
-    <CONFIGURE_STACK_CHECKER_ENABLED>`.  However, using a too small interrupt
-    stack size may still result in undefined behaviour.
+    The interrupt stacks are covered by the stack checker, see
+    :ref:`CONFIGURE_STACK_CHECKER_ENABLED`.  However, using a too small interrupt stack
+    size may still result in undefined behaviour.
 
     In releases before RTEMS 5.1 the default value was
     :ref:`CONFIGURE_MINIMUM_TASK_STACK_SIZE` instead of ``CPU_STACK_MINIMUM_SIZE``.
diff --git a/c-user/config/posix-api.rst b/c-user/config/posix-api.rst
index 23aeb62..7a683d4 100644
--- a/c-user/config/posix-api.rst
+++ b/c-user/config/posix-api.rst
@@ -330,13 +330,10 @@ NOTES:
     This object class can be configured in unlimited allocation mode, see
     :ref:`ConfigUnlimitedObjects`.
 
-    This calculations for the required memory in the RTEMS Workspace for
-    threads assume that each thread has a minimum stack size and has floating
-    point support enabled.  The configuration option
-    :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used to specify thread stack
-    requirements **above** the minimum size required.  See :ref:`Reserve
-    Task/Thread Stack Memory Above Minimum` for more information about
-    ``CONFIGURE_EXTRA_TASK_STACKS``.
+    This calculations for the required memory in the RTEMS Workspace for threads
+    assume that each thread has a minimum stack size and has floating point
+    support enabled.  The configuration option :ref:`CONFIGURE_EXTRA_TASK_STACKS` is used
+    to specify thread stack requirements **above** the minimum size required.
 
     The maximum number of Classic API Tasks is specified by
     :ref:`CONFIGURE_MAXIMUM_TASKS`.
diff --git a/c-user/config/scheduler-general.rst b/c-user/config/scheduler-general.rst
index c353f16..274a7cf 100644
--- a/c-user/config/scheduler-general.rst
+++ b/c-user/config/scheduler-general.rst
@@ -13,17 +13,18 @@ and only necessary in very specific circumstances.  A normal application
 configuration does not need any of the configuration options described in this
 section.
 
-By default, the :ref:`Deterministic Priority Scheduler <SchedulerPriority>`
+By default, the :ref:`SchedulerPriority`
 algorithm is used in uniprocessor configurations.  In case SMP is enabled and
 the configured maximum processors
 (:ref:`CONFIGURE_MAXIMUM_PROCESSORS`) is greater
-than one, then the :ref:`Earliest Deadline First (EDF) SMP Scheduler
-<SchedulerSMPEDF>` is selected as the default scheduler algorithm.
+than one, then the
+:ref:`SchedulerSMPEDF`
+is selected as the default scheduler algorithm.
 
-For the :ref:`schedulers built into
-RTEMS <SchedulingConcepts>`, the configuration is straightforward.  All that is
-required is to define the configuration option which specifies which scheduler
-you want for in your application.
+For the schedulers provided by RTEMS (see :ref:`SchedulingConcepts`), the
+configuration is straightforward.  All that is required is to define the
+configuration option which specifies which scheduler you want for in your
+application.
 
 The pluggable scheduler interface also enables the user to provide their own
 scheduling algorithm.  If you choose to do this, you must define multiple
@@ -183,16 +184,15 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Constant Bandwidth Server (CBS) Scheduler <SchedulerCBS>`
+    :ref:`SchedulerCBS`
     algorithm is made available to the application.
 
 NOTES:
     This scheduler configuration option is an advanced configuration option.
     Think twice before you use it.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for exactly one processor.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for exactly one processor.
 
 .. index:: CONFIGURE_SCHEDULER_EDF
 
@@ -213,16 +213,15 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Earliest Deadline First (EDF) Scheduler <SchedulerEDF>`
+    :ref:`SchedulerEDF`
     algorithm is made available to the application.
 
 NOTES:
     This scheduler configuration option is an advanced configuration option.
     Think twice before you use it.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for exactly one processor.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for exactly one processor.
 
 .. index:: CONFIGURE_SCHEDULER_EDF_SMP
 
@@ -243,7 +242,7 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Earliest Deadline First (EDF) SMP Scheduler <SchedulerSMPEDF>`
+    :ref:`SchedulerSMPEDF`
     algorithm is made available to the application.
 
 NOTES:
@@ -253,9 +252,8 @@ NOTES:
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for up to 32 processors.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for up to 32 processors.
 
     This scheduler algorithm is the default in SMP configurations if
     :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is
@@ -277,21 +275,21 @@ OPTION TYPE:
 DEFAULT VALUE:
     The default value is
 
-    * ``"MEDF"`` for the :ref:`EDF SMP Scheduler <SchedulerSMPEDF>`,
+    * ``"MEDF"`` for the :ref:`SchedulerSMPEDF`,
 
-    * ``"MPA "`` for the :ref:`Arbitrary Processor Affinity Priority SMP Scheduler <SchedulerSMPPriorityAffinity>`,
+    * ``"MPA "`` for the :ref:`SchedulerSMPPriorityAffinity`,
 
-    * ``"MPD "`` for the :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>`,
+    * ``"MPD "`` for the :ref:`SchedulerSMPPriority`,
 
-    * ``"MPS "`` for the :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>`,
+    * ``"MPS "`` for the :ref:`SchedulerSMPPrioritySimple`,
 
-    * ``"UCBS"`` for the :ref:`Uniprocessor CBS Scheduler <SchedulerCBS>`,
+    * ``"UCBS"`` for the :ref:`SchedulerCBS`,
 
-    * ``"UEDF"`` for the :ref:`Uniprocessor EDF Scheduler <SchedulerEDF>`,
+    * ``"UEDF"`` for the :ref:`SchedulerEDF`,
 
-    * ``"UPD "`` for the :ref:`Uniprocessor Deterministic Priority Scheduler <SchedulerPriority>`, and
+    * ``"UPD "`` for the :ref:`SchedulerPriority`, and
 
-    * ``"UPS "`` for the :ref:`Uniprocessor Simple Priority Scheduler <SchedulerPrioritySimple>`.
+    * ``"UPS "`` for the :ref:`SchedulerPrioritySimple`.
 
 VALUE CONSTRAINTS:
     The value of this configuration option shall be a valid integer of type
@@ -328,16 +326,15 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Deterministic Priority Scheduler <SchedulerPriority>`
+    :ref:`SchedulerPriority`
     algorithm is made available to the application.
 
 NOTES:
     This scheduler configuration option is an advanced configuration option.
     Think twice before you use it.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for exactly one processor.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for exactly one processor.
 
     This scheduler algorithm is the default when
     :ref:`CONFIGURE_MAXIMUM_PROCESSORS` is
@@ -365,7 +362,7 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Arbitrary Processor Affinity SMP Scheduler <SchedulerSMPPriorityAffinity>`
+    :ref:`SchedulerSMPPriorityAffinity`
     algorithm is made available to the application.
 
 NOTES:
@@ -375,9 +372,8 @@ NOTES:
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for up to 32 processors.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for up to 32 processors.
 
     The memory allocated for this scheduler depends on the
     :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option.
@@ -401,7 +397,7 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Deterministic Priority SMP Scheduler <SchedulerSMPPriority>`
+    :ref:`SchedulerSMPPriority`
     algorithm is made available to the application.
 
 NOTES:
@@ -411,9 +407,8 @@ NOTES:
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for up to 32 processors.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for up to 32 processors.
 
     The memory allocated for this scheduler depends on the
     :ref:`CONFIGURE_MAXIMUM_PRIORITY` configuration option.
@@ -437,16 +432,15 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Simple Priority Scheduler <SchedulerPrioritySimple>`
+    :ref:`SchedulerPrioritySimple`
     algorithm is made available to the application.
 
 NOTES:
     This scheduler configuration option is an advanced configuration option.
     Think twice before you use it.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for exactly one processor.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for exactly one processor.
 
 .. index:: CONFIGURE_SCHEDULER_SIMPLE_SMP
 
@@ -467,7 +461,7 @@ DEFAULT CONFIGURATION:
 
 DESCRIPTION:
     In case this configuration option is defined, then
-    :ref:`Simple Priority SMP Scheduler <SchedulerSMPPrioritySimple>`
+    :ref:`SchedulerSMPPrioritySimple`
     algorithm is made available to the application.
     application.
 
@@ -478,9 +472,8 @@ NOTES:
     This scheduler algorithm is only available when RTEMS is built with SMP
     support enabled.
 
-    In case no explicit :ref:`clustered scheduler configuration
-    <ConfigurationSchedulersClustered>` is present, then it is used as the
-    scheduler for up to 32 processors.
+    In case no explicit :ref:`ConfigurationSchedulersClustered`
+    is present, then it is used as the scheduler for up to 32 processors.
 
 .. index:: CONFIGURE_SCHEDULER_STRONG_APA
 
-- 
2.26.2

More information about the devel mailing list