Merge pull request #2373 from keszybz/man-api-build-3

Man page grammar and build tweaks v3

4 files changed, 119 insertions, 123 deletions

diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml
index eeb406ba5b..c3749164cd 100644
--- a/man/sd_event_add_io.xml
+++ b/man/sd_event_add_io.xml
@@ -120,36 +120,35 @@
     returned in the <parameter>source</parameter> parameter. The
     <parameter>fd</parameter> parameter takes the UNIX file descriptor
     to watch, which may refer to a socket, a FIFO, a message queue, a
-    serial connection, a character device or any other file descriptor
-    compatible with Linux <citerefentry
-    project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
-    <parameter>events</parameter> parameter takes a bit mask of I/O
-    events to watch the file descriptor for, a combination of the
-    following event flags: <constant>EPOLLIN</constant>,
-    <constant>EPOLLOUT</constant>, <constant>EPOLLRDHUP</constant>,
-    <constant>EPOLLPRI</constant> and <constant>EPOLLET</constant>,
-    see <citerefentry
-    project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    serial connection, a character device, or any other file descriptor
+    compatible with Linux
+    <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+    <parameter>events</parameter> parameter takes a bit mask of events
+    to watch for, a combination of the following event flags:
+    <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
+    <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>,
+    and <constant>EPOLLET</constant>, see
+    <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     for details. The <parameter>handler</parameter> shall reference a
-    function to call when the I/O event source is triggered. The
-    handler function will be passed the
-    <parameter>userdata</parameter> pointer, which may be chosen
-    freely by the caller. The handler will also be passed the file
-    descriptor the event was seen on as well as the actual event flags
-    seen. It's generally a subset of the events watched, however may
-    additionally have <constant>EPOLLERR</constant> and
-    <constant>EPOLLHUP</constant> set.</para>
-
-    <para>By default, the I/O event source will stay enabled
+    function to call when the event source is triggered. The
+    <parameter>userdata</parameter> pointer will be passed to the
+    handler function, and may be chosen freely by the caller. The
+    handler will also be passed the file descriptor the event was seen
+    on, as well as the actual event flags. It's generally a subset of
+    the events watched, however may additionally include
+    <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>.
+    </para>
+
+    <para>By default, an event source will stay enabled
     continuously (<constant>SD_EVENT_ON</constant>), but this may be
     changed with
     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     If the handler function returns a negative error code, it will be
     disabled after the invocation, even if the
     <constant>SD_EVENT_ON</constant> mode was requested before. Note
-    that an I/O event source set to <constant>SD_EVENT_ON</constant> will
-    fire continuously unless data is read or written to the file
-    descriptor in order to reset the mask of events seen.
+    that an event source set to <constant>SD_EVENT_ON</constant> will
+    fire continuously unless data is read from or written to the file
+    descriptor to reset the mask of events seen.
     </para>
 
     <para>Setting the I/O event mask to watch for to 0 does not mean
@@ -164,16 +163,17 @@
     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     but note that the event source is only removed from the event loop
     when all references to the event source are dropped. To make sure
-    an event source does not fire anymore, even when there's still a
-    reference to it kept, consider setting the event source to
-    <constant>SD_EVENT_OFF</constant> with
-    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    an event source does not fire anymore, even if it is still referenced,
+    disable the event source using
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    with <constant>SD_EVENT_OFF</constant>.</para>
 
     <para>If the second parameter of
-    <function>sd_event_add_io()</function> is passed as NULL no
-    reference to the event source object is returned. In this case the
-    event source is considered "floating", and will be destroyed
-    implicitly when the event loop itself is destroyed.</para>
+    <function>sd_event_add_io()</function> is
+    <constant>NULL</constant> no reference to the event source object
+    is returned. In this case the event source is considered
+    "floating", and will be destroyed implicitly when the event loop
+    itself is destroyed.</para>
 
     <para>It is recommended to use
     <function>sd_event_add_io()</function> only in conjunction with
@@ -181,24 +181,24 @@
     ensure that all I/O operations from invoked handlers are properly
     asynchronous and non-blocking. Using file descriptors without
     <constant>O_NONBLOCK</constant> might result in unexpected
-    starving of other event sources. See <citerefentry
-    project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    starvation of other event sources. See
+    <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
 
     <para><function>sd_event_source_get_io_events()</function> retrieves
-    the configured I/O event mask to watch of an I/O event source created
+    the configured mask of watched I/O events of an event source created
     previously with <function>sd_event_add_io()</function>. It takes
     the event source object and a pointer to a variable to store the
-    event mask in.</para>
+    mask in.</para>
 
