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>