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