]> kaliko git repositories - mpd-sima.git/blob - data/man/mpd_sima.1.xml
Update manual
[mpd-sima.git] / 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>&dhutils;</refname>
60     <refpurpose>&dhutils; will try to maintain some titles ahead in the queue following different policies.</refpurpose>
61   </refnamediv>
62   <refsynopsisdiv>
63     <cmdsynopsis>
64       <command>&dhutils;</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>&dhutils;</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>&dhutils;</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>&dhutils;</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>&dhutils;</command>
100       <arg choice="plain">generate-config</arg>
101       <arg choice="opt"><option>…</option></arg>
102     </cmdsynopsis>
103     <cmdsynopsis>
104       <command>&dhutils;</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     <cmdsynopsis>
109       <command>&dhutils;</command>
110       <arg choice="plain">bl-view</arg>
111     </cmdsynopsis>
112     <cmdsynopsis>
113       <command>&dhutils;</command>
114       <arg choice="plain">bl-add-artist</arg>
115       <arg choice="opt"><option>artist</option></arg>
116     </cmdsynopsis>
117     <cmdsynopsis>
118       <command>&dhutils;</command>
119       <arg choice="plain">bl-add-album</arg>
120       <arg choice="opt"><option>album</option></arg>
121     </cmdsynopsis>
122     <cmdsynopsis>
123       <command>&dhutils;</command>
124       <arg choice="plain">bl-add-track</arg>
125       <arg choice="opt"><option>track</option></arg>
126     </cmdsynopsis>
127     <cmdsynopsis>
128       <command>&dhutils;</command>
129       <arg choice="plain">bl-delete</arg>
130       <arg choice="plain"><option>id</option></arg>
131     </cmdsynopsis>
132   </refsynopsisdiv>
133   <refsect1 id="description">
134     <title>DESCRIPTION</title>
135     <para>This manual page documents briefly the
136       <command>&dhutils;</command> commands.</para>
137     <para>At start up default configuration is first overridden by user
138         configuration in mpd_sima.cfg (see <xref linkend="files"/>) and finally
139         command lines options are honored. For instance you can override
140         default MPD host (localhost) in your configuration
141         file or with <command>-S my_mpd_server</command> option. For default
142         configuration see <xref linkend="configuration"/>. See also environment
143         variables special case for MPD host and port in <xref linkend="environment"/>.
144     </para>
145   </refsect1>
146     <refsect1 id="example">
147         <title>EXAMPLE</title>
148         <refsect2 id="daemon">
149             <title>Launch as a system service (dæmon).</title>
150             <para>Here follows an example on how to launch &dhutils; as a service on your system, not attach to regular user configuration/database.</para>
151             <para><command>&dhutils; --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>
152         </refsect2>
153         <refsect2 id="user_land">
154             <title>Launch in user land</title>
155             <para>Launching &dhutils; from/whithin your user account is easy, you can simply call <command>&dhutils;</command> from your shell or one of the following command:</para>
156             <para>Background execution (dæmonise), log in the specified file, save pid:</para>
157             <para><command>&dhutils; --daemon --pid=$HOME/var/run/mpd-sima.pid --log=$HOME/var/log/mpd-sima.log</command></para>
158             <para>Foreground execution, connect <emphasis>my.mpd.server.org</emphasis>, log to std(out|err):</para>
159             <para><command>&dhutils; --host=my.mpd.server.org</command></para>
160         </refsect2>
161     </refsect1>
162   <refsect1 id="options">
163     <title>OPTIONS</title>
164     <para>The program follows the usual GNU command line syntax,
165       with long options starting with two dashes (`-').  A summary of
166       options is included below.</para>
167     <variablelist>
168       <!-- Use the variablelist.term.separator and the
169            variablelist.term.break.after parameters to
170            control the term elements. -->
171            <varlistentry> <!-- help -->
172             <term><option>-h</option></term>
173             <term><option>--help</option></term>
174             <listitem>
175                 <para>Print help and exit.</para>
176             </listitem>
177         </varlistentry>
178         <varlistentry> <!-- version -->
179             <term><option>--version</option></term>
180             <listitem>
181                 <para>Print version and exit.</para>
182             </listitem>
183         </varlistentry>
184         <varlistentry> <!-- daemon -->
185             <term><option>--daemon</option></term>
186             <listitem>
187                 <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>
188             </listitem>
189         </varlistentry>
190         <varlistentry> <!-- pid_file -->
191             <term><option>-p <replaceable class="parameter">pid_file</replaceable></option></term>
192             <term><option>--pid=<replaceable class="parameter">pid_file</replaceable></option></term>
193             <listitem>
194                 <para>Use the specific file <replaceable>pid_file</replaceable> to store pid to.<sbr />Default is not to store pid info.</para>
195             </listitem>
196         </varlistentry>
197         <varlistentry> <!-- log -->
198             <term><option>-l <replaceable class="parameter">log_file</replaceable></option></term>
199             <term><option>--log=<replaceable class="parameter">log_file</replaceable></option></term>
200             <listitem>
201                 <para>Use the specific file <replaceable>log_file</replaceable> to log messages to.<sbr />Default is to log to stdout/stderr.</para>
202             </listitem>
203         </varlistentry>
204         <varlistentry> <!-- log-level -->
205             <term><option>-v <replaceable class="parameter">log_level</replaceable></option></term>
206             <term><option>--log-level=<replaceable class="parameter">log_level</replaceable></option></term>
207             <listitem>
208                 <para>Verbosity in [debug,info,warning,error].<sbr />Default is to log info messages.</para>
209             </listitem>
210         </varlistentry>
211         <varlistentry><!-- config -->
212             <term><option>-c <replaceable class="parameter">conf_file</replaceable></option></term>
213             <term><option>--config=<replaceable class="parameter">conf_file</replaceable></option></term>
214             <listitem>
215                 <para>Use the specific file <replaceable>conf_file</replaceable> to set up
216                     configuration instead of looking for the default user
217                     configuration file.<sbr />Default is to look for
218                     <envar>$XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg</envar>.<sbr />
219                     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 />
220                     For more details on configuration file cf.
221                     <citerefentry><refentrytitle>mpd_sima.cfg</refentrytitle>
222                 <manvolnum>5</manvolnum></citerefentry>, see also <xref linkend="files"/>.<sbr />
223                    </para>
224             </listitem>
225         </varlistentry>
226         <varlistentry> <!-- var-dir -->
227             <term><option>--var-dir=<replaceable class="parameter">var_directory</replaceable></option></term>
228             <listitem>
229                 <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>
230             </listitem>
231         </varlistentry>
232         <varlistentry><!-- host -->
233             <term><option>-S <replaceable class="parameter">mpd_host</replaceable></option></term>
234             <term><option>--host=<replaceable class="parameter">mpd_host</replaceable></option></term>
235             <listitem>
236                 <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>
237                 <para>See also <xref linkend="environment"/>.</para>
238             </listitem>
239         </varlistentry>
240         <varlistentry><!-- port -->
241             <term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
242             <term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
243             <listitem>
244                 <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>
245                 <para>See also <xref linkend="environment"/></para>
246             </listitem>
247         </varlistentry>
248         <varlistentry> <!-- config-test -->
249             <term><option>config-test</option></term>
250             <listitem>
251               <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>
252                 <para>config-test tests MPD connection and Tags plugin configuration.</para>
253             </listitem>
254         </varlistentry>
255         <varlistentry> <!-- create-db -->
256             <term><option>create-db</option></term>
257             <listitem>
258                 <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>
259             </listitem>
260         </varlistentry>
261         <varlistentry> <!-- generate-config -->
262             <term><option>generate-config</option></term>
263             <listitem>
264                 <para>Generate a sample configuration file according to the current CLI options and env. var.. The configuration is written on stdout.</para>
265             </listitem>
266         </varlistentry>
267         <varlistentry> <!-- purge-history -->
268             <term><option>purge-history</option></term>
269             <listitem>
270                 <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>
271             </listitem>
272         </varlistentry>
273         <varlistentry> <!-- bl-view -->
274             <term><option>bl-view</option></term>
275             <listitem>
276                 <para>View blocklist, useful to get entry IDs to remove with delete command.</para>
277             </listitem>
278         </varlistentry>
279         <varlistentry> <!-- bl-add-artist -->
280           <term><option>bl-add-artist <replaceable class="parameter">artist</replaceable></option></term>
281             <listitem>
282               <para>Add artist to the blocklist. If
283               <replaceable class="parameter">artist</replaceable>
284                 is not provided, try to get the currently playing artist.
285               </para>
286             </listitem>
287         </varlistentry>
288         <varlistentry> <!-- bl-add-album -->
289           <term><option>bl-add-album <replaceable class="parameter">album</replaceable></option></term>
290             <listitem>
291               <para>Add album to the blocklist. If
292               <replaceable class="parameter">album</replaceable>
293                 is not provided, try to get the currently playing album.
294               </para>
295             </listitem>
296         </varlistentry>
297         <varlistentry> <!-- bl-add-track -->
298           <term><option>bl-add-track <replaceable class="parameter">track</replaceable></option></term>
299             <listitem>
300               <para>Add track to the blocklist. If
301               <replaceable class="parameter">track</replaceable>
302                 is not provided, try to get the currently playing track.
303               </para>
304             </listitem>
305         </varlistentry>
306         <varlistentry> <!-- bl-delete -->
307           <term><option>bl-delete <replaceable class="parameter">id</replaceable></option></term>
308             <listitem>
309               <para>Remove blocklist entry referenced by its
310               <replaceable class="parameter">id</replaceable>. Use bloclist view command to get the id.
311               </para>
312             </listitem>
313         </varlistentry>
314     </variablelist>
315   </refsect1>
316   <xi:include href="files.xml" />
317   <refsect1 id="environment">
318       <title>ENVIRONMENT</title>
319       <variablelist>
320           <varlistentry>
321               <term><envar>MPD_HOST</envar>, <envar>MPD_PORT</envar></term>
322               <listitem>
323                   <para>&dhutils; will look for <envar>MPD_HOST</envar> and
324                       <envar>MPD_PORT</envar> to override built-in configuration
325                       (set to "localhost:6600").</para>
326                   <para>&dhutils; expects <envar>MPD_HOST</envar> syntax as documented in mpc manual, 
327                       cf. <citerefentry><refentrytitle>mpc</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
328                       <sbr/>To use a password, provide a value of the form "password@host".
329                   </para>
330               </listitem>
331           </varlistentry>
332           <varlistentry>
333               <term><envar>HTTP_PROXY</envar>, <envar>HTTPS_PROXY</envar></term>
334               <listitem>
335                   <para>&dhutils; honors <envar>HTTP_PROXY</envar> environment variables.</para>
336               </listitem>
337           </varlistentry>
338       </variablelist>
339   </refsect1>
340   <refsect1 id="configuration">
341       <title>CONFIGURATION</title>
342       <variablelist>
343           <varlistentry>
344               <term><filename>mpd_sima.cfg</filename></term>
345               <listitem>
346                   <para><filename>mpd_sima.cfg</filename> is read if present.
347                       Otherwise built-in defaults are used. An example should be
348                       provided in the tarball within
349                       <filename>doc/examples/</filename>. On Debian
350                       system please look in
351                       <filename>/usr/share/doc/&dhpackage;</filename>.</para>
352               </listitem>
353           </varlistentry>
354           <varlistentry>
355               <term>DEFAULTS</term>
356               <listitem>
357                   <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>
358                   <para>The get the defaults as detected by &dhutils; on your system you can run &dhutils; to print the config:</para>
359                   <para><command>&dhpackage; generate-config</command></para>
360               </listitem>
361           </varlistentry>
362       </variablelist>
363       <para>For details about mpd_sima.cfg refer to the manual
364           <citerefentry>
365               <refentrytitle>mpd_sima.cfg</refentrytitle>
366               <manvolnum>5</manvolnum>
367           </citerefentry>
368       </para>
369   </refsect1>
370   <xi:include href="feedback.xml" />
371   <xi:include href="seealso.xml" />
372 </refentry>