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