-    <para><function>sd_event_source_set_io_events()</function> changes the
-    configured I/O event mask to watch of an I/O event source created previously
-    with <function>sd_event_add_io()</function>. It takes the event
-    source object and the new event mask to set.</para>
+    <para><function>sd_event_source_set_io_events()</function>
+    configures the mask of watched I/O events of an event source created
+    previously with <function>sd_event_add_io()</function>. It takes the
+    event source object and the new event mask.</para>
 
     <para><function>sd_event_source_get_io_revents()</function>
     retrieves the I/O event mask of currently seen but undispatched
-    events from an I/O event source created previously with
+    events from an event source created previously with
     <function>sd_event_add_io()</function>. It takes the event source
     object and a pointer to a variable to store the event mask
     in. When called from a handler function on the handler's event
@@ -214,15 +214,15 @@
     source types, the latter only to I/O event sources.</para>
 
     <para><function>sd_event_source_get_io_fd()</function> retrieves
-    the UNIX file descriptor of an I/O event source created previously
+    the UNIX file descriptor of an event source created previously
     with <function>sd_event_add_io()</function>. It takes the event
-    source object and returns the positive file descriptor in the return
-    value, or a negative error number on error (see below).</para>
+    source object and returns the non-negative file descriptor
+    or a negative error number on error (see below).</para>
 
     <para><function>sd_event_source_set_io_fd()</function>
     changes the UNIX file descriptor of an I/O event source created
     previously with <function>sd_event_add_io()</function>. It takes
-    the event source object and the new file descriptor to set.</para>
+    the event source object and the new file descriptor.</para>
   </refsect1>
 
   <refsect1>
@@ -230,13 +230,13 @@
 
     <para>On success, these functions return 0 or a positive
     integer. On failure, they return a negative errno-style error
-    code. </para>
+    code.</para>
   </refsect1>
 
   <refsect1>
     <title>Errors</title>
 
-    <para>Returned errors may indicate the following problems:</para>
+    <para>Returned values may indicate the following problems:</para>
 
     <variablelist>
       <varlistentry>
diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml
index a2aabd3c1a..e98f1d2682 100644
--- a/man/sd_event_add_signal.xml
+++ b/man/sd_event_add_signal.xml
@@ -123,24 +123,23 @@
     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     but note that the event source is only removed from the event loop
     when all references to the event source are dropped. To make sure
-    an event source does not fire anymore, even when there's still a
-    reference to it kept, consider setting the event source to
-    <constant>SD_EVENT_OFF</constant> with
-    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    an event source does not fire anymore, even if it is still referenced,
+    disable the event source using
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    with <constant>SD_EVENT_OFF</constant>.</para>
 
     <para>If the second parameter of
-    <function>sd_event_add_signal()</function> is passed as NULL no
-    reference to the event source object is returned. In this case the
-    event source is considered "floating", and will be destroyed
-    implicitly when the event loop itself is destroyed.</para>
-
-    <para><function>sd_event_source_get_signal()</function> retrieves
-    the configured UNIX process signal number of a signal event source
-    created previously with
-    <function>sd_event_add_signal()</function>. It takes the event
-    source object as the <parameter>source</parameter>
+    <function>sd_event_add_signal()</function> is
+    <constant>NULL</constant> no reference to the event source object
+    is returned. In this case the event source is considered
+    "floating", and will be destroyed implicitly when the event loop
+    itself is destroyed.</para>
+
+    <para><function>sd_event_source_get_signal()</function> returns
+    the configured signal number of an event source created previously
+    with <function>sd_event_add_signal()</function>. It takes the
+    event source object as the <parameter>source</parameter>
     parameter.</para>
-
   </refsect1>
 
   <refsect1>
@@ -148,7 +147,7 @@
 
     <para>On success, these functions return 0 or a positive
     integer. On failure, they return a negative errno-style error
-    code. </para>
+    code.</para>
   </refsect1>
 
   <refsect1>
@@ -167,7 +166,6 @@
         <term><constant>-EINVAL</constant></term>
 
         <listitem><para>An invalid argument has been passed.</para></listitem>
-
       </varlistentry>
 
       <varlistentry>
@@ -175,21 +173,18 @@
 
         <listitem><para>A handler is already installed for this
         signal or the signal was not blocked previously.</para></listitem>
-
       </varlistentry>
 
       <varlistentry>
         <term><constant>-ESTALE</constant></term>
 
         <listitem><para>The event loop is already terminated.</para></listitem>
-
       </varlistentry>
 
       <varlistentry>
         <term><constant>-ECHILD</constant></term>
 
         <listitem><para>The event loop has been created in a different process.</para></listitem>
-
       </varlistentry>
 
       <varlistentry>
diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index b58d740bd8..142fa80f8f 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -122,31 +122,31 @@
     clock identifier, one of <constant>CLOCK_REALTIME</constant>,
     <constant>CLOCK_MONOTONIC</constant>,
     <constant>CLOCK_BOOTTIME</constant>,
-    <constant>CLOCK_REALTIME_ALARM</constant> or
+    <constant>CLOCK_REALTIME_ALARM</constant>, or
     <constant>CLOCK_BOOTTIME_ALARM</constant>. See
     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     for details regarding the various types of clocks. The
-    <parameter>usec</parameter> parameter takes a time value in
-    microseconds (µs), relative to the clock's epoch, specifying when
-    the timer shall elapse the earliest. If a time that already lies
-    in the past is specified (including 0), the timer source is
-    dispatched immediately in the next event loop iterations. The
-    <parameter>accuracy</parameter> parameter takes an additional
-    accuracy value in µs specifying a time the timer event may be
-    delayed. Specify 0 for selecting the default accuracy
-    (250ms). Specify 1µs for most accurate timers. Consider specifying
-    60000000µs or larger (1min) for long-running events that may be
+    <parameter>usec</parameter> parameter specifies the earliest time,
+    in microseconds (µs), relative to the clock's epoch, when
+    the timer shall be triggered. If a time already in the past is
+    specified (including <constant>0</constant>), this timer source
+    "fires" immediately and is ready to be dispatched. The
+    <parameter>accuracy</parameter> parameter specifies an additional
+    accuracy value in µs specifying how much the timer event may be
+    delayed. Use <constant>0</constant> to select the default accuracy
+    (250ms). Use 1µs for maximum accuracy. Consider specifying
+    60000000µs (1min) or larger for long-running events that may be
     delayed substantially. Picking higher accuracy values allows the
-    system to coalesce timer events more aggressively, thus improving
+    system to coalesce timer events more aggressively, improving
     power efficiency. The <parameter>handler</parameter> parameter
     shall reference a function to call when the timer elapses. The
     handler function will be passed the
     <parameter>userdata</parameter> pointer, which may be chosen
     freely by the caller. The handler is also passed the configured
-    time it was triggered, however it might actually have been called
-    at a slightly later time, subject to the specified accuracy value,
+    trigger time, even if it is actually called
+    slightly later, subject to the specified accuracy value,
     the kernel timer slack (see
-    <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
+    <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>),
     and additional scheduling latencies. To query the actual time the
     handler was called use
     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
@@ -167,22 +167,24 @@
     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     but note that the event source is only removed from the event loop
     when all references to the event source are dropped. To make sure
-    an event source does not fire anymore, even when there's still a
-    reference to it kept, consider setting the event source to
-    <constant>SD_EVENT_OFF</constant> with
-    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    an event source does not fire anymore, even if it is still referenced,
+    disable the event source using
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    with <constant>SD_EVENT_OFF</constant>.</para>
 
     <para>If the second parameter of
-    <function>sd_event_add_time()</function> is passed as NULL no
-    reference to the event source object is returned. In this case the
-    event source is considered "floating", and will be destroyed
-    implicitly when the event loop itself is destroyed.</para>
+    <function>sd_event_add_time()</function> is
+    <constant>NULL</constant> no reference to the event source object
+    is returned. In this case the event source is considered
+    "floating", and will be destroyed implicitly when the event loop
+    itself is destroyed.</para>
 
     <para>If the <parameter>handler</parameter> to
-    <function>sd_event_add_time()</function> is passed as NULL, and
-    the event source fires, this will be considered a request to exit
-    the event loop. In this case, the <parameter>userdata</parameter>
-    parameter, cast to an integer is used for the exit code passed to
+    <function>sd_event_add_time()</function> is
+    <constant>NULL</constant>, and the event source fires, this will
+    be considered a request to exit the event loop. In this case, the
+    <parameter>userdata</parameter> parameter, cast to an integer, is
+    used for the exit code passed to
     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
     <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
@@ -192,7 +194,7 @@
     <para>In order to set up relative timers (that is, relative to the
     current time), retrieve the current time via
     <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-    add the desired timespan to sleep to it, and pass the result as
+    add the desired timespan to it, and use the result as
     the <parameter>usec</parameter> parameter to
     <function>sd_event_add_time()</function>.</para>
 
@@ -212,30 +214,30 @@
     latency will keep accumulating on the timer.</para>
 
     <para><function>sd_event_source_get_time()</function> retrieves
-    the configured time value of a timer event source created
+    the configured time value of an event source created
     previously with <function>sd_event_add_time()</function>. It takes
     the event source object and a pointer to a variable to store the
