c-user: Format the directives as descriptions.

This change combined with the element list change in latex generates
a much better looking PDF.

Add a page break before each directive to like th previous versions of the
manuals.

1 files changed, 304 insertions, 311 deletions

diff --git a/c-user/timer_manager.rst b/c-user/timer_manager.rst
index 088c1b3..d9ffd92 100644
--- a/c-user/timer_manager.rst
+++ b/c-user/timer_manager.rst
@@ -189,446 +189,439 @@ This section details the timer manager's directives.  A subsection is dedicated
 to each of this manager's directives and describes the calling sequence,
 related constants, usage, and status codes.
 
+.. raw:: latex
+
+   \clearpage
 .. _rtems_timer_create:
 
 TIMER_CREATE - Create a timer
 -----------------------------
 .. index:: create a timer
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_create
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_create(
-        rtems_name  name,
-        rtems_id   *id
-    );
+CALLING SEQUENCE:
+    .. code-block:: c
 
-**DIRECTIVE STATUS CODES:**
+        rtems_status_code rtems_timer_create(
+            rtems_name  name,
+            rtems_id   *id
+        );
 
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
 
- * - ``RTEMS_SUCCESSFUL``
-   - timer created successfully
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
-   - invalid timer name
- * - ``RTEMS_TOO_MANY``
-   - too many timers created
+     * - ``RTEMS_SUCCESSFUL``
+       - timer created successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``id`` is NULL
+     * - ``RTEMS_INVALID_NAME``
+       - invalid timer name
+     * - ``RTEMS_TOO_MANY``
+       - too many timers created
 
-**DESCRIPTION:**
+DESCRIPTION:
+    This directive creates a timer.  The assigned timer id is returned in id.
+    This id is used to access the timer with other timer manager directives.
+    For control and maintenance of the timer, RTEMS allocates a TMCB from the
+    local TMCB free pool and initializes it.
 
-This directive creates a timer.  The assigned timer id is returned in id.  This
-id is used to access the timer with other timer manager directives.  For
-control and maintenance of the timer, RTEMS allocates a TMCB from the local
-TMCB free pool and initializes it.
+NOTES:
+    This directive will not cause the calling task to be preempted.
 
-**NOTES:**
+.. raw:: latex
 
-This directive will not cause the calling task to be preempted.
+   \clearpage
 
 .. _rtems_timer_ident:
 
 TIMER_IDENT - Get ID of a timer
 -------------------------------
 .. index:: obtain the ID of a timer
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_ident
 
-.. code-block:: c
+CALLING SEQUENCE:
+    .. code-block:: c
 
-    rtems_status_code rtems_timer_ident(
-        rtems_name  name,
-        rtems_id   *id
-    );
+        rtems_status_code rtems_timer_ident(
+            rtems_name  name,
+            rtems_id   *id
+        );
 
-**DIRECTIVE STATUS CODES:**
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
 
-.. list-table::
- :class: rtems-table
+     * - ``RTEMS_SUCCESSFUL``
+       - timer identified successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``id`` is NULL
+     * - ``RTEMS_INVALID_NAME``
+       - timer name not found
 
- * - ``RTEMS_SUCCESSFUL``
-   - timer identified successfully
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``id`` is NULL
- * - ``RTEMS_INVALID_NAME``
-   - timer name not found
+DESCRIPTION:
+    This directive obtains the timer id associated with the timer name to be
+    acquired.  If the timer name is not unique, then the timer id will match
+    one of the timers with that name.  However, this timer id is not guaranteed
+    to correspond to the desired timer.  The timer id is used to access this
+    timer in other timer related directives.
 
-**DESCRIPTION:**
+NOTES:
+    This directive will not cause the running task to be preempted.
 
-This directive obtains the timer id associated with the timer name to be
-acquired.  If the timer name is not unique, then the timer id will match one of
-the timers with that name.  However, this timer id is not guaranteed to
-correspond to the desired timer.  The timer id is used to access this timer in
-other timer related directives.
+.. raw:: latex
 
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
+   \clearpage
 
 .. _rtems_timer_cancel:
 
 TIMER_CANCEL - Cancel a timer
 -----------------------------
 .. index:: cancel a timer
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_cancel
 
