docs/command_line.rst

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