-    time, relative to the selected clock's epoch, in µs in.</para>
+    time in, relative to the selected clock's epoch, in µs.</para>
 
     <para><function>sd_event_source_set_time()</function> changes the
-    configured time value of a timer event source created previously
-    with <function>sd_event_add_time()</function>. It takes the event
-    source object and a time relative to the selected clock's
-    epoch, in µs.</para>
+    time of an event source created previously with
+    <function>sd_event_add_time()</function>. It takes the event
+    source object and a time relative to the selected clock's epoch,
+    in µs.</para>
 
     <para><function>sd_event_source_get_time_accuracy()</function>
-    retrieves the configured accuracy value of a timer event source
+    retrieves the configured accuracy value of a event source
     created previously with <function>sd_event_add_time()</function>. It
     takes the event source object and a pointer to a variable to store
-    the accuracy in µs in.</para>
+    the accuracy in. The accuracy is specified in µs.</para>
 
     <para><function>sd_event_source_set_time_accuracy()</function>
     changes the configured accuracy of a timer event source created
     previously with <function>sd_event_add_time()</function>. It takes
-    the event source object and an accuracy, in µs.</para>
+    the event source object and accuracy, in µs.</para>
 
     <para><function>sd_event_source_get_time_clock()</function>
-    retrieves the configured clock of a timer event source created
+    retrieves the configured clock of a event source created
     previously with <function>sd_event_add_time()</function>. It takes
     the event source object and a pointer to a variable to store the
     clock identifier in.</para>
@@ -252,7 +254,7 @@
   <refsect1>
     <title>Errors</title>
 
-    <para>Returned errors may indicate the following problems:</para>
+    <para>Returned values may indicate the following problems:</para>
 
     <variablelist>
       <varlistentry>
diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml
index 6cec0446c8..2c83b0bcb5 100644
--- a/man/sd_event_now.xml
+++ b/man/sd_event_now.xml
@@ -65,45 +65,44 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_event_now()</function> returns the timestamp
-    the most recent event loop iteration began. This timestamp is
-    taken right after returning from the event sleep, and before
+    <para><function>sd_event_now()</function> returns the time when
+    the most recent event loop iteration began. A timestamp
+    is taken right after returning from the event sleep, and before
     dispatching any event sources. The <parameter>event</parameter>
-    parameter takes the even loop object to retrieve the timestamp
+    parameter specifies the event loop object to retrieve the timestamp
     from. The <parameter>clock</parameter> parameter specifies the clock to
     retrieve the timestamp for, and is one of
-    <constant>CLOCK_REALTIME</constant> (or its equivalent
+    <constant>CLOCK_REALTIME</constant> (or equivalently
     <constant>CLOCK_REALTIME_ALARM</constant>),
-    <constant>CLOCK_MONOTONIC</constant> or
-    <constant>CLOCK_BOOTTIME</constant> (or its equivalent
-    <constant>CLOCK_BOOTTIME_ALARM</constant>), see <citerefentry
-    project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    <constant>CLOCK_MONOTONIC</constant>, or
+    <constant>CLOCK_BOOTTIME</constant> (or equivalently
+    <constant>CLOCK_BOOTTIME_ALARM</constant>), see
+    <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     for more information on the various clocks. The retrieved
     timestamp is stored in the <parameter>usec</parameter> parameter,
     in µs since the clock's epoch. If this function is invoked before
-    the first event loop iteration the current time is returned, as
+    the first event loop iteration, the current time is returned, as
     reported by <function>clock_gettime()</function>. To distinguish
     this case from a regular invocation the return value will be
-    positive non-zero in this case, while it is zero when the returned
-    timestamp refers to the actual event loop iteration.</para>
+    positive, and zero when the returned timestamp refers to an actual
+    event loop iteration.</para>
   </refsect1>
 
   <refsect1>
     <title>Return Value</title>
 
     <para>If the first event loop iteration has not run yet
-    <function>sd_event_now()</function> returns the requested
-    timestamp in <parameter>usec</parameter> and returns a positive,
-    non-zero return value. Otherwise, on success it will return the
-    iteration's timestamp in <parameter>usec</parameter> and 0 as
-    return value. On failure, the call returns a negative errno-style
+    <function>sd_event_now()</function> writes current time to
+    <parameter>usec</parameter> and returns a positive return value.
+    Otherwise, it will write the requested timestamp to <parameter>usec</parameter>
+    and return 0. On failure, the call returns a negative errno-style
     error code.</para>
   </refsect1>
 
   <refsect1>
     <title>Errors</title>
 
-    <para>Returned errors may indicate the following problems:</para>
+    <para>Returned values may indicate the following problems:</para>
 
     <variablelist>
       <varlistentry>