-.. code-block:: c
+CALLING SEQUENCE:
+    .. code-block:: c
 
-    rtems_status_code rtems_timer_cancel(
-        rtems_id id
-    );
+        rtems_status_code rtems_timer_cancel(
+            rtems_id id
+        );
 
-**DIRECTIVE STATUS CODES:**
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
 
-.. list-table::
- :class: rtems-table
+     * - ``RTEMS_SUCCESSFUL``
+       - timer canceled successfully
+     * - ``RTEMS_INVALID_ID``
+       - invalid timer id
 
- * - ``RTEMS_SUCCESSFUL``
-   - timer canceled successfully
- * - ``RTEMS_INVALID_ID``
-   - invalid timer id
+DESCRIPTION:
+    This directive cancels the timer id.  This timer will be reinitiated by the
+    next invocation of ``rtems_timer_reset``, ``rtems_timer_fire_after``, or
+    ``rtems_timer_fire_when`` with this id.
 
-**DESCRIPTION:**
+NOTES:
+    This directive will not cause the running task to be preempted.
 
-This directive cancels the timer id.  This timer will be reinitiated by the
-next invocation of ``rtems_timer_reset``, ``rtems_timer_fire_after``, or
-``rtems_timer_fire_when`` with this id.
+.. raw:: latex
 
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
+   \clearpage
 
 .. _rtems_timer_delete:
 
 TIMER_DELETE - Delete a timer
 -----------------------------
 .. index:: delete a timer
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_delete
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_delete(
-        rtems_id id
-    );
+CALLING SEQUENCE:
+    .. code-block:: c
 
-**DIRECTIVE STATUS CODES:**
+        rtems_status_code rtems_timer_delete(
+            rtems_id id
+        );
 
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
 
- * - ``RTEMS_SUCCESSFUL``
-   - timer deleted successfully
- * - ``RTEMS_INVALID_ID``
-   - invalid timer id
+     * - ``RTEMS_SUCCESSFUL``
+       - timer deleted successfully
+     * - ``RTEMS_INVALID_ID``
+       - invalid timer id
 
-**DESCRIPTION:**
+DESCRIPTION:
+    This directive deletes the timer specified by id.  If the timer is running,
+    it is automatically canceled.  The TMCB for the deleted timer is reclaimed
+    by RTEMS.
 
-This directive deletes the timer specified by id.  If the timer is running, it
-is automatically canceled.  The TMCB for the deleted timer is reclaimed by
-RTEMS.
+NOTES:
+    This directive will not cause the running task to be preempted.
 
-**NOTES:**
+    A timer can be deleted by a task other than the task which created the
+    timer.
 
-This directive will not cause the running task to be preempted.
+.. raw:: latex
 
-A timer can be deleted by a task other than the task which created the timer.
+   \clearpage
 
 .. _rtems_timer_fire_after:
 
 TIMER_FIRE_AFTER - Fire timer after interval
 --------------------------------------------
 .. index:: fire a timer after an interval
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_fire_after
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_fire_after(
-        rtems_id                           id,
-        rtems_interval                     ticks,
-        rtems_timer_service_routine_entry  routine,
-        void                              *user_data
-    );
+CALLING SEQUENCE:
+    .. code-block:: c
 
-**DIRECTIVE STATUS CODES:**
+        rtems_status_code rtems_timer_fire_after(
+            rtems_id                           id,
+            rtems_interval                     ticks,
+            rtems_timer_service_routine_entry  routine,
+            void                              *user_data
+        );
 
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
 
- * - ``RTEMS_SUCCESSFUL``
-   - timer initiated successfully
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``routine`` is NULL
- * - ``RTEMS_INVALID_ID``
-   - invalid timer id
- * - ``RTEMS_INVALID_NUMBER``
-   - invalid interval
+     * - ``RTEMS_SUCCESSFUL``
+       - timer initiated successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``routine`` is NULL
+     * - ``RTEMS_INVALID_ID``
+       - invalid timer id
+     * - ``RTEMS_INVALID_NUMBER``
+       - invalid interval
 
