data/mpd_sima.1.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <!--
   3
   4 `xsltproc -''-nonet \
   5           -''-param man.charmap.use.subset "0" \
   6           -''-param make.year.ranges "1" \
   7           -''-param make.single.year.ranges "1" \
   8           /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \
   9           manpage.xml'
  10
  11 A manual page <package>.<section> will be generated. You may view the
  12 manual page with: nroff -man <package>.<section> | less'. A typical entry
  13 in a Makefile or Makefile.am is:
  14
  15 DB2MAN = /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl
  16 XP     = xsltproc -''-nonet -''-param man.charmap.use.subset "0"
  17
  18 manpage.1: manpage.xml
  19         $(XP) $(DB2MAN) $<
  20
  21 The xsltproc binary is found in the xsltproc package. The XSL files are in
  22 docbook-xsl. A description of the parameters you can use can be found in the
  23 docbook-xsl-doc-* packages. Please remember that if you create the nroff
  24 version in one of the debian/rules file targets (such as build), you will need
  25 to include xsltproc and docbook-xsl in your Build-Depends control field.
  26 Alternatively use the xmlto command/package. That will also automatically
  27 pull in xsltproc and docbook-xsl.
  28
  29 Notes for using docbook2x: docbook2x-man does not automatically create the
  30 AUTHOR(S) and COPYRIGHT sections. In this case, please add them manually as
  31 <refsect1> ... </refsect1>.
  32
  33 To disable the automatic creation of the AUTHOR(S) and COPYRIGHT sections
  34 read /usr/share/doc/docbook-xsl/doc/manpages/authors.html. This file can be
  35 found in the docbook-xsl-doc-html package.
  36
  37 Validation can be done using: `xmllint -''-noout -''-valid manpage.xml`
  38
  39 General documentation about man-pages and man-page-formatting:
  40 man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
  41
  42 -->
  43 <!DOCTYPE refentry [
  44
  45   <!ENTITY dhsection   "1">
  46   <!ENTITY dhpackage "mpd-sima">
  47   <!ENTITY dhutils "mpd-sima">
  48
  49 ]>
  50
  51 <refentry xmlns="http://docbook.org/ns/docbook"
  52           xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
  53   <xi:include href="info.xml" />
  54   <refmeta>
  55       <refentrytitle>&dhutils;</refentrytitle>
  56       <manvolnum>&dhsection;</manvolnum>
  57   </refmeta>
  58   <refnamediv>
  59     <refname>&dhpackage;</refname>
  60     <refpurpose>&dhpackage; will try to maintain some titles ahead in your play list following different policies.</refpurpose>
  61   </refnamediv>
  62   <refsynopsisdiv>
  63     <cmdsynopsis>
  64       <command>&dhpackage;</command>
  65       <arg choice="opt"><option>--daemon</option></arg>
  66       <arg choice="opt"><option>--config=</option><replaceable class="option">conf_file</replaceable></arg>
  67       <arg choice="opt"><option>--var_dir=</option><replaceable class="option">var_directory</replaceable></arg>
  68       <arg choice="opt"><option>--pid=</option><replaceable class="option">pid_file</replaceable></arg>
  69       <arg choice="opt"><option>--log=</option><replaceable class="option">log_file</replaceable></arg>
  70       <arg choice="opt"><option>--log-level=</option><replaceable class="option">log_level</replaceable></arg>
  71       <arg choice="opt"><option>--host=</option><replaceable class="option">mpd_host</replaceable></arg>
  72       <arg choice="opt"><option>--mpd_port=</option><replaceable class="option">mpd_port</replaceable></arg>
  73     </cmdsynopsis>
  74     <cmdsynopsis>
  75       <command>&dhpackage;</command>
  76       <arg choice="opt"><option>--var_dir=</option><replaceable class="option">var_directory</replaceable></arg>
  77       <arg choice="opt"><option>--create-db></option></arg>
  78     </cmdsynopsis>
  79     <cmdsynopsis>
  80       <command>&dhpackage;</command>
  81       <!-- Normally the help and version options make the programs stop
  82            right after outputting the requested information. -->
  83       <group choice="opt">
  84         <arg choice="plain">
  85           <group choice="req">
  86             <arg choice="plain"><option>-h</option></arg>
  87             <arg choice="plain"><option>--help</option></arg>
  88           </group>
  89         </arg>
  90         <arg choice="plain"><option>--version</option></arg>
  91       </group>
  92     </cmdsynopsis>
  93   </refsynopsisdiv>
  94   <refsect1 id="description">
  95     <title>DESCRIPTION</title>
  96     <para>This manual page documents briefly the
  97       <command>&dhpackage;</command> commands.</para>
  98     <para>At start up default configuration is first overridden by user
  99         configuration in mpd_sima.cfg (see <xref linkend="files"/>) and finally
 100         command lines options are honored. For instance you can override
 101         default MPD_HOST set in defaults (localhost) or in your configuration
 102         file with <command>-S my_mpd_server</command> option. For default
 103         configuration see <xref linkend="configuration"/>.</para>
 104   </refsect1>
 105     <refsect1 id="example">
 106         <title>EXAMPLE</title>
 107         <refsect2 id="daemon">
 108             <title>Launch as a system service (dæmon).</title>
 109             <para>Here follows an example on how to launch &dhpackage; as a service on your system, not attach to regular user configuration/database.</para>
 110             <para><command>&dhpackage; --daemon --conf=/etc/mpd_sima.cfg --var_dir=/var/cache/mpd-sima/ --pid=/run/mpd-sima.pid --log=/var/log/mpd-sima.log</command></para>
 111         </refsect2>
 112         <refsect2 id="user_land">
 113             <title>Launch in user land</title>
 114             <para>Launching &dhpackage; from/whithin your user account is easy, you can simply call <command>&dhpackage;</command> from your shell or one of the following command:</para>
 115             <para>Background execution (dæmonise), log in the specified file, save pid:</para>
 116             <para><command>&dhpackage; --daemon --pid=$HOME/var/run/mpd-sima.pid --log=$HOME/var/log/mpd-sima.log</command></para>
 117             <para>Foreground execution, connect <emphasis>my.mpd.server.org</emphasis>, log to std(out|err):</para>
 118             <para><command>&dhpackage; --host=my.mpd.server.org</command></para>
 119         </refsect2>
 120     </refsect1>
 121   <refsect1 id="options">
 122     <title>OPTIONS</title>
 123     <para>The program follows the usual GNU command line syntax,
 124       with long options starting with two dashes (`-').  A summary of
 125       options is included below.</para>
 126     <variablelist>
 127       <!-- Use the variablelist.term.separator and the
 128            variablelist.term.break.after parameters to
 129            control the term elements. -->
 130            <varlistentry> <!-- help -->
 131             <term><option>-h</option></term>
 132             <term><option>--help</option></term>
 133             <listitem>
 134                 <para>Print help and exit.</para>
 135             </listitem>
 136         </varlistentry>
 137         <varlistentry> <!-- version -->
 138             <term><option>--version</option></term>
 139             <listitem>
 140                 <para>Print version and exit.</para>
 141             </listitem>
 142         </varlistentry>
 143         <varlistentry> <!-- daemon -->
 144             <term><option>--daemon</option></term>
 145             <listitem>
 146                 <para>Start as a daemon. Log redirected to /dev/null, usually setting <option>--log</option> and <option>--pid</option> options in daemon mode are a good idea to monitor/stop the process.</para>
 147             </listitem>
 148         </varlistentry>
 149         <varlistentry> <!-- pid_file -->
 150             <term><option>-p <replaceable class="parameter">pid_file</replaceable></option></term>
 151             <term><option>--pid=<replaceable class="parameter">pid_file</replaceable></option></term>
 152             <listitem>
 153                 <para>Use the specific file <replaceable>pid_file</replaceable> to store pid to.<sbr />Default is not to store pid info.</para>
 154             </listitem>
 155         </varlistentry>
 156         <varlistentry> <!-- log -->
 157             <term><option>-l <replaceable class="parameter">log_file</replaceable></option></term>
 158             <term><option>--log=<replaceable class="parameter">log_file</replaceable></option></term>
 159             <listitem>
 160                 <para>Use the specific file <replaceable>log_file</replaceable> to log messages to.<sbr />Default is to log to stdout/stderr.</para>
 161             </listitem>
 162         </varlistentry>
 163         <varlistentry> <!-- log-level -->
 164             <term><option>-v <replaceable class="parameter">log_level</replaceable></option></term>
 165             <term><option>--log-level=<replaceable class="parameter">log_level</replaceable></option></term>
 166             <listitem>
 167                 <para>Verbosity in [debug,info,warning,error].<sbr />Default is to log info messages.</para>
 168             </listitem>
 169         </varlistentry>
 170         <varlistentry>
 171             <term><option>-c <replaceable class="parameter">conf_file</replaceable></option></term>
 172             <term><option>--config=<replaceable class="parameter">conf_file</replaceable></option></term>
 173             <listitem>
 174                 <para>Use the specific file <replaceable>conf_file</replaceable> to set up configuration instead of looking for the default user configuration file.<sbr />Default is to look for <envar>$XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg</envar>.  Concerning this file see also <xref linkend="files"/>.<sbr />Pay attention: Because you load a specific configuration file from command line interface <emphasis>does not mean</emphasis> it will override others options pass to mpd_sima. In other words launching with <option>-P 6666</option> will override port setting whatever the configuration file your using, default or command line specified.</para>
 175             </listitem>
 176         </varlistentry>
 177         <varlistentry> <!-- var_dir -->
 178             <term><option>--var_dir=<replaceable class="parameter">var_directory</replaceable></option></term>
 179             <listitem>
 180                 <para>Use the specific path <replaceable>var_directory</replaceable> to look for (or create) var files (ie. database) instead of looking at the default user data location.<sbr />Default is to look in <envar>$XDG_DATA_HOME/mpd_sima/</envar>.  Concerning <envar>$XDG_DATA_HOME</envar> see also <xref linkend="files"/></para>
 181             </listitem>
 182         </varlistentry>
 183         <varlistentry> <!-- create-db -->
 184             <term><option>--create-db</option></term>
 185             <listitem>
 186                 <para>Create the database and exit. Uses folder specified with <option>--var_dir</option> or default directory.<sbr />Default is to use <envar>$XDG_DATA_HOME/mpd_sima/</envar>.  Concerning <envar>$XDG_DATA_HOME</envar> see also <xref linkend="files"/></para>
 187             </listitem>
 188         </varlistentry>
 189         <varlistentry><!-- host -->
 190             <term><option>-S <replaceable class="parameter">mpd_host</replaceable></option></term>
 191             <term><option>--host=<replaceable class="parameter">mpd_host</replaceable></option></term>
 192             <listitem>
 193                 <para>Use the specific host <replaceable>mpd_host</replaceable> as MPD server.<sbr /><replaceable>mpd_host</replaceable> can be an <acronym>IP</acronym> or a fully qualified domain name as long as your system can resolve it. This overrides <envar>MPD_HOST</envar> environment variable.<sbr />Default is <emphasis>localhost</emphasis>.</para>
 194                 <para>See also <xref linkend="environment"/>.</para>
 195             </listitem>
 196         </varlistentry>
 197         <varlistentry><!-- port -->
 198             <term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
 199             <term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
 200             <listitem>
 201                 <para>Use the specific port number <replaceable>mpd_port</replaceable> on MPD server. This overrides <envar>MPD_PORT</envar> environment variable.<sbr />Default is <emphasis>6600</emphasis>.</para>
 202                 <para>See also <xref linkend="environment"/></para>
 203             </listitem>
 204         </varlistentry>
 205     </variablelist>
 206   </refsect1>
 207   <refsect1 id="files">
 208       <title>FILES</title>
 209       <variablelist>
 210           <varlistentry>
 211               <term><filename>${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg</filename></term>
 212               <!--
 213               <listitem>
 214               </listitem>
 215               <term><filename>${HOME}/.config/mpd_sima/mpd_sima.cfg</filename></term>
 216               -->
 217               <listitem>
 218                   <para>The per-user configuration file. Usually <envar>XDG_CONFIG_HOME</envar> is set to <filename>${HOME}/.config</filename>.</para>
 219               </listitem>
 220           </varlistentry>
 221           <varlistentry>
 222               <term><filename>${XDG_DATA_HOME}/mpd_sima/sima.db</filename></term>
 223               <!--
 224               <listitem>
 225               </listitem>
 226               <term><filename>${HOME}/.local/share/mpd_sima/history.pkl</filename></term>
 227               -->
 228               <listitem>
 229                   <para>SQLite database. Usually <envar>XDG_DATA_HOME</envar> is set to <filename>${HOME}/.local/share</filename>.</para>
 230               </listitem>
 231           </varlistentry>
 232       </variablelist>
 233   </refsect1>
 234   <refsect1 id="environment">
 235       <title>ENVIRONMENT</title>
 236       <variablelist>
 237           <varlistentry>
 238               <term><envar>MPD_HOST</envar>, <envar>MPD_PORT</envar></term>
 239               <listitem>
 240                   <para>&dhutils; will look for <envar>MPD_HOST</envar> and
 241                       <envar>MPD_PORT</envar> to override built-in configuration
 242                       (set to "localhost:6600").</para>
 243                   <para>&dhutils; expects <envar>MPD_HOST</envar> syntax as documented in mpc manual,
 244                       cf. <citerefentry><refentrytitle>mpc</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 245                       <sbr/>To use a password, provide a value of the form "password@host".
 246                   </para>
 247               </listitem>
 248           </varlistentry>
 249       </variablelist>
 250   </refsect1>
 251   <refsect1 id="configuration">
 252       <title>CONFIGURATION</title>
 253       <variablelist>
 254           <varlistentry>
 255               <term><filename>mpd_sima.cfg</filename></term>
 256               <listitem>
 257                   <para><filename>mpd_sima.cfg</filename> is read if present.
 258                       Otherwise built-in defaults are used. An example should be
 259                       provided in the tarball within
 260                       <filename>doc/examples/mpd_sima.cfg</filename>. On Debian
 261                       system please look in
 262                       <filename>/usr/share/doc/&dhpackage;</filename>.</para>
 263               </listitem>
 264           </varlistentry>
 265           <varlistentry>
 266               <term>DEFAULTS</term>
 267               <listitem>
 268                   <para>Default is to look for MPD server at localhost:6600 (or MPD_HOST/MPD_PORT env. var. if set).</para>
 269                         <para>The default behavior is to add one track,
 270                             this track is to be chosen among titles from
 271                             artists similar to the artist of the currently
 272                             played track. MPD_sima will add one track when the
 273                             play list is one track long.</para>
 274                   <para>To change these defaults, use the configuration file <filename>mpd_sima.cfg</filename></para>
 275               </listitem>
 276           </varlistentry>
 277       </variablelist>
 278   </refsect1>
 279   <xi:include href="feedback.xml" />
 280   <refsect1 id="see_also">
 281     <title>SEE ALSO</title>
 282     <!-- In alpabetical order. -->
 283     <para>
 284         <citerefentry>
 285             <refentrytitle>mpc</refentrytitle>
 286             <manvolnum>1</manvolnum>
 287             </citerefentry>, <citerefentry>
 288             <refentrytitle>mpd</refentrytitle>
 289             <manvolnum>1</manvolnum>
 290             </citerefentry>, <citerefentry>
 291             <refentrytitle>mpd-sima.cfg</refentrytitle>
 292             <manvolnum>5</manvolnum>
 293         </citerefentry>
 294     </para>
 295       <para>
 296           <filename>/usr/share/doc/mpd-sima/</filename>
 297       </para>
 298   </refsect1>
 299 </refentry>