[pulseaudio-discuss] [PATCH] manpage: reformat overlong lines; try to document environment variables

[Peter Meerwald]

this patch adds documentation for the following envirnoment variables used
by PulseAudio:

PULSE_COOKIE
PULSE_PROP_...
PULSE_PROP_OVERRIDE_...
PULSE_RUNTIME_PATH
PULSE_STATE_PATH
PULSE_CONFIG_PATH
PULSE_LATENCY_MSEC
PULSE_NO_SIMD
VALGRIND

the list is probably not complete; some env. vars. should probably not be
documented (?) but rather be dropped

there is currently no section in pulseaudio.1 documenting env. vars. relating
to the daemon, only client-side env. vars. are described -- this might not be
the best place to put this information

which env. var. relate to
daemon?
client?
both?

PULSE_PASSED_FD has been omitted
---
 man/pulseaudio.1.xml.in |   90 ++++++++++++++++++++++++++++++++++++++---------
 1 files changed, 73 insertions(+), 17 deletions(-)

diff --git a/man/pulseaudio.1.xml.in b/man/pulseaudio.1.xml.in
index ab5fa05..b9c2c31 100644
--- a/man/pulseaudio.1.xml.in
+++ b/man/pulseaudio.1.xml.in
@@ -37,7 +37,8 @@ USA.
   </synopsis>
 
   <description>
-    <p>PulseAudio is a networked low-latency sound server for Linux, POSIX and Windows systems.</p>
+    <p>PulseAudio is a networked low-latency sound server for Linux, POSIX
+    and Windows systems.</p>
   </description>
 
   <options>
@@ -243,7 +244,8 @@ USA.
     <option>
       <p><opt>--use-pid-file</opt><arg>[=BOOL]</arg></p>
 
-      <optdesc><p>Create a PID file. If this options is disabled it is possible to run multiple sound servers per user.</p></optdesc>
+      <optdesc><p>Create a PID file. If this options is disabled it is
+      possible to run multiple sound servers per user.</p></optdesc>
     </option>
 
     <option>
@@ -360,11 +362,11 @@ USA.
     PulseAudio is running as a user daemon this group has no
     meaning.</p>
 
-    <p>User <arg>pulse</arg>, group <arg>pulse</arg>: if PulseAudio is running as a system
-    daemon (see <opt>--system</opt> above) and is started as root the
-    daemon will drop priviliges and become a normal user process using
-    this user and group. If PulseAudio is running as a user daemon
-    this user and group has no meaning.</p>
+    <p>User <arg>pulse</arg>, group <arg>pulse</arg>: if PulseAudio is
+    running as a system daemon (see <opt>--system</opt> above) and is
+    started as root the daemon will drop priviliges and become a normal
+    user process using this user and group. If PulseAudio is running as a
+    user daemon this user and group has no meaning.</p>
   </section>
 
   <section name="Real-time and high-priority scheduling">
@@ -394,7 +396,8 @@ USA.
     (see <manref name="setrlimit" section="2"/> for more information)
     can be used to allow specific users to acquire real-time
     scheduling. This can be configured in
-    <file>/etc/security/limits.conf</file>, a resource limit of 9 is recommended.</p>
+    <file>/etc/security/limits.conf</file>, a resource limit of 9 is
+    recommended.</p>
 
     <p>Alternatively, the SUID root bit can be set for the PulseAudio
     binary. Then, the daemon will drop root priviliges immediately on
@@ -421,29 +424,82 @@ USA.
   <section name="Environment variables">
 
     <p>The PulseAudio client libraries check for the existance of the
-    following environment variables and change their local configuration accordingly:</p>
+    following environment variables and change their local configuration
+    accordingly:</p>
 
-    <p><arg>$PULSE_SERVER</arg>: the server string specifying the server to connect to when a client asks for a sound server connection and doesn't explicitly ask for a specific server.</p>
+    <p><arg>$PULSE_SERVER</arg>: the server string specifying the server
+    to connect to when a client asks for a sound server connection and
+    doesn't explicitly ask for a specific server.</p>
 
-    <p><arg>$PULSE_SINK</arg>: the symbolic name of the sink to connect to when a client creates a playback stream and doesn't explicitly ask for a specific sink.</p>
+    <p><arg>$PULSE_SINK</arg>: the symbolic name of the sink to connect to
+    when a client creates a playback stream and doesn't explicitly ask for
+    a specific sink.</p>
 
