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