--- /dev/null
+<?xml version='1.0' encoding='UTF-8'?>
+<!--
+
+`xsltproc -''-nonet \
+ -''-param man.charmap.use.subset "0" \
+ -''-param make.year.ranges "1" \
+ -''-param make.single.year.ranges "1" \
+ /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \
+ manpage.xml'
+
+A manual page <package>.<section> will be generated. You may view the
+manual page with: nroff -man <package>.<section> | less'. A typical entry
+in a Makefile or Makefile.am is:
+
+DB2MAN = /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl
+XP = xsltproc -''-nonet -''-param man.charmap.use.subset "0"
+
+manpage.1: manpage.xml
+ $(XP) $(DB2MAN) $<
+
+The xsltproc binary is found in the xsltproc package. The XSL files are in
+docbook-xsl. A description of the parameters you can use can be found in the
+docbook-xsl-doc-* packages. Please remember that if you create the nroff
+version in one of the debian/rules file targets (such as build), you will need
+to include xsltproc and docbook-xsl in your Build-Depends control field.
+Alternatively use the xmlto command/package. That will also automatically
+pull in xsltproc and docbook-xsl.
+
+Notes for using docbook2x: docbook2x-man does not automatically create the
+AUTHOR(S) and COPYRIGHT sections. In this case, please add them manually as
+<refsect1> ... </refsect1>.
+
+To disable the automatic creation of the AUTHOR(S) and COPYRIGHT sections
+read /usr/share/doc/docbook-xsl/doc/manpages/authors.html. This file can be
+found in the docbook-xsl-doc-html package.
+
+Validation can be done using: `xmllint -''-noout -''-valid manpage.xml`
+
+General documentation about man-pages and man-page-formatting:
+man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
+
+-->
+<!DOCTYPE refentry [
+
+ <!ENTITY dhsection "1">
+ <!ENTITY dhpackage "mpd-sima">
+ <!ENTITY dhutils "mpd-sima">
+
+]>
+
+<refentry xmlns="http://docbook.org/ns/docbook"
+ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
+ <xi:include href="info.xml" />
+ <refmeta>
+ <refentrytitle>&dhutils;</refentrytitle>
+ <manvolnum>&dhsection;</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>&dhpackage;</refname>
+ <refpurpose>&dhpackage; will try to maintain some titles ahead in your play list following different policies.</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>&dhpackage;</command>
+ <arg choice="opt"><option>--daemon</option></arg>
+ <arg choice="opt"><option>--config=</option><replaceable class="option">conf_file</replaceable></arg>
+ <arg choice="opt"><option>--var_dir=</option><replaceable class="option">var_directory</replaceable></arg>
+ <arg choice="opt"><option>--pid=</option><replaceable class="option">pid_file</replaceable></arg>
+ <arg choice="opt"><option>--log=</option><replaceable class="option">log_file</replaceable></arg>
+ <arg choice="opt"><option>--log-level=</option><replaceable class="option">log_level</replaceable></arg>
+ <arg choice="opt"><option>--host=</option><replaceable class="option">mpd_host</replaceable></arg>
+ <arg choice="opt"><option>--mpd_port=</option><replaceable class="option">mpd_port</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>&dhpackage;</command>
+ <arg choice="opt"><option>--var_dir=</option><replaceable class="option">var_directory</replaceable></arg>
+ <arg choice="opt"><option>--create-db></option></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>&dhpackage;</command>
+ <!-- Normally the help and version options make the programs stop
+ right after outputting the requested information. -->
+ <group choice="opt">
+ <arg choice="plain">
+ <group choice="req">
+ <arg choice="plain"><option>-h</option></arg>
+ <arg choice="plain"><option>--help</option></arg>
+ </group>
+ </arg>
+ <arg choice="plain"><option>--version</option></arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1 id="description">
+ <title>DESCRIPTION</title>
+ <para>This manual page documents briefly the
+ <command>&dhpackage;</command> commands.</para>
+ <para>At start up default configuration is first overridden by user
+ configuration in mpd_sima.cfg (see <xref linkend="files"/>) and finally
+ command lines options are honored. For instance you can override
+ default MPD_HOST set in defaults (localhost) or in your configuration
+ file with <command>-S my_mpd_server</command> option. For default
+ configuration see <xref linkend="configuration"/>.</para>
+ </refsect1>
+ <refsect1 id="example">
+ <title>EXAMPLE</title>
+ <refsect2 id="daemon">
+ <title>Launch as a system service (dæmon).</title>
+ <para>Here follows an example on how to launch &dhpackage; as a service on your system, not attach to regular user configuration/database.</para>
+ <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>
+ </refsect2>
+ <refsect2 id="user_land">
+ <title>Launch in user land</title>
+ <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>
+ <para>Background execution (dæmonise), log in the specified file, save pid:</para>
+ <para><command>&dhpackage; --daemon --pid=$HOME/var/run/mpd-sima.pid --log=$HOME/var/log/mpd-sima.log</command></para>
+ <para>Foreground execution, connect <emphasis>my.mpd.server.org</emphasis>, log to std(out|err):</para>
+ <para><command>&dhpackage; --host=my.mpd.server.org</command></para>
+ </refsect2>
+ </refsect1>
+ <refsect1 id="options">
+ <title>OPTIONS</title>
+ <para>The program follows the usual GNU command line syntax,
+ with long options starting with two dashes (`-'). A summary of
+ options is included below.</para>
+ <variablelist>
+ <!-- Use the variablelist.term.separator and the
+ variablelist.term.break.after parameters to
+ control the term elements. -->
+ <varlistentry> <!-- help -->
+ <term><option>-h</option></term>
+ <term><option>--help</option></term>
+ <listitem>
+ <para>Print help and exit.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- version -->
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Print version and exit.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- daemon -->
+ <term><option>--daemon</option></term>
+ <listitem>
+ <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>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- pid_file -->
+ <term><option>-p <replaceable class="parameter">pid_file</replaceable></option></term>
+ <term><option>--pid=<replaceable class="parameter">pid_file</replaceable></option></term>
+ <listitem>
+ <para>Use the specific file <replaceable>pid_file</replaceable> to store pid to.<sbr />Default is not to store pid info.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- log -->
+ <term><option>-l <replaceable class="parameter">log_file</replaceable></option></term>
+ <term><option>--log=<replaceable class="parameter">log_file</replaceable></option></term>
+ <listitem>
+ <para>Use the specific file <replaceable>log_file</replaceable> to log messages to.<sbr />Default is to log to stdout/stderr.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- log-level -->
+ <term><option>-v <replaceable class="parameter">log_level</replaceable></option></term>
+ <term><option>--log-level=<replaceable class="parameter">log_level</replaceable></option></term>
+ <listitem>
+ <para>Verbosity in [debug,info,warning,error].<sbr />Default is to log info messages.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c <replaceable class="parameter">conf_file</replaceable></option></term>
+ <term><option>--config=<replaceable class="parameter">conf_file</replaceable></option></term>
+ <listitem>
+ <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>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- var_dir -->
+ <term><option>--var_dir=<replaceable class="parameter">var_directory</replaceable></option></term>
+ <listitem>
+ <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>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- create-db -->
+ <term><option>--create-db</option></term>
+ <listitem>
+ <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>
+ </listitem>
+ </varlistentry>
+ <varlistentry><!-- host -->
+ <term><option>-S <replaceable class="parameter">mpd_host</replaceable></option></term>
+ <term><option>--host=<replaceable class="parameter">mpd_host</replaceable></option></term>
+ <listitem>
+ <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>
+ <para>See also <xref linkend="environment"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><!-- port -->
+ <term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
+ <term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
+ <listitem>
+ <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>
+ <para>See also <xref linkend="environment"/></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="files">
+ <title>FILES</title>
+ <variablelist>
+ <varlistentry>
+ <term><filename>${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg</filename></term>
+ <!--
+ <listitem>
+ </listitem>
+ <term><filename>${HOME}/.config/mpd_sima/mpd_sima.cfg</filename></term>
+ -->
+ <listitem>
+ <para>The per-user configuration file. Usually <envar>XDG_CONFIG_HOME</envar> is set to <filename>${HOME}/.config</filename>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>${XDG_DATA_HOME}/mpd_sima/sima.db</filename></term>
+ <!--
+ <listitem>
+ </listitem>
+ <term><filename>${HOME}/.local/share/mpd_sima/history.pkl</filename></term>
+ -->
+ <listitem>
+ <para>SQLite database. Usually <envar>XDG_DATA_HOME</envar> is set to <filename>${HOME}/.local/share</filename>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="environment">
+ <title>ENVIRONMENT</title>
+ <variablelist>
+ <varlistentry>
+ <term><envar>MPD_HOST</envar>, <envar>MPD_PORT</envar></term>
+ <listitem>
+ <para>&dhutils; will look for <envar>MPD_HOST</envar> and
+ <envar>MPD_PORT</envar> to override built-in configuration
+ (set to "localhost:6600").</para>
+ <para>&dhutils; expects <envar>MPD_HOST</envar> syntax as documented in mpc manual,
+ cf. <citerefentry><refentrytitle>mpc</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ <sbr/>To use a password, provide a value of the form "password@host".
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="configuration">
+ <title>CONFIGURATION</title>
+ <variablelist>
+ <varlistentry>
+ <term><filename>mpd_sima.cfg</filename></term>
+ <listitem>
+ <para><filename>mpd_sima.cfg</filename> is read if present.
+ Otherwise built-in defaults are used. An example should be
+ provided in the tarball within
+ <filename>doc/examples/mpd_sima.cfg</filename>. On Debian
+ system please look in
+ <filename>/usr/share/doc/&dhpackage;</filename>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DEFAULTS</term>
+ <listitem>
+ <para>Default is to look for MPD server at localhost:6600 (or MPD_HOST/MPD_PORT env. var. if set).</para>
+ <para>The default behavior is to add one track,
+ this track is to be chosen among titles from
+ artists similar to the artist of the currently
+ played track. MPD_sima will add one track when the
+ play list is one track long.</para>
+ <para>To change these defaults, use the configuration file <filename>mpd_sima.cfg</filename></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <xi:include href="feedback.xml" />
+ <refsect1 id="see_also">
+ <title>SEE ALSO</title>
+ <!-- In alpabetical order. -->
+ <para>
+ <citerefentry>
+ <refentrytitle>mpc</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>, <citerefentry>
+ <refentrytitle>mpd</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>, <citerefentry>
+ <refentrytitle>mpd-sima.cfg</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </citerefentry>
+ </para>
+ <para>
+ <filename>/usr/share/doc/mpd-sima/</filename>
+ </para>
+ </refsect1>
+</refentry>
home / dev / repositories / mpd-sima.git / commitdiff