-**DESCRIPTION:**
+DESCRIPTION:
+    This directive initiates the timer specified by id.  If the timer is
+    running, it is automatically canceled before being initiated.  The timer is
+    scheduled to fire after an interval ticks clock ticks has passed.  When the
+    timer fires, the timer service routine routine will be invoked with the
+    argument user_data.
 
-This directive initiates the timer specified by id.  If the timer is running,
-it is automatically canceled before being initiated.  The timer is scheduled to
-fire after an interval ticks clock ticks has passed.  When the timer fires, the
-timer service routine routine will be invoked with the argument user_data.
+NOTES:
+    This directive will not cause the running task to be preempted.
 
-**NOTES:**
+.. raw:: latex
 
-This directive will not cause the running task to be preempted.
+   \clearpage
 
 .. _rtems_timer_fire_when:
 
 TIMER_FIRE_WHEN - Fire timer when specified
 -------------------------------------------
 .. index:: fire a timer at wall time
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_fire_when
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_fire_when(
-        rtems_id                           id,
-        rtems_time_of_day                 *wall_time,
-        rtems_timer_service_routine_entry  routine,
-        void                              *user_data
-    );
-
-**DIRECTIVE STATUS CODES:**
-
-.. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
-   - timer initiated successfully
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``routine`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``wall_time`` is NULL
- * - ``RTEMS_INVALID_ID``
-   - invalid timer id
- * - ``RTEMS_NOT_DEFINED``
-   - system date and time is not set
- * - ``RTEMS_INVALID_CLOCK``
-   - invalid time of day
-
-**DESCRIPTION:**
-
-This directive initiates the timer specified by id.  If the timer is running,
-it is automatically canceled before being initiated.  The timer is scheduled to
-fire at the time of day specified by wall_time.  When the timer fires, the
-timer service routine routine will be invoked with the argument user_data.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_timer_fire_when(
+            rtems_id                           id,
+            rtems_time_of_day                 *wall_time,
+            rtems_timer_service_routine_entry  routine,
+            void                              *user_data
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - timer initiated successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``routine`` is NULL
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``wall_time`` is NULL
+     * - ``RTEMS_INVALID_ID``
+       - invalid timer id
+     * - ``RTEMS_NOT_DEFINED``
+       - system date and time is not set
+     * - ``RTEMS_INVALID_CLOCK``
+       - invalid time of day
+
+DESCRIPTION:
+    This directive initiates the timer specified by id.  If the timer is
+    running, it is automatically canceled before being initiated.  The timer is
+    scheduled to fire at the time of day specified by wall_time.  When the
+    timer fires, the timer service routine routine will be invoked with the
+    argument user_data.
+
+NOTES:
+    This directive will not cause the running task to be preempted.
+
+.. raw:: latex
+
+   \clearpage
 
 .. _rtems_timer_initiate_server:
 
 TIMER_INITIATE_SERVER - Initiate server for task-based timers
 -------------------------------------------------------------
 .. index:: initiate the Timer Server
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_initiate_server
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_initiate_server(
-        uint32_t         priority,
-        uint32_t         stack_size,
-        rtems_attribute  attribute_set
-    );
+CALLING SEQUENCE:
+    .. code-block:: c
 
-**DIRECTIVE STATUS CODES:**
+        rtems_status_code rtems_timer_initiate_server(
+            uint32_t         priority,
+            uint32_t         stack_size,
+            rtems_attribute  attribute_set
+        );
 
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
 
- * - ``RTEMS_SUCCESSFUL``
-   - Timer Server initiated successfully
- * - ``RTEMS_TOO_MANY``
-   - too many tasks created
+     * - ``RTEMS_SUCCESSFUL``
+       - Timer Server initiated successfully
+     * - ``RTEMS_TOO_MANY``
+       - too many tasks created
 
-**DESCRIPTION:**
+DESCRIPTION:
+    This directive initiates the Timer Server task.  This task is responsible
+    for executing all timers initiated via the
+    ``rtems_timer_server_fire_after`` or ``rtems_timer_server_fire_when``
+    directives.
 
-This directive initiates the Timer Server task.  This task is responsible for
-executing all timers initiated via the ``rtems_timer_server_fire_after`` or
-``rtems_timer_server_fire_when`` directives.
+NOTES:
+    This directive could cause the calling task to be preempted.
 
-**NOTES:**
+    The Timer Server task is created using the ``rtems_task_create`` service
+    and must be accounted for when configuring the system.
 
-This directive could cause the calling task to be preempted.
+    Even through this directive invokes the ``rtems_task_create`` and
+    ``rtems_task_start`` directives, it should only fail due to resource
+    allocation problems.
 
-The Timer Server task is created using the ``rtems_task_create`` service and
-must be accounted for when configuring the system.
+.. raw:: latex
 
-Even through this directive invokes the ``rtems_task_create`` and
-``rtems_task_start`` directives, it should only fail due to resource allocation
-problems.
+   \clearpage
 
 .. _rtems_timer_server_fire_after:
 
 TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval
 --------------------------------------------------------------
 .. index:: fire task-based a timer after an interval
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_server_fire_after
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_server_fire_after(
-        rtems_id                           id,
-        rtems_interval                     ticks,
-        rtems_timer_service_routine_entry  routine,
-        void                              *user_data
-    );
+CALLING SEQUENCE:
+    .. code-block:: c
 
-**DIRECTIVE STATUS CODES:**
+        rtems_status_code rtems_timer_server_fire_after(
+            rtems_id                           id,
+            rtems_interval                     ticks,
+            rtems_timer_service_routine_entry  routine,
+            void                              *user_data
+        );
 
-.. list-table::
- :class: rtems-table
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
 
- * - ``RTEMS_SUCCESSFUL``
-   - timer initiated successfully
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``routine`` is NULL
- * - ``RTEMS_INVALID_ID``
-   - invalid timer id
- * - ``RTEMS_INVALID_NUMBER``
-   - invalid interval
- * - ``RTEMS_INCORRECT_STATE``
-   - Timer Server not initiated
+     * - ``RTEMS_SUCCESSFUL``
+       - timer initiated successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``routine`` is NULL
+     * - ``RTEMS_INVALID_ID``
+       - invalid timer id
+     * - ``RTEMS_INVALID_NUMBER``
+       - invalid interval
+     * - ``RTEMS_INCORRECT_STATE``
+       - Timer Server not initiated
 
-**DESCRIPTION:**
+DESCRIPTION:
+    This directive initiates the timer specified by id and specifies that when
+    it fires it will be executed by the Timer Server.
 
-This directive initiates the timer specified by id and specifies that when it
-fires it will be executed by the Timer Server.
+    If the timer is running, it is automatically canceled before being
+    initiated.  The timer is scheduled to fire after an interval ticks clock
+    ticks has passed.  When the timer fires, the timer service routine routine
+    will be invoked with the argument user_data.
 
-If the timer is running, it is automatically canceled before being initiated.
-The timer is scheduled to fire after an interval ticks clock ticks has passed.
-When the timer fires, the timer service routine routine will be invoked with
-the argument user_data.
+NOTES:
+    This directive will not cause the running task to be preempted.
 
-**NOTES:**
+.. raw:: latex
 
-This directive will not cause the running task to be preempted.
+   \clearpage
 
 .. _rtems_timer_server_fire_when:
 
 TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified
 -------------------------------------------------------------
 .. index:: fire a task-based timer at wall time
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_server_fire_when
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_server_fire_when(
-        rtems_id                           id,
-        rtems_time_of_day                 *wall_time,
-        rtems_timer_service_routine_entry  routine,
-        void                              *user_data
-    );
-
-**DIRECTIVE STATUS CODES:**
-
-.. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
-   - timer initiated successfully
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``routine`` is NULL
- * - ``RTEMS_INVALID_ADDRESS``
-   - ``wall_time`` is NULL
- * - ``RTEMS_INVALID_ID``
-   - invalid timer id
- * - ``RTEMS_NOT_DEFINED``
-   - system date and time is not set
- * - ``RTEMS_INVALID_CLOCK``
-   - invalid time of day
- * - ``RTEMS_INCORRECT_STATE``
-   - Timer Server not initiated
-
-**DESCRIPTION:**
-
-This directive initiates the timer specified by id and specifies that when it
-fires it will be executed by the Timer Server.
-
-If the timer is running, it is automatically canceled before being initiated.
-The timer is scheduled to fire at the time of day specified by wall_time.  When
-the timer fires, the timer service routine routine will be invoked with the
-argument user_data.
-
-**NOTES:**
-
-This directive will not cause the running task to be preempted.
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_timer_server_fire_when(
+            rtems_id                           id,
+            rtems_time_of_day                 *wall_time,
+            rtems_timer_service_routine_entry  routine,
+            void                              *user_data
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - timer initiated successfully
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``routine`` is NULL
+     * - ``RTEMS_INVALID_ADDRESS``
+       - ``wall_time`` is NULL
+     * - ``RTEMS_INVALID_ID``
+       - invalid timer id
+     * - ``RTEMS_NOT_DEFINED``
+       - system date and time is not set
+     * - ``RTEMS_INVALID_CLOCK``
+       - invalid time of day
+     * - ``RTEMS_INCORRECT_STATE``
+       - Timer Server not initiated
+
+DESCRIPTION:
+    This directive initiates the timer specified by id and specifies that when
+    it fires it will be executed by the Timer Server.
+
+    If the timer is running, it is automatically canceled before being
+    initiated.  The timer is scheduled to fire at the time of day specified by
+    wall_time.  When the timer fires, the timer service routine routine will be
+    invoked with the argument user_data.
+
+NOTES:
+    This directive will not cause the running task to be preempted.
+
+.. raw:: latex
+
+   \clearpage
 
 .. _rtems_timer_reset:
 
 TIMER_RESET - Reset an interval timer
 -------------------------------------
 .. index:: reset a timer
-
-**CALLING SEQUENCE:**
-
 .. index:: rtems_timer_reset
 
-.. code-block:: c
-
-    rtems_status_code rtems_timer_reset(
-        rtems_id   id
-    );
-
-**DIRECTIVE STATUS CODES:**
-
-.. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
-   - timer reset successfully
- * - ``RTEMS_INVALID_ID``
-   - invalid timer id
- * - ``RTEMS_NOT_DEFINED``
-   - attempted to reset a when or newly created timer
-
-**DESCRIPTION:**
-
-This directive resets the timer associated with id.  This timer must have been
-previously initiated with either the ``rtems_timer_fire_after`` or
-``rtems_timer_server_fire_after`` directive.  If active the timer is canceled,
-after which the timer is reinitiated using the same interval and timer service
-routine which the original ``rtems_timer_fire_after`` or
-``rtems_timer_server_fire_after`` directive used.
-
-**NOTES:**
-
-If the timer has not been used or the last usage of this timer was by a
-``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then
-the ``RTEMS_NOT_DEFINED`` error is returned.
-
-Restarting a cancelled after timer results in the timer being reinitiated with
-its previous timer service routine and interval.
-
-This directive will not cause the running task to be preempted.
+CALLING SEQUENCE:
+    .. code-block:: c
+
+        rtems_status_code rtems_timer_reset(
+            rtems_id   id
+        );
+
+DIRECTIVE STATUS CODES:
+    .. list-table::
+     :class: rtems-table
+
+     * - ``RTEMS_SUCCESSFUL``
+       - timer reset successfully
+     * - ``RTEMS_INVALID_ID``
+       - invalid timer id
+     * - ``RTEMS_NOT_DEFINED``
+       - attempted to reset a when or newly created timer
+
+DESCRIPTION:
+    This directive resets the timer associated with id.  This timer must have
+    been previously initiated with either the ``rtems_timer_fire_after`` or
+    ``rtems_timer_server_fire_after`` directive.  If active the timer is
+    canceled, after which the timer is reinitiated using the same interval and
+    timer service routine which the original ``rtems_timer_fire_after`` or
+    ``rtems_timer_server_fire_after`` directive used.
+
+NOTES:
+    If the timer has not been used or the last usage of this timer was by a
+    ``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive,
+    then the ``RTEMS_NOT_DEFINED`` error is returned.
+
+    Restarting a cancelled after timer results in the timer being reinitiated
+    with its previous timer service routine and interval.
+
+    This directive will not cause the running task to be preempted.