docs/command_line.rst

   1
   2 Command-line scripts
   3 ====================
   4
   5
   6 .. contents::
   7    :local:
   8
   9
  10 ml-initdb.py
  11 ------------
  12
  13 Usage::
  14
  15     ml-initdb.py [-d]
  16
  17 Options::
  18
  19     -d, --database database  Open this database by pathname/db uri
  20
  21 Initialize database and import genres list. Isn’t really needed as
  22 the next script does all that too.
  23
  24
  25 ml-import.py
  26 ------------
  27
  28 Usage::
  29
  30     ml-import.py [-d] [file.inpx ...]
  31
  32 Options::
  33
  34     -d, --database database  Open this database by pathname/db uri
  35
  36 Initialize database, import genres list and import a list of INPX files
  37 listed in the command line. On subsequent runs doesn’t destroy DB or
  38 reimport genres; it also skips already import books but import new ones.
  39
  40
  41 ml-search.py
  42 ------------
  43
  44 Usage::
  45
  46     ml-search.py [-d] [-i] [-I] [-t] [-s] [-f] [-v] [-c] ...
  47
  48 Search through the database and display results. Currently can only
  49 search authors by name.
  50
  51 Global options::
  52
  53     -d, --database database  Open this database by pathname/db uri
  54     -i, --ignore-case        ignore case (default is to guess)
  55     -I, --case-sensitive     don’t ignore case
  56     -t, --start              search type: substring at the start
  57                              (this is the default)
  58     -s, --substring          search type: substring anywhere
  59     -f, --full               search type: match the full string
  60     -c, --count              Output count of found objects
  61     -v, --verbose            Output more details about found objects;
  62                              repeat for even more details
  63
  64 Options ``-i/-I`` cannot be used together as they are the opposite. In
  65 case none of them are used the program guesses case-sensitivity by
  66 looking at the arguments. If all arguments are lowercase the program
  67 performs case-insensitive search. If there are UPPERCASE or MixedCase
  68 arguments the program performs case-sensitive search.
  69
  70 Options ``-t/-s/-f`` define the search type. Search types are:
  71
  72 * start - search for substring at the start of the search field; for
  73   example searching for "duck" returns results for "duck" and "duckling"
  74   but not for "McDuck"; this is the default search type.
  75 * substring - search for any substring; "duck" => "duck", "duckling",
  76   "McDuck" (except for case-sensitive search, of course).
  77 * full - search for exact match, compare the entire strings;
  78   i.e. searching for "duck" returns results for "duck" but not for
  79   "duckling";
  80
  81
  82 Author search
  83 ^^^^^^^^^^^^^
  84
  85 Usage::
  86
  87     ml-search.py author [-s surname] [-n name] [-m misc-name] [--id id] [fullname]
  88
  89 Search and print a list of authors by surname/name/misc name/full name.
  90
  91 Options::
  92
  93     -s, --surname surname       Search by surname
  94     -n, --name name             Search by name
  95     -m, --misc-name misc. name  Search by misc. name
  96     --id id                     Search by database id
  97
  98 Example::
  99
 100     ml-search.py -i author -s duck
 101
 102 Search and print a list of authors whose surname starts with "duck",
 103 case insensitive.
 104
 105 If a few options are given the search is limited with operator AND.
 106 Example::
 107
 108     ml-search.py -i author -s duck -n mack
 109
 110 Search and print a list of authors whose surname starts with "duck" and
 111 name starts with "mack", case insensitive.
 112
 113 With one option `-v` it also prints database id.
 114
 115
 116 Book searching and downloading
 117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 118
 119 Usage::
 120
 121     ml-search.py books [-t title] [-s series] [-a archive] [-f file] [-p path] [--format f] [--get] [--get-many N] [--id id] [--surname name] [--name name] [--misc-name name] [--fullname name] [--aid aid] [-e ext] [--eid eid] [--gname name] [--gtitle title] [--gid gid] [-l lang] [--lid lid]
 122
 123 Search and print a list of books by title, series, archive or file name.
 124
 125 Options::
 126
 127     -t, --title title      Search by title
 128     -s, --series series    Search by series
 129     -a, --archive archive  Search by archive (zip file)
 130     -f, --file file        Search by file name (without extension)
 131     -p, --path path        Path to the directory with the library
 132                            archives
 133     --format format        Format of the downloaded file name
 134     --get                  Download exactly one book
 135     --get-many N           Download at most this many books
 136     --id id                Search by database id
 137     --surname surname      Search by author’s surname
 138     --name name            Search by author’s name
 139     --misc-name misc. name Search by author’s misc. name
 140     --fullname name        Search by author’s full name
 141     --aid aid              Search by author’s id
 142     -e, --ext ext          Search by file extension
 143     --eid eid              Search by extension’s id
 144     --gname name           Search by genre’s name
 145     --gtitle title         Search by genre’s title
 146     --gid gid              Search by genre’s id
 147     -l, --lang lang        Search by language
 148     --lid lid              Search by language’s id
 149
 150 By default the program prints only titles of the found book. With one
 151 option `-v` it also prints database id, the list of authors and genres,
 152 and also series the book belongs to (if any) and the serial number of
 153 the book in the series. With two options `-v` (`-v -v` or simply `-vv`)
 154 it also prints the file date and language. With three `-v` it prints
 155 archive name, file name, extension and size, and flag if the book is
 156 marked to be deleted.
 157
 158 Option `-p` provides the path to the directory with the library
 159 archives. By default the path is extracted from `m_librarian.conf`,
 160 section `[library]`, key `path`::
 161
 162     [library]
 163     path = /var/lib/archives
 164
 165 The option is useful for multiple databases (global option `-d`).
 166
 167 Option `--get` allows to download a book from the library to a local
 168 file. The option allows to download exactly one book. The simplest way
 169 to use it is via option `--id`. The file is downloaded into the current
 170 directory with the name from the library.
 171
 172 Configuration key
 173
 174 |    [download]
 175 |    format = %a/%s/%n %t
 176
 177 allows to set format for the download file pathname. Default format is
 178 `%f`, i.e. just filename. Other format specifiers are::
 179
 180     %a - author (one of if many)
 181     %e - file extension
 182     %f - file name in archive
 183     %G - genre (one of if many), name
 184     %g - genre (one of if many), title
 185     %l - language
 186     %n - series number (or 0)
 187     %s - series
 188     %t - title
 189
 190 Format must not end in directory separator (`/` or `\\`). If specifier
 191 `%e` (extension) is not found in the format it is appended
 192 unconditionally with a dot. That is, format `%f` is equivalent to
 193 `%f.%e`.
 194
 195 Option `--format format` allows to overwrite this configuration value.
 196
 197 Option `--get-many N` allows to download many books (at most N, where N
 198 is an integer). Options `--get-many N` and `--get` are, of course,
 199 mutually incompatible.
 200
 201
 202 Extension search
 203 ^^^^^^^^^^^^^^^^
 204
 205 Usage::
 206
 207     ml-search.py ext [name] [--id id]
 208
 209 Options::
 210
 211     --id id                Search by database id
 212
 213 Search and print a list of extensions by name.
 214
 215 With one option `-v` it also prints database id.
 216
 217
 218 Genres search
 219 ^^^^^^^^^^^^^
 220
 221 Usage::
 222
 223     ml-search.py genres [-n name] [-t title] [--id id]
 224
 225 Search and print a list of genres by name and title.
 226
 227 Options::
 228
 229     -n, --name name    Search by name
 230     -t, --title title  Search by title
 231     --id id            Search by database id
 232
 233 With one option `-v` it also prints database id.
 234
 235
 236 Language search
 237 ^^^^^^^^^^^^^^^
 238
 239 Usage::
 240
 241     ml-search.py lang [name] [--id id]
 242
 243 Search and print a list of languages by name.
 244
 245 Options::
 246
 247     --id id                Search by database id
 248
 249 With one option `-v` it also prints database id.
 250
 251 .. vim: set tw=72 :