data/man/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 the queue 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       <!-- Normally the help and version options make the programs stop
  77            right after outputting the requested information. -->
  78       <group choice="plain">
  79         <arg choice="req">
  80           <group choice="req">
  81             <arg choice="plain"><option>-h</option></arg>
  82             <arg choice="plain"><option>--help</option></arg>
  83           </group>
  84           <arg choice="plain"><option>--version</option></arg>
  85         </arg>
  86       </group>
  87     </cmdsynopsis>
  88     <cmdsynopsis>
  89       <command>&dhpackage;</command>
  90       <arg choice="plain">config-test</arg>
  91       <arg choice="opt"><option>--config=</option><replaceable class="option">conf_file</replaceable></arg>
  92     </cmdsynopsis>
  93     <cmdsynopsis>
  94       <command>&dhpackage;</command>
  95       <arg choice="plain">create-db</arg>
  96       <arg choice="opt"><option>--var-dir=</option><replaceable class="option">var_directory</replaceable></arg>
  97     </cmdsynopsis>
  98     <cmdsynopsis>
  99       <command>&dhpackage;</command>
 100       <arg choice="plain">generate-config</arg>
 101       <arg choice="opt"><option>…</option></arg>
 102     </cmdsynopsis>
 103     <cmdsynopsis>
 104       <command>&dhpackage;</command>
 105       <arg choice="plain">purge-history</arg>
 106       <arg choice="opt"><option>--var-dir=</option><replaceable class="option">var_directory</replaceable></arg>
 107     </cmdsynopsis>
 108   </refsynopsisdiv>
 109   <refsect1 id="description">
 110     <title>DESCRIPTION</title>
 111     <para>This manual page documents briefly the
 112       <command>&dhpackage;</command> commands.</para>
 113     <para>At start up default configuration is first overridden by user
 114         configuration in mpd_sima.cfg (see <xref linkend="files"/>) and finally
 115         command lines options are honored. For instance you can override
 116         default MPD_HOST set in defaults (localhost) or in your configuration
 117         file with <command>-S my_mpd_server</command> option. For default
 118         configuration see <xref linkend="configuration"/>. See also environment
 119         variables special case for MPD host and port in <xref linkend="environment"/>.
 120     </para>
 121   </refsect1>
 122     <refsect1 id="example">
 123         <title>EXAMPLE</title>
 124         <refsect2 id="daemon">
 125             <title>Launch as a system service (dæmon).</title>
 126             <para>Here follows an example on how to launch &dhpackage; as a service on your system, not attach to regular user configuration/database.</para>
 127             <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>
 128         </refsect2>
 129         <refsect2 id="user_land">
 130             <title>Launch in user land</title>
 131             <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>
 132             <para>Background execution (dæmonise), log in the specified file, save pid:</para>
 133             <para><command>&dhpackage; --daemon --pid=$HOME/var/run/mpd-sima.pid --log=$HOME/var/log/mpd-sima.log</command></para>
 134             <para>Foreground execution, connect <emphasis>my.mpd.server.org</emphasis>, log to std(out|err):</para>
 135             <para><command>&dhpackage; --host=my.mpd.server.org</command></para>
 136         </refsect2>
 137     </refsect1>
 138   <refsect1 id="options">
 139     <title>OPTIONS</title>
 140     <para>The program follows the usual GNU command line syntax,
 141       with long options starting with two dashes (`-').  A summary of
 142       options is included below.</para>
 143     <variablelist>
 144       <!-- Use the variablelist.term.separator and the
 145            variablelist.term.break.after parameters to
 146            control the term elements. -->
 147            <varlistentry> <!-- help -->
 148             <term><option>-h</option></term>
 149             <term><option>--help</option></term>
 150             <listitem>
 151                 <para>Print help and exit.</para>
 152             </listitem>
 153         </varlistentry>
 154         <varlistentry> <!-- version -->
 155             <term><option>--version</option></term>
 156             <listitem>
 157                 <para>Print version and exit.</para>
 158             </listitem>
 159         </varlistentry>
 160         <varlistentry> <!-- daemon -->
 161             <term><option>--daemon</option></term>
 162             <listitem>
 163                 <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>
 164             </listitem>
 165         </varlistentry>
 166         <varlistentry> <!-- pid_file -->
 167             <term><option>-p <replaceable class="parameter">pid_file</replaceable></option></term>
 168             <term><option>--pid=<replaceable class="parameter">pid_file</replaceable></option></term>
 169             <listitem>
 170                 <para>Use the specific file <replaceable>pid_file</replaceable> to store pid to.<sbr />Default is not to store pid info.</para>
 171             </listitem>
 172         </varlistentry>
 173         <varlistentry> <!-- log -->
 174             <term><option>-l <replaceable class="parameter">log_file</replaceable></option></term>
 175             <term><option>--log=<replaceable class="parameter">log_file</replaceable></option></term>
 176             <listitem>
 177                 <para>Use the specific file <replaceable>log_file</replaceable> to log messages to.<sbr />Default is to log to stdout/stderr.</para>
 178             </listitem>
 179         </varlistentry>
 180         <varlistentry> <!-- log-level -->
 181             <term><option>-v <replaceable class="parameter">log_level</replaceable></option></term>
 182             <term><option>--log-level=<replaceable class="parameter">log_level</replaceable></option></term>
 183             <listitem>
 184                 <para>Verbosity in [debug,info,warning,error].<sbr />Default is to log info messages.</para>
 185             </listitem>
 186         </varlistentry>
 187         <varlistentry><!-- config -->
 188             <term><option>-c <replaceable class="parameter">conf_file</replaceable></option></term>
 189             <term><option>--config=<replaceable class="parameter">conf_file</replaceable></option></term>
 190             <listitem>
 191                 <para>Use the specific file <replaceable>conf_file</replaceable> to set up
 192                     configuration instead of looking for the default user
 193                     configuration file.<sbr />Default is to look for
 194                     <envar>$XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg</envar>.<sbr />
 195                     CLI option overrides any equivalent mentioned in configuration file, ie. launching &dhutils; with '<option>--port</option>' CLI option will ignore port setting in configuration file.<sbr />
 196                     For more details on configuration file cf.
 197                     <citerefentry><refentrytitle>mpd_sima.cfg</refentrytitle>
 198                 <manvolnum>5</manvolnum></citerefentry>, see also <xref linkend="files"/>.<sbr />
 199                    </para>
 200             </listitem>
 201         </varlistentry>
 202         <varlistentry> <!-- var-dir -->
 203             <term><option>--var-dir=<replaceable class="parameter">var_directory</replaceable></option></term>
 204             <listitem>
 205                 <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>
 206             </listitem>
 207         </varlistentry>
 208         <varlistentry><!-- host -->
 209             <term><option>-S <replaceable class="parameter">mpd_host</replaceable></option></term>
 210             <term><option>--host=<replaceable class="parameter">mpd_host</replaceable></option></term>
 211             <listitem>
 212                 <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>
 213                 <para>See also <xref linkend="environment"/>.</para>
 214             </listitem>
 215         </varlistentry>
 216         <varlistentry><!-- port -->
 217             <term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
 218             <term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
 219             <listitem>
 220                 <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>
 221                 <para>See also <xref linkend="environment"/></para>
 222             </listitem>
 223         </varlistentry>
 224         <varlistentry> <!-- config-test -->
 225             <term><option>config-test</option></term>
 226             <listitem>
 227               <para>Test configuration file and exit. Uses the configuration file specified with <option>--config</option> or default location.<sbr />Default is to use <envar>$XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg</envar> (see <xref linkend="files"/> for more).</para>
 228                 <para>config-test tests MPD connection and Tags plugin configuration.</para>
 229             </listitem>
 230         </varlistentry>
 231         <varlistentry> <!-- create-db -->
 232             <term><option>create-db</option></term>
 233             <listitem>
 234                 <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> (see <xref linkend="files"/> for more).</para>
 235             </listitem>
 236         </varlistentry>
 237         <varlistentry> <!-- generate-config -->
 238             <term><option>generate-config</option></term>
 239             <listitem>
 240                 <para>Generate a sample configuration file according to the current CLI options and env. var.. The configuration is written on stdout.</para>
 241             </listitem>
 242         </varlistentry>
 243         <varlistentry> <!-- purge-history -->
 244             <term><option>purge-history</option></term>
 245             <listitem>
 246                 <para>Purge play history in 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> (see <xref linkend="files"/> for more).</para>
 247             </listitem>
 248         </varlistentry>
 249     </variablelist>
 250   </refsect1>
 251   <xi:include href="files.xml" />
 252   <refsect1 id="environment">
 253       <title>ENVIRONMENT</title>
 254       <variablelist>
 255           <varlistentry>
 256               <term><envar>MPD_HOST</envar>, <envar>MPD_PORT</envar></term>
 257               <listitem>
 258                   <para>&dhutils; will look for <envar>MPD_HOST</envar> and
 259                       <envar>MPD_PORT</envar> to override built-in configuration
 260                       (set to "localhost:6600").</para>
 261                   <para>&dhutils; expects <envar>MPD_HOST</envar> syntax as documented in mpc manual,
 262                       cf. <citerefentry><refentrytitle>mpc</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 263                       <sbr/>To use a password, provide a value of the form "password@host".
 264                   </para>
 265               </listitem>
 266           </varlistentry>
 267           <varlistentry>
 268               <term><envar>HTTP_PROXY</envar>, <envar>HTTPS_PROXY</envar></term>
 269               <listitem>
 270                   <para>&dhutils; honors <envar>HTTP_PROXY</envar> environment variables.</para>
 271               </listitem>
 272           </varlistentry>
 273       </variablelist>
 274   </refsect1>
 275   <refsect1 id="configuration">
 276       <title>CONFIGURATION</title>
 277       <variablelist>
 278           <varlistentry>
 279               <term><filename>mpd_sima.cfg</filename></term>
 280               <listitem>
 281                   <para><filename>mpd_sima.cfg</filename> is read if present.
 282                       Otherwise built-in defaults are used. An example should be
 283                       provided in the tarball within
 284                       <filename>doc/examples/</filename>. On Debian
 285                       system please look in
 286                       <filename>/usr/share/doc/&dhpackage;</filename>.</para>
 287               </listitem>
 288           </varlistentry>
 289           <varlistentry>
 290               <term>DEFAULTS</term>
 291               <listitem>
 292                   <para>Default is to look for MPD server at localhost:6600 (or MPD_HOST/MPD_PORT env. var. if set). The default plugins will use Last.fm to find similar tracks to queue and fallback to random if nothing if found.</para>
 293                   <para>The get the defaults as detected by &dhpackage; on your system you can run &dhpackage; to print the config:</para>
 294                   <para><command>&dhpackage; generate-config</command></para>
 295               </listitem>
 296           </varlistentry>
 297       </variablelist>
 298       <para>For details about mpd_sima.cfg refer to the manual
 299           <citerefentry>
 300               <refentrytitle>mpd_sima.cfg</refentrytitle>
 301               <manvolnum>5</manvolnum>
 302           </citerefentry>
 303       </para>
 304   </refsect1>
 305   <xi:include href="feedback.xml" />
 306   <xi:include href="seealso.xml" />
 307 </refentry>