Pass format of the downloaded file name in the command line

[m_librarian.git] / docs / command_line.rst

diff --git a/docs/command_line.rst b/docs/command_line.rst
index da05ed2ba537dd95ada4953d536d0b63eb2384b0..2196791d417609bb909f923a284b62cf7aac4b72 100644 (file)
--- a/docs/command_line.rst
+++ b/docs/command_line.rst
@@ -113,12 +113,12 @@ name starts with "mack", case insensitive.
 With one option `-v` it also prints database id.
 
 
-Book search
-^^^^^^^^^^^
+Book searching and downloading
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Usage::
 
-    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]
+    ml-search.py books [-t title] [-s series] [-a archive] [-f file] [-p path] [--format f] [--get] [--get-many N] [--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]
 
 Search and print a list of books by title, series, archive or file name.
 
@@ -128,6 +128,11 @@ Options::
     -s, --series series    Search by series
     -a, --archive archive  Search by archive (zip file)
     -f, --file file        Search by file name (without extension)
+    -p, --path path        Path to the directory with the library
+                           archives
+    --format format        Format of the downloaded file name
+    --get                  Download exactly one book
+    --get-many N           Download at most this many books
     --id id                Search by database id
     --surname surname      Search by author’s surname
     --name name            Search by author’s name
@@ -150,6 +155,49 @@ it also prints the file date and language. With three `-v` it prints
 archive name, file name, extension and size, and flag if the book is
 marked to be deleted.
 
+Option `-p` provides the path to the directory with the library
+archives. By default the path is extracted from `m_librarian.conf`,
+section `[library]`, key `path`::
+
+    [library]
+    path = /var/lib/archives
+
+The option is useful for multiple databases (global option `-d`).
+
+Option `--get` allows to download a book from the library to a local
+file. The option allows to download exactly one book. The simplest way
+to use it is via option `--id`. The file is downloaded into the current
+directory with the name from the library.
+
+Configuration key
+
+|    [download]
+|    format = %a/%s/%n %t
+
+allows to set format for the download file pathname. Default format is
+`%f`, i.e. just filename. Other format specifiers are::
+
+    %a - author (one of if many)
+    %e - file extension
+    %f - file name in archive
+    %G - genre (one of if many), name
+    %g - genre (one of if many), title
+    %l - language
+    %n - series number (or 0)
+    %s - series
+    %t - title
+
+Format must not end in directory separator (`/` or `\\`). If specifier
+`%e` (extension) is not found in the format it is appended
+unconditionally with a dot. That is, format `%f` is equivalent to
+`%f.%e`.
+
+Option `--format format` allows to overwrite this configuration value.
+
+Option `--get-many N` allows to download many books (at most N, where N
+is an integer). Options `--get-many N` and `--get` are, of course,
+mutually incompatible.
+
 
 Extension search
 ^^^^^^^^^^^^^^^^