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><!-- REGULAR EDIT (ADD) OPTIONS -->
  64             <command>&dhutils;</command>
  65             <arg choice="plain"><option>--add_similarity=</option><replaceable class="option">similarity_string</replaceable></arg>
  66             <arg choice="opt">
  67                 <option>--check_names</option>
  68             </arg>
  69             <arg choice="opt">
  70                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
  71             </arg>
  72             <arg choice="opt">
  73                 <option>--reciprocal</option>
  74             </arg>
  75             <arg choice="opt">
  76                 <option>--host=</option><replaceable class="option">mpd_host</replaceable>
  77             </arg>
  78             <arg choice="opt">
  79                 <option>--port=</option><replaceable class="option">mpd_port</replaceable>
  80             </arg>
  81         </cmdsynopsis>
  82         <cmdsynopsis><!-- EDIT (RM ARTIST) OPTIONS -->
  83             <command>&dhutils;</command>
  84             <arg choice="plain"><option>--remove_artist=</option><replaceable class="parameter">artist</replaceable></arg>
  85             <arg choice="opt">
  86                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
  87             </arg>
  88             <arg choice="opt">
  89                 <option>--reciprocal</option>
  90             </arg>
  91         </cmdsynopsis>
  92         <cmdsynopsis><!-- EDIT (RM SIM) OPTIONS -->
  93             <command>&dhutils;</command>
  94             <arg choice="plain"><option>--remove_similarity=</option><replaceable class="parameter">"main artist,similar artist"</replaceable></arg>
  95             <arg choice="opt">
  96                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
  97             </arg>
  98             <arg choice="opt">
  99                 <option>--reciprocal</option>
 100             </arg>
 101         </cmdsynopsis>
 102         <cmdsynopsis><!-- EDIT (PURGE HIST) OPTIONS -->
 103             <command>&dhutils;</command>
 104             <arg choice="plain"><option>--purge_hist</option></arg>
 105             <arg choice="opt">
 106                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
 107             </arg>
 108         </cmdsynopsis>
 109         <cmdsynopsis><!-- REGULAR VIEW OPTIONS -->
 110             <command>&dhutils;</command>
 111             <arg choice="plain"><option>--view_artist=<replaceable class="parameter">"artist name"</replaceable></option></arg>
 112             <arg choice="opt">
 113                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
 114             </arg>
 115         </cmdsynopsis>
 116         <cmdsynopsis><!-- VIEW ALL ENTRIES OPTIONS -->
 117             <command>&dhutils;</command>
 118             <arg choice="plain"><option>--view_all</option></arg>
 119             <arg choice="opt">
 120                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
 121             </arg>
 122         </cmdsynopsis>
 123         <cmdsynopsis><!-- EDIT (BLACK LIST) OPTIONS -->
 124             <command>&dhutils;</command>
 125             <group choice="req">
 126                 <arg choice="plain"><option>--bl_curr_trk</option></arg>
 127                 <arg choice="plain"><option>--bl_curr_art</option></arg>
 128                 <arg choice="plain"><option>--bl_curr_alb</option></arg>
 129                 <arg choice="plain"><option>--bl_art=</option><replaceable class="parameter">artist_name</replaceable></arg>
 130             </group>
 131             <arg choice="opt">
 132                 <arg choice="plain"><option>--dbfile=</option><replaceable class="parameter">db_file</replaceable></arg>
 133             </arg>
 134             <arg choice="opt">
 135                 <arg choice="plain"><option>--host=</option><replaceable class="option">mpd_host</replaceable></arg>
 136             </arg>
 137             <arg choice="opt">
 138                 <arg choice="plain"><option>--port=</option><replaceable class="option">mpd_port</replaceable></arg>
 139             </arg>
 140         </cmdsynopsis>
 141         <cmdsynopsis><!-- EDIT (RM BL) OPTIONS -->
 142             <command>&dhutils;</command>
 143             <arg choice="plain"><option>--remove_bl=</option><replaceable class="parameter">row_id</replaceable></arg>
 144             <arg choice="opt">
 145                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
 146             </arg>
 147         </cmdsynopsis>
 148         <cmdsynopsis><!-- VIEW BL OPTIONS -->
 149             <command>&dhutils;</command>
 150             <arg choice="plain"><option>--view_bl</option></arg>
 151             <arg choice="opt">
 152                 <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
 153             </arg>
 154         </cmdsynopsis>
 155         <cmdsynopsis><!-- HELP/VERSION -->
 156             <command>&dhutils;</command>
 157             <!-- Normally the help and version options make the programs stop
 158             right after outputting the requested information. -->
 159             <group choice="req">
 160                 <arg choice="plain">
 161                     <group choice="req">
 162                         <arg choice="plain"><option>-h</option></arg>
 163                         <arg choice="plain"><option>--help</option></arg>
 164                     </group>
 165                 </arg>
 166                 <arg choice="plain"><option>--version</option></arg>
 167             </group>
 168         </cmdsynopsis>
 169     </refsynopsisdiv>
 170     <refsect1 id="description">
 171         <title>DESCRIPTION</title>
 172         <para>This manual page documents briefly the
 173             <command>&dhutils;</command> commands.</para>
 174         <para>simadb_cli is a command line interface to get and edit users
 175             similarities and blacklist database used with MPD_sima. The default
 176             database file (see <xref linkend="files"/>) can be overridden if
 177             you want.</para>
 178         <para>Consider reading <xref linkend="simadb" /> to understand the
 179             structure and relation of similarities within the database.</para>
 180     </refsect1>
 181     <refsect1 id="example">
 182         <title>EXAMPLE</title>
 183         <refsect2 id="similarity">
 184             <title>Similarity edition</title>
 185             <para>Here follows some simple examples on how to deal with similarity database.</para>
 186             <para>Pay attention, the following examples set one-way similarities in the DB! Read more about it in <xref linkend="simadb" />.</para>
 187             <para><emphasis>Adding a similarity between two artists.</emphasis> In the following example "Pelican" will point
 188                 to "Russian Circles" with a match score of 88% (ie. "Russian Circles"
 189                 88% similar to Pelican, not reciprocal), it will also check against MPD
 190                 the presence of both artists in the music library.</para>
 191             <para><command>&dhutils; --add "Pelican,Russian Circles:80" --check_names</command></para>
 192             <para>Similarity string use comma "," as artists separator and semi colon ":" for
 193                 artist/similarity score separator, cf. <xref linkend="simiformat"/>.</para>
 194             <para><emphasis>Adding a similarity between multiple artists.</emphasis> In the following example "Rage
 195                 Against The Machine" will point to "Tool" and "Audioslave" as similar
 196                 artists and controls artists names are actually in MPD music library.</para>
 197             <para><command>&dhutils; --add "Rage Against The Machine,Tool:70,Audiosalve:80" --check_names</command></para>
 198             <para><emphasis>Viewing similarit(y|ies) for an artist.</emphasis> In the
 199                 following example we are looking for entries for "Rage Against The Machine"</para>
 200             <para><command>&dhutils; --view_artist "Rage Against The Machine"</command></para>
 201         </refsect2>
 202         <refsect2 id="blacklist">
 203             <title>Black list edition</title>
 204             <para><emphasis>Adding to black list.</emphasis> You can add a single
 205                 track, an album or an artist to the black list. The element to
 206                 black list is chosen from the currently playing track. Use
 207                 <option>--bl_curr_trk</option> to prevent &dhutils; to queue this
 208                 track, <option>--bl_curr_alb</option> or <option>--bl_curr_art</option> respectively for the album and the
 209                 artist.
 210             </para>
 211             <para>Remember you need access to your MPD server to retrieve
 212                 information to black list. Defaults are localhost:6600 or found in
 213                 environment variables but you may set it up from command
 214                 line:
 215             </para>
 216             <para><command>&dhutils; --bl_curr_art -S mympd.example.org</command></para>
 217             <para>
 218                 <emphasis>To black list a specific artist</emphasis> (not
 219                 currently playing) you can use <option>--bl_ar="Artist name to black list"</option>.
 220             </para>
 221         </refsect2>
 222     </refsect1>
 223     <refsect1 id="options">
 224         <title>OPTIONS</title>
 225         <para>The program follows the usual GNU command line syntax,
 226             with long options starting with two dashes ("-").  A summary of
 227             options is included below.</para>
 228         <variablelist>
 229             <!-- Use the variablelist.term.separator and the
 230             variablelist.term.break.after parameters to
 231             control the term elements. -->
 232             <varlistentry> <!-- help -->
 233                 <term><option>-h</option></term>
 234                 <term><option>--help</option></term>
 235                 <listitem>
 236                     <para>Print help and exit.</para>
 237                 </listitem>
 238             </varlistentry>
 239             <varlistentry> <!-- version -->
 240                 <term><option>--version</option></term>
 241                 <listitem>
 242                     <para>Print version and exit.</para>
 243                 </listitem>
 244             </varlistentry>
 245             <varlistentry> <!-- add similarity -->
 246                 <term><option>-a <replaceable class="parameter">similarity_string</replaceable></option></term>
 247                 <term><option>--add_similarity=<replaceable class="parameter">similarity_string</replaceable></option></term>
 248                 <listitem>
 249                     <para>Add similarity to the database.<sbr />For more details about the <replaceable class="option">similarity_string</replaceable> see <xref linkend="simiformat"/>.</para>
 250                 </listitem>
 251             </varlistentry>
 252             <varlistentry> <!-- check_names -->
 253                 <term><option>-c</option></term>
 254                 <term><option>--check_names</option></term>
 255                 <listitem>
 256                     <para>Use with <option>--add_similarity</option> in order to check artists names used in <replaceable class="parameter">similarity_string</replaceable>. &dhutils; will control presence of artists names in MPD library. Default is to look for MPD server on localhost:6600 or environment variables <envar>MPD_HOST</envar> and <envar>MPD_PORT</envar> if set.<sbr />You can as well give &dhutils; host/port on the command line using respectively <option>-S</option> and <option>-P</option>.</para>
 257                 </listitem>
 258             </varlistentry>
 259             <varlistentry> <!-- black list artist -->
 260                 <term><option>--bl_art=<replaceable class="parameter">artist_name</replaceable></option></term>
 261                 <listitem>
 262                     <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>
 263                     <para>If <replaceable class="parameter">artist_name</replaceable> is not found the script print out a list of matching artists.</para>
 264                 </listitem>
 265             </varlistentry>
 266             <varlistentry> <!-- black list -->
 267                 <term><option>--bl_curr_trk</option> | <option>--bl_curr_art</option> | <option>--bl_curr_alb</option></term>
 268                 <listitem>
 269                     <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>
 270                 </listitem>
 271             </varlistentry>
 272             <varlistentry> <!-- dbfile -->
 273                 <term><option>-d <replaceable class="parameter">db_file</replaceable></option></term>
 274                 <term><option>--dbfile=<replaceable class="parameter">db_file</replaceable></option></term>
 275                 <listitem>
 276                     <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>
 277                 </listitem>
 278             </varlistentry>
 279             <varlistentry> <!-- purge history -->
 280                 <term><option>--purge_hist</option></term>
 281                 <listitem>
 282                     <para>Purge history, you may supply an alternative DB file with --dbfile option.</para>
 283                 </listitem>
 284             </varlistentry>
 285             <varlistentry> <!-- reciprocal -->
 286                 <term><option>-r</option></term>
 287                 <term><option>--reciprocal</option></term>
 288                 <listitem>
 289                     <para>Use with an editing options in order to edit reciprocal similarity as well. <option>--add_similarity</option> and <option>--remove_{artist|similarity}</option> are supporting reciprocal edition.</para>
 290                     <para><emphasis>N.B</emphasis>: this option has to appear after the editing option on the command line.</para>
 291                     <para>See <xref linkend="simadb"/> for further information about reciprocity notion.</para>
 292                 </listitem>
 293             </varlistentry>
 294             <varlistentry> <!-- remove artist -->
 295                 <term><option>--remove_artist=<replaceable class="parameter">artist</replaceable></option></term>
 296                 <listitem>
 297                     <para>Use to remove an artist entry (as main artist) with its associated similarities. To remove artist where it appears as a similar artist use the <option>--reciprocal</option> option.</para>
 298                 </listitem>
 299             </varlistentry>
 300             <varlistentry> <!-- remove bl id -->
 301                 <term><option>--remove_bl=<replaceable class="parameter">row_id</replaceable></option></term>
 302                 <listitem>
 303                     <para>Use to remove a black list entry. To get the row_id to suppress use <option>--view_bl</option> option.</para>
 304                 </listitem>
 305             </varlistentry>
 306             <varlistentry> <!-- remove similarity -->
 307                 <term><option>--remove_similarity=<replaceable class="parameter">"main artist,similar artist"</replaceable></option></term>
 308                 <listitem>
 309                     <para>Use to remove a single similarity between a main artist and an associated similarity. Give the main artist first, use comma (",") to separate it from similar artist.<sbr />Use of <option>--reciprocal</option> is possible here, see <xref linkend="simadb" />.</para>
 310                     <para>This option is useful in case you want to remove only a specific similarity between two artists, to remove completely an artist use <option>--remove_artist</option> instead.</para>
 311                 </listitem>
 312             </varlistentry>
 313             <varlistentry> <!-- view artist -->
 314                 <term><option>-v <replaceable class="parameter">"artist name"</replaceable></option></term>
 315                 <term><option>--view_artist=<replaceable class="parameter">"artist name"</replaceable></option></term>
 316                 <listitem>
 317                     <para>Get entries for <replaceable class="parameter">"artist name"</replaceable> in the data base (print to stdout).</para>
 318                 </listitem>
 319             </varlistentry>
 320             <varlistentry> <!-- view bl -->
 321                 <term><option>--view_bl</option></term>
 322                 <listitem>
 323                     <para>Get all entries in the black list.</para>
 324                 </listitem>
 325             </varlistentry>
 326             <varlistentry> <!-- view all -->
 327                 <term><option>--view_all</option></term>
 328                 <listitem>
 329                     <para>Get all entries in the data base (print to stdout).</para>
 330                 </listitem>
 331             </varlistentry>
 332             <varlistentry>
 333                 <term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
 334                 <term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
 335                 <listitem>
 336                     <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>
 337                 </listitem>
 338             </varlistentry>
 339             <varlistentry>
 340                 <term><option>-S <replaceable class="parameter">mpd_host</replaceable></option></term>
 341                 <term><option>--host=<replaceable class="parameter">mpd_host</replaceable></option></term>
 342                 <listitem>
 343                     <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>
 344                 </listitem>
 345             </varlistentry>
 346         </variablelist>
 347     </refsect1>
 348     <refsect1 id="files">
 349         <title>FILES</title>
 350         <variablelist>
 351             <varlistentry>
 352                 <term><filename>${XDG_DATA_HOME}/mpd_sima/sima.db</filename></term>
 353                 <listitem>
 354                     <para>SQLite DB file. Usually <envar>XDG_DATA_HOME</envar> is set to <filename>${HOME}/.local/share</filename>.</para>
 355                 </listitem>
 356             </varlistentry>
 357         </variablelist>
 358     </refsect1>
 359     <refsect1 id="simiformat">
 360         <title>SIMILARITY FORMAT</title>
 361         <para>The <replaceable class="parameter">similarity_string</replaceable> has to be formatted following a special pattern in order for simadb_cli to extract similarity relations between artists names. Usually a similarity entry is defined as a main artist, lets say <emphasis>main_art</emphasis>, followed by a list of similar artists which you want to be related to that <emphasis>main_art</emphasis>, each artist of that list with a specific similarity value, a match score, quantifying the similarity relation with the <emphasis>main_art</emphasis>. The match score value is an integer in [0 ,100] with 100 corresponding to a perfect match.</para>
 362         <para><replaceable class="parameter">similarity_string</replaceable> is then to be formatted as follow:</para>
 363         <para><command>main_art,first artist:&lt;score&gt;,second artist:&lt;score&gt;</command></para>
 364         <para>Each artist group are separated with commas (",") and inside each group the artist name and the match score is colon (":") separated. Obviously the first artist group, as the main artist, does not have a match score.</para>
 365         <para>Lets see how it works with an example. I consider "Led Zeppelin" to be similar to "Tool" with a match score of 25, I also want to have "Audioslave" related to "Led Zeppelin" with a score of 20. Then the <replaceable class="parameter">similarity_string</replaceable> will be the following:</para>
 366         <para><command>Led Zeppelin,Tool:25,Audiosalve:20</command></para>
 367         <para>See <xref linkend="simadb" /> for more details about how similarities are handled</para>
 368     </refsect1>
 369     <refsect1 id="simadb">
 370         <title>A WORD ABOUT SIMA DATA BASE</title>
 371         <para>The similarity database is defined from the point of view of a <emphasis>main artist</emphasis> which is declared related to a list of <emphasis>similar artists</emphasis>. That means when you define <emphasis>main_art</emphasis> to be similar to <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> the reciprocal won't be true, <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> are not similar to <emphasis>main_art</emphasis>. At least this is the default behavior when you edit entries with simadb_cli, this is also the way last.fm is working concerning similar artists. This documentation is using that particular terminology to specify which kind of artist we are dealing with : "main artist" or "similar artist".<sbr />The <option>--reciprocal</option> option allows one to add reciprocal relation where <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> become respectively the <emphasis>main_art</emphasis>. Using <option>--reciprocal</option> you will then edit two more entries in the database. To summarize here is what you'll end up with in your data base adding similarity with this string <command>main_art,sim_art A:34,sim_art B:45</command>.</para>
 372         <para><command>simadb_cli --reciprocal --add_similarity=main_art,sim_art A:34,sim_art B:45</command></para>
 373         <para>main_art similar to sim_art A:34 and sim_art B:45<sbr />sim_art A  similar to main_art:34<sbr />sim_art B  similar to main_art:45</para>
 374         <para>Without the reciprocal option you would have add only the first similarity. Usually using the reciprocal option is the desired behavior, at least what users have in mind when thinking of similarity relation between to artists but keep in mind that it may lead to have MPD_sima more sensible to loop over the same two artist (ASSERTION TO BE CONFIRMED).</para>
 375     </refsect1>
 376     <!--
 377     <refsect1 id="diagnostics">
 378         <title>DIAGNOSTICS</title>
 379         <para>The following diagnostics may be issued
 380             on <filename class="devicefile">stderr</filename>:</para>
 381         <variablelist>
 382             <varlistentry>
 383                 <term><errortext>Bad configuration file. Exiting.</errortext></term>
 384                 <listitem>
 385                     <para>The configuration file seems to contain a broken configuration
 386                         line. Use the <option>-''-verbose</option> option, to get more info.
 387                     </para>
 388                 </listitem>
 389             </varlistentry>
 390         </variablelist>
 391         <para><command>&dhpackage;</command> provides some return codes, that can
 392             be used in scripts:</para>
 393         <segmentedlist>
 394             <segtitle>Code</segtitle>
 395             <segtitle>Diagnostic</segtitle>
 396             <seglistitem>
 397                 <seg><errorcode>0</errorcode></seg>
 398                 <seg>Program exited successfully.</seg>
 399             </seglistitem>
 400             <seglistitem>
 401                 <seg><errorcode>1</errorcode></seg>
 402                 <seg>The configuration file seems to be broken.</seg>
 403             </seglistitem>
 404         </segmentedlist>
 405     </refsect1>
 406     -->
 407   <xi:include href="feedback.xml" />
 408   <xi:include href="seealso.xml" />
 409 </refentry>