]> kaliko git repositories - mpd-sima.git/blob - data/man/simadb_cli.1.xml
Document new offline autoqueue plugin based on file tags only
[mpd-sima.git] / data / man / simadb_cli.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 "simadb_cli">
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; is a command line interface editor for the sima user DB.</refpurpose>
61     </refnamediv>
62     <refsynopsisdiv>
63         <cmdsynopsis><!-- EDIT (RM ARTIST) OPTIONS -->
64             <command>&dhutils;</command>
65             <arg choice="plain"><option>--remove_artist=</option><replaceable class="parameter">artist</replaceable></arg>
66             <arg choice="opt">
67                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
68             </arg>
69             <arg choice="opt">
70                 <option>--reciprocal</option>
71             </arg>
72         </cmdsynopsis>
73         <cmdsynopsis><!-- EDIT (PURGE HIST) OPTIONS -->
74             <command>&dhutils;</command>
75             <arg choice="plain"><option>--purge_hist</option></arg>
76             <arg choice="opt">
77                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
78             </arg>
79         </cmdsynopsis>
80         <cmdsynopsis><!-- VIEW ALL ENTRIES OPTIONS -->
81             <command>&dhutils;</command>
82             <arg choice="plain"><option>--view_all</option></arg>
83             <arg choice="opt">
84                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
85             </arg>
86         </cmdsynopsis>
87         <cmdsynopsis><!-- EDIT (BLACK LIST) OPTIONS -->
88             <command>&dhutils;</command>
89             <group choice="req">
90                 <arg choice="plain"><option>--bl_curr_trk</option></arg>
91                 <arg choice="plain"><option>--bl_curr_art</option></arg>
92                 <arg choice="plain"><option>--bl_curr_alb</option></arg>
93                 <arg choice="plain"><option>--bl_art=</option><replaceable class="parameter">artist_name</replaceable></arg>
94             </group>
95             <arg choice="opt">
96                 <arg choice="plain"><option>--dbfile=</option><replaceable class="parameter">db_file</replaceable></arg>
97             </arg>
98             <arg choice="opt">
99                 <arg choice="plain"><option>--host=</option><replaceable class="option">mpd_host</replaceable></arg>
100             </arg>
101             <arg choice="opt">
102                 <arg choice="plain"><option>--port=</option><replaceable class="option">mpd_port</replaceable></arg>
103             </arg>
104         </cmdsynopsis>
105         <cmdsynopsis><!-- EDIT (RM BL) OPTIONS -->
106             <command>&dhutils;</command>
107             <arg choice="plain"><option>--remove_bl=</option><replaceable class="parameter">row_id</replaceable></arg>
108             <arg choice="opt">
109                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
110             </arg>
111         </cmdsynopsis>
112         <cmdsynopsis><!-- VIEW BL OPTIONS -->
113             <command>&dhutils;</command>
114             <arg choice="plain"><option>--view_bl</option></arg>
115             <arg choice="opt">
116                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
117             </arg>
118         </cmdsynopsis>
119         <cmdsynopsis><!-- HELP/VERSION -->
120             <command>&dhutils;</command>
121             <!-- Normally the help and version options make the programs stop
122             right after outputting the requested information. -->
123             <group choice="req">
124                 <arg choice="plain">
125                     <group choice="req">
126                         <arg choice="plain"><option>-h</option></arg>
127                         <arg choice="plain"><option>--help</option></arg>
128                     </group>
129                 </arg>
130                 <arg choice="plain"><option>--version</option></arg>
131             </group>
132         </cmdsynopsis>
133     </refsynopsisdiv>
134     <refsect1 id="description">
135         <title>DESCRIPTION</title>
136         <para>This manual page documents briefly the
137             <command>&dhutils;</command> commands.</para>
138         <para>simadb_cli is a command line interface to get and edit users
139             blacklist database used with MPD_sima. The default
140             database file (see <xref linkend="files"/>) can be overridden if
141             you want.</para>
142     </refsect1>
143     <refsect1 id="example">
144         <title>EXAMPLE</title>
145         <refsect2 id="blacklist">
146             <title>Black list edition</title>
147             <para><emphasis>Adding to black list.</emphasis> You can add a single
148                 track, an album or an artist to the black list. The element to
149                 black list is chosen from the currently playing track. Use
150                 <option>--bl_curr_trk</option> to prevent &dhutils; to queue this
151                 track, <option>--bl_curr_alb</option> or <option>--bl_curr_art</option> respectively for the album and the
152                 artist.
153             </para>
154             <para>Remember you need access to your MPD server to retrieve
155                 information to black list. Defaults are localhost:6600 or found in
156                 environment variables but you may set it up from command
157                 line:
158             </para>
159             <para><command>&dhutils; --bl_curr_art -S mympd.example.org</command></para>
160             <para>
161                 <emphasis>To black list a specific artist</emphasis> (not
162                 currently playing) you can use <option>--bl_ar="Artist name to black list"</option>.
163             </para>
164         </refsect2>
165     </refsect1>
166     <refsect1 id="options">
167         <title>OPTIONS</title>
168         <para>The program follows the usual GNU command line syntax,
169             with long options starting with two dashes ("-").  A summary of
170             options is included below.</para>
171         <variablelist>
172             <!-- Use the variablelist.term.separator and the
173             variablelist.term.break.after parameters to
174             control the term elements. -->
175             <varlistentry> <!-- help -->
176                 <term><option>-h</option></term>
177                 <term><option>--help</option></term>
178                 <listitem>
179                     <para>Print help and exit.</para>
180                 </listitem>
181             </varlistentry>
182             <varlistentry> <!-- version -->
183                 <term><option>--version</option></term>
184                 <listitem>
185                     <para>Print version and exit.</para>
186                 </listitem>
187             </varlistentry>
188             <varlistentry> <!-- black list artist -->
189                 <term><option>--bl_art=<replaceable class="parameter">artist_name</replaceable></option></term>
190                 <listitem>
191                     <para>Use to black list <replaceable class="parameter">artist_name</replaceable>. &dhutils; is checking <replaceable class="parameter">artist_name</replaceable> is actually in MPD music library (cf <option>-S</option> and <option>-P</option> options to set MPD host/address if necessary).</para>
192                     <para>If <replaceable class="parameter">artist_name</replaceable> is not found the script print out a list of matching artists.</para>
193                 </listitem>
194             </varlistentry>
195             <varlistentry> <!-- black list -->
196                 <term><option>--bl_curr_trk</option> | <option>--bl_curr_art</option> | <option>--bl_curr_alb</option></term>
197                 <listitem>
198                     <para>Use to black list the currently playing track|artist|album. You need access to your MPD server, use <option>-S</option> and <option>-P</option> to set MPD host/address if necessary.</para>
199                 </listitem>
200             </varlistentry>
201             <varlistentry> <!-- dbfile -->
202                 <term><option>-d <replaceable class="parameter">db_file</replaceable></option></term>
203                 <term><option>--dbfile=<replaceable class="parameter">db_file</replaceable></option></term>
204                 <listitem>
205                     <para>Use the specific file <replaceable>db_file</replaceable> as database.<sbr />Default is too use <envar>XDG_DATA_HOME</envar> (see <xref linkend="files"/>).</para>
206                 </listitem>
207             </varlistentry>
208             <varlistentry> <!-- purge history -->
209                 <term><option>--purge_hist</option></term>
210                 <listitem>
211                     <para>Purge history, you may supply an alternative DB file with --dbfile option.</para>
212                 </listitem>
213             </varlistentry>
214             <varlistentry> <!-- remove bl id -->
215                 <term><option>--remove_bl=<replaceable class="parameter">row_id</replaceable></option></term>
216                 <listitem>
217                     <para>Use to remove a black list entry. To get the row_id to suppress use <option>--view_bl</option> option.</para>
218                 </listitem>
219             </varlistentry>
220             <varlistentry> <!-- view bl -->
221                 <term><option>--view_bl</option></term>
222                 <listitem>
223                     <para>Get all entries in the black list.</para>
224                 </listitem>
225             </varlistentry>
226             <varlistentry>
227                 <term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
228                 <term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
229                 <listitem>
230                     <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>
231                 </listitem>
232             </varlistentry>
233             <varlistentry>
234                 <term><option>-S <replaceable class="parameter">mpd_host</replaceable></option></term>
235                 <term><option>--host=<replaceable class="parameter">mpd_host</replaceable></option></term>
236                 <listitem>
237                     <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>
238                 </listitem>
239             </varlistentry>
240         </variablelist>
241     </refsect1>
242     <refsect1 id="files">
243         <title>FILES</title>
244         <variablelist>
245             <varlistentry>
246                 <term><filename>${XDG_DATA_HOME}/mpd_sima/sima.db</filename></term>
247                 <listitem>
248                     <para>SQLite DB file. Usually <envar>XDG_DATA_HOME</envar> is set to <filename>${HOME}/.local/share</filename>.</para>
249                 </listitem>
250             </varlistentry>
251         </variablelist>
252     </refsect1>
253   <xi:include href="feedback.xml" />
254   <xi:include href="seealso.xml" />
255 </refentry>