-    <p><arg>$PULSE_SOURCE</arg>: the symbolic name of the source to connect to when a client creates a record stream and doesn't explicitly ask for a specific source.</p>
+    <p><arg>$PULSE_SOURCE</arg>: the symbolic name of the source to connect
+    to when a client creates a record stream and doesn't explicitly ask for
+    a specific source.</p>
 
-    <p><arg>$PULSE_BINARY</arg>: path of PulseAudio executable to run when server auto-spawning is used.</p>
+    <p><arg>$PULSE_BINARY</arg>: path of PulseAudio executable to run when
+    server auto-spawning is used.</p>
 
-    <p><arg>$PULSE_CLIENTCONFIG</arg>: path of file that shall be read instead of <file>client.conf</file> (see above) for client configuration.</p>
+    <p><arg>$PULSE_CLIENTCONFIG</arg>: path of file that shall be read
+    instead of <file>client.conf</file> (see above) for client
+    configuration.</p>
 
-    <p>These environment settings take precedence -- if set -- over the configuration settings from <file>client.conf</file> (see above).</p>
+    <p><arg>$PULSE_COOKIE</arg>: path of PulseAudio authentication cookie
+    file.</p>
+
+    <p><arg>$PULSE_PROP_...</arg>: allows to set properties for PulseAudio
+    clients. These properties can be used for various purposes such as
+    user interface enhancements or making policy decision (e.g. route
+    'phone' streams to a particular device). See
+    <url href="http://pulseaudio.org/wiki/ApplicationProperties"/> for
+    details. For example, <arg>PULSE_PROP_media.role=phone</arg> indicates
+    that the media stream is phone data (i.e. VoIP speech audio);
+    <arg>PULSE_PROP_application.name="Foobar Music Player"</arg> sets the
+    application's name to be displayed in e.g. a mixer application.</p>
+
+    <p><arg>$PULSE_PROP_OVERRIDE_...</arg>: allows to override properties
+    set by a PulseAudio client program. </p>
+
+    <p><arg>$PULSE_RUNTIME_PATH</arg>: path of runtime directory that shall
+    contain dynamic data that needs not be kept across reboots and is
+    usually private to the user, except in system mode where it might be
+    accessible by other users, too.</p>
+
+    <p><arg>$PULSE_STATE_PATH</arg>: path to directory containing private,
+    dynamic per-user data that should be kept across reboots.</p>
+
+    <p><arg>$PULSE_CONFIG_PATH</arg>: path to directory containing client
+    configuration.</p>
+
+    <p><arg>$PULSE_LATENCY_MSEC</arg>: allows to override the target
+    length of the playback buffer and length of a recording fragment in
+    milliseconds.</p>
+
+    <p><arg>$PULSE_NO_SIMD</arg>: if defined disables optimized code paths
+    specific to certain CPU extensions (e.g. Intel SSE or ARM NEON).</p>
+
+    <p><arg>$VALGRIND</arg>: if defined and PulseAudio is compiled with
+    Valgrind support, memory is properly freed on exit to suppress
+    Valgrind warnings (for debugging purposes).</p>
+
+    <p>These environment settings take precedence -- if set -- over the
+    configuration settings from <file>client.conf</file> (see above).</p>
 
   </section>
 
   <section name="Authors">
-    <p>The PulseAudio Developers &lt;@PACKAGE_BUGREPORT@&gt;; PulseAudio is available from <url href="@PACKAGE_URL@"/></p>
+    <p>The PulseAudio Developers &lt;@PACKAGE_BUGREPORT@&gt;; PulseAudio
+    is available from <url href="@PACKAGE_URL@"/></p>
   </section>
 
   <section name="See also">
     <p>
-      <manref name="pulse-daemon.conf" section="5"/>, <manref name="default.pa" section="5"/>, <manref name="pulse-client.conf" section="5"/>, <manref name="pacmd" section="1"/>
+      <manref name="pulse-daemon.conf" section="5"/>,
+      <manref name="default.pa" section="5"/>,
+      <manref name="pulse-client.conf" section="5"/>,
+      <manref name="pacmd" section="1"/>
     </p>
   </section>
 
-- 
1.7.8.2