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     -P, --path path        Path to the directory with the library
 150                            archives
 151     --download-to [path]   Download directory
 152     -F, --format format    Format of the downloaded file name
 153     --get                  Download exactly one book
 154     --get-many N           Download at most this many books
 155
 156 By default the program prints only titles of the found book. With one
 157 option `-v` it also prints database id, the list of authors and genres,
 158 and also series the book belongs to (if any) and the serial number of
 159 the book in the series. With two options `-v` (`-v -v` or simply `-vv`)
 160 it also prints the file date and language. With three `-v` it prints
 161 archive name, file name, extension and size, and flag if the book is
 162 marked to be deleted.
 163
 164 Option `-P` provides the path to the directory with the library
 165 archives. By default the path is extracted from configuration file,
 166 section `[library]`, key `path`::
 167
 168     [library]
 169     path = /var/lib/archives
 170
 171 The option is useful for multiple databases (global option `-D`).
 172
 173 Option `--download-to` provides the path to the download directory.
 174 By default the script downloads books to the current directory.
 175 If the option is used without `path` argument the path is extracted from
 176 configuration file, section `[download]`, key `path`::
 177
 178     [download]
 179     path = /tmp
 180
 181 Option `--get` allows to download a book from the library to a local
 182 file. The option allows to download exactly one book. The simplest way
 183 to use it is via option `--id`. The file is downloaded into the current
 184 directory with the name from the library.
 185
 186 Configuration key
 187
 188 |    [download]
 189 |    format = %a/%s/%n %t
 190
 191 allows to set format for the download file pathname. Default format is
 192 `%f`, i.e. just filename. Other format specifiers are::
 193
 194     %a - author (one of if many)
 195     %e - file extension
 196     %f - file name in archive
 197     %G - genre (one of if many), name
 198     %g - genre (one of if many), title
 199     %l - language
 200     %n - series number (or 0)
 201     %s - series
 202     %t - title
 203
 204 Format must not end in directory separator (`/` or `\\`). If specifier
 205 `%e` (extension) is not found in the format it is appended
 206 unconditionally with a dot. That is, format `%f` is equivalent to
 207 `%f.%e`.
 208
 209 Option `-F|--format format` allows to overwrite this configuration value.
 210
 211 Option `--get-many N` allows to download many books (at most N, where N
 212 is an integer). Options `--get-many N` and `--get` are, of course,
 213 mutually incompatible.
 214
 215
 216 Extension search
 217 ^^^^^^^^^^^^^^^^
 218
 219 Usage::
 220
 221     ml-search.py ext [name] [--id id]
 222
 223 Options::
 224
 225     --id id                Search by database id
 226
 227 Search and print a list of extensions by name.
 228
 229 With one option `-v` it also prints database id.
 230
 231
 232 Genres search
 233 ^^^^^^^^^^^^^
 234
 235 Usage::
 236
 237     ml-search.py genres [-n name] [-t title] [--id id]
 238
 239 Search and print a list of genres by name and title.
 240
 241 Options::
 242
 243     -n, --name name    Search by name
 244     -t, --title title  Search by title
 245     --id id            Search by database id
 246
 247 With one option `-v` it also prints database id.
 248
 249
 250 Language search
 251 ^^^^^^^^^^^^^^^
 252
 253 Usage::
 254
 255     ml-search.py lang [name] [--id id]
 256
 257 Search and print a list of languages by name.
 258
 259 Options::
 260
 261     --id id                Search by database id
 262
 263 With one option `-v` it also prints database id.
 264
 265
 266 ml-web.py
 267 ------------
 268
 269 Usage::
 270
 271     ml-web.py [-p port]
 272
 273 Options::
 274
 275     -p, --port port      HTTP port to listen to
 276
 277 Run a web server. If a port is given listens on the given port else
 278 chooses a random port. Starts a browser (or open a new window of a
 279 running browser) pointing it to the server.
 280
 281 If the program is already running the second instance detects the first
 282 one, starts a browser pointing to running instance and exits.
 283
 284 .. vim: set tw=72 :