feat: Update man

docs/baf.1.rst

@@ -2,66 +2,60 @@
 baf
 ===
 
-----------------------------------
+---------------------------
-backup automation micro-framework.
+backup files and databases.
-----------------------------------
+---------------------------
 
+:Author: ge
 :Copyright: \(C) 2022, ge <https://nixhacks.net/>, GPLv3+
+:Date: 2022 May 15
 :Manual section: 1
+:Version: baf 0.0.1
 
 Синопсис
 --------
 
-``baf`` [options] [<arguments>]
+``baf`` [-cvlhV] FILE..
 
 Описание
 --------
 
-Baf это утилита для резервного копирования на основе сценариев Bash. По умолчанию предусмотрено создание полных резервных копий файлов и баз данных MySQL и PostgreSQL, но функционал может быть расширен в сценариях при помощи пользовательских функций.
+Baf (Backup Automation Micro-framework) - это расширяемая утилита для резервного копирования на основе сценариев Bash. По умолчанию предусмотрено создание резервных копий файлов с помощью ``tar`` и дампов баз данных MySQL/MariaDB и PostgreSQL.
 
 Опции
 -----
 
--h, --help      print help text and exit.
+-c, --config    config file.
--v, --version   print version and exit.
+-v, --verbose   verbose output.
+-l, --log-file  log file.
+-h, --help      print this help messagea and exit.
+-V, --version   print version and exit.
 
-Основы
+Быстрый старт
-------
+-------------
 
-Baf это седство для полного резервного копирования и может быть использован как микро-фреймворк для написания сценариев резервного копирования.
+Baf можно рассматривать как небольшой фреймворк или библиотеку для создания сценариев резервного копирования. Baf не реализует собственный язык сценариев, а полагается на Bash. В любом варианте применения утилита требует написания сценария для выполнения бэкапа.
 
-Baf не реализует собственный язык сценариев, а полагается на Bash. В любом варианте применения Baf требует написания сценария для выполнения бэкапа.
+В сценариях можно использовать переменные и функции. Сценарий импортируется в основной скрипт с помощью команды ``source`` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS).
-
-В сценариях можно использовать переменные и функции. Сценарий импортируется Baf с помощью команды `source` (см. ``bash``\(1) п. SHELL BUILTIN COMMANDS).
 
 Простейший сценарий резервного копирования выглядит следующим образом::
 
     sources=('file:/home/user')
     targets=('file:/var/backup')
 
-Здесь массивы `sources` и `targets` определяют точки (`points`) резервного копирования — источники (`sources`) и назначения (`targets`). Это основные сущности, с которыми работает Baf. Вот некоторые особенности точек:
+Здесь массивы `sources` и `targets` определяют точки или поинты (`points`) резервного копирования — источники (`sources`) и назначения (`targets`). Это основные сущности, с которыми работает Baf. Вот некоторые особенности поинтов:
 
-- Все точки указываются в формате URI (см. RFC 3986). Описание URI также есть в этой документации ниже.ы
+- Все поинты указываются в формате URI. Описание URI также есть в этой документации ниже.
-- Точки могут указывать как на локальные (размещённые на текущей машине), так и на удалённые (размещённые на удалённой машине) ресурсы.
+- Поинты могут указывать как на локальные (размещённые на текущей машине), так и на удалённые (размещённые на удалённой машине) ресурсы.
 - Можно указать как несколько источников, так и несколько назначений.
 
 Для выполнения бэкапа директорий или отдельных файлов применяется схема URI `file`. В схеме `file` нельзя указать директорию, размещённую на удалённом хранилище (за исключением случая, когда удалённое хранилище примонтировано как файловая система), для этого используйте другие схемы. В примере выше будет выполнена резервная копия локальной директории /home/user в другую локальную директорию /var/backup. Поскольку в сценарии из примера нет ничего, кроме указания точек `sources` и `targets`, бэкап будет выполнен с параметрами по умолчанию: директория /home/user будет заархивирована с помощью утилиты ``tar``\(1), архив будет сжат с помощью утилиты ``gzip``\(1) и помещён в директорию /var/backup. Имя архива будет сложено из строки::
 
-    ${name_prefix}${name}_%Y%m%d-%H%M${file_ext}
+    ${name_prefix}${name}_${name_date_fmt}${name_ext}
 
-Здесь:
+Описание переменных см. в разделе ПЕРЕМЕННЫЕ. Пример имени файла:: 
 
-   ``${name_prefix}``
+    example.sh_example_20220515-0953.tar.gz
-        Переменная, значение которой соответствует имени файла сценария (без расширения).
-
-   ``${name}``
-        Имя архивируемой директории/файла (``basename``\(1)).
-
-   ``%Y%m%d-%H%M``
-        Дата, интерпретируемая утилитой ``date``\(1).
-
-   ``${file_ext}``
-        Расширение имени файла, соответствующее формату архива. По умолчанию ".tar.gz".
 
 Обзор URI
 ---------
@@ -70,7 +64,7 @@ Baf не реализует собственный язык сценариев,
 
     scheme:[//[username[:password]@]hostname[:port]]/[path]?[query]#[fragment]
 
-Парсер URI соответствует RFC 3986 не полностью - разбиение на составные части URI происходит верно, но интерпретация отдельных ситуаций может отличаться. См. примеры URI и реузультаты их интерпретации парсером в файле `tests/parse_uri.bats`. На практике рекомендую придерживаться примеров, которые приведены ниже и в файле `tests/parse_uri.bats`. В случае, если изменение логики парсера необходимо, вы можете прислать правки в pull-реквесте или завести feature-реквест в репозитории проекта.
+Парсер URI соответствует RFC 3986 не полностью - разбиение на составные части URI происходит верно, но интерпретация в отдельных ситуациях может отличаться. См. примеры URI и реузультаты их интерпретации парсером в файле `tests/parse_uri.bats`. На практике рекомендую придерживаться примеров, которые приведены ниже и в файле `tests/parse_uri.bats`. В случае, если изменение логики парсера необходимо, вы можете прислать правки в pull-реквесте или завести feature-реквест в репозитории проекта. На текущий момент компоненты `query` и `fragment` не используются.
 
 Примеры URI для массива `sources`::
 
@@ -86,7 +80,7 @@ Baf не реализует собственный язык сценариев,
     rsync://backup_user@192.168.3.12:2022/backups
     s3://my_bucket
 
-Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code.
+Пароли содержащие специальные символы недопустимые в URI (включая пробелы) необходимо закодировать в percent code. См. примеры кодирования строки на разных языках программирования ниже.
 
 Python 2::
 
@@ -102,7 +96,6 @@ Perl 5::
 
 Поддерживаемые протоколы и схемы URI
 ------------------------------------
-
 Схемы, которые могут быть использованы как sources
 ``````````````````````````````````````````````````
 
@@ -112,6 +105,10 @@ file
         file:/var/www/html
         file:///home/jhon/cool_stuff.txt
         
+    Не используйте двойной слэш для этой схемы, используйте один или три слэша. Двойной слэш означает наличие компонента Authority, это приводит к неверной интерпретации адреса. 
+    
+    См. также ``backup_files()``
+
 mysql
     URI содержит реквизиты для подключения к БД MySQL/MariaDB. Формат::
 
@@ -119,43 +116,53 @@ mysql
 
     С помощью утилиты ``mysqldump``\(1) формируется дамп в формате SQL, файл по умолчанию сжимается утилитой ``gzip``.
 
+    См. также ``backup_mysql()`` 
+
 postgres
-    Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1), файлы по умолчанию сохраняются с расширением ".psql.gz".
+    Аналогично `mysql`, но для PostgreSQL. Для создания дампа используется ``pg_dump``\(1), файлы по умолчанию сохраняются с расширением .psql.gz.
+
+    См. также ``backup_postgres()``
 
 sqlite
     Схема для баз данных SQLite. Ничем не отличается от `file`, добавлена для наглядного обозначения, что источником является БД SQLite, а не иной файл.
     
+    См. также ``backup_sqlite()``
+
 Схемы, которые могут быть использованы как targets
 ``````````````````````````````````````````````````
 
 file
-    См. описание выше. В контексте `targets` указывает директорию для сохранения архивов с файлами и базами данных.
+    В контексте `targets` указывает директорию для сохранения бэкапов. В массиве `targets` обязательно должен быть хотя бы один поинт со схемой `file`. Этот поинт будет использован как основной и сохранён в переменные ``__main_target`` (содержит URI) и ``__main_target_path`` (path). Если в массиве присутствует несколько поинтов со схемой `file`, то в качестве основного будет выбран первый по порядку поинт. Все бэкапы первоначально будут сохраняться в директорию ``__main_target_path`` и затем копироваться в другой таргет с помощью соответствующего обработчика. В случае копировани из одной директории в другую используется утилита ``cp``\(1).
+
+    Избегайте указания в одном сценарии таргетов, которые ведут одновременно на примонтированный к локальной машине сетевой диск и другое удалённое хранилище. В таком случае архивы будут создаваться на сетевом диске и далее снова копироваться по сети, что будет очень медленно.
+
+    См. также ``transfer_files()``
 
 ftp
-    Для выполнения загрузки файлов на удалённый FTP-сервер используется утилита GNU ``ftp``\(1).
+    Не реализовано.
 
 sftp
-    OpenSSH File Transfer Protocol.
+    Не реализовано.
 
 rsync
-    Rsync.
+    Не реализовано.
 
 s3
-    Amazon S3 or any S3-compatible storage.
+    Не реализовано.
 
 swift
-    OpenStack Swift.
+    Не реализовано.
 
 sj
-    Storj DCS.
+    Не реализовано.
 
 dav, davs
-    WebDAV.
+    Не реализовано.
 
 Создание резервных копий
 ------------------------
 
-Baf предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. Baf также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено в Baf по умолчанию.
+Baf предполагает, что для всех резервных копий необходимо создавать архивы. Поэтому вам нужно следить за тем, чтобы в локальном хранилище всегда хватало дискового пространства для создания новых архивов. Baf также не удаляет старые архивы и вам также надо позаботиться об удалении устаревших резервных копий. Изменить это поведение можно с помощью пользовательских функций в сценариях. В этом разделе речь пойдёт о поведении, которое установлено по умолчанию. См. функции ``builtin_backup()``, ``process_sources()``, ``process_targets()``.
 
 Базовая концепция строится на том, что существует несколько точек источников и несколько точек назначения. Создаётся резервная копия источника и копируется в точку назначения.
 
@@ -174,11 +181,6 @@ Baf предполагает, что для всех резервных копи
 
 Здесь будут созданы архивы файлов и базы данных и сохранены в локальную директорию /var/backup. Затем эти файлы будут переданы по протоколу FTP на сервер fe80::5054:ff:fe24:382 в директорию /backups. Файлы из директории /var/backup не будут удалены или перемещены. Если добавить дополнительную точку назначения, то файлы из /var/backup будут скопированы и туда. Обратите внимание, что Baf не выполняет повторного создания архивов для каждой точки назначения — архивы создаются один раз и далее распространяются по всем указанным назначениям. Если в массиве `targets` имеется несколько точек назначения со схемой `file`, то архивы будут сохранены в первую по порядку точку, а затем скопированы оттуда в остальные.
 
-Потребление ресурсов
---------------------
-
-Избегайте указания в одном сценарии точек назначения, которые ведут на примонтированный к локальной машине сетевой диск и другое удалённое хранилище одновременно. В таком случае архивы будут создаваться сразу на сетевом диске, что может существенно замедлить скорость их создания. Также при копировании файлов в другое удалённое хранилище будет выполняться двойная работа по сети, что тоже будет очень медленным.
-
 Резервное копирование на удалённое хранилище
 --------------------------------------------
 FTP
@@ -201,29 +203,175 @@ WebDAV
 ``````
 Переменные
 ----------
-Baf условно разделяет переменные на "внутренние" ("защищённые") и "общие". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "общими".
 
-Общие переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи общих переменных — в обоих случаях есть риск что-то поломать.
+Baf условно разделяет переменные на "внутренние" ("защищённые") и "обычные". К "защищённым" переменным относятся все перемеменные, имена которых начинаются с двух знаков подчёркивания, например: ``__main_target``. Все остальные переменные считаются "обычными".
 
-``__log_file``
+Обычные переменные могут быть перезаписаны в пользовательском скрипте. Защищённые переменные технически ничем от них не отличаются, однако не нужно переопределять такие переменные в пользовательском скрипте, так как это может привести к неожиданным ошибкам во время выполнения скрипта. Точно также очень внимательно нужно относится к перезаписи обычных переменных — в обоих случаях есть риск что-то поломать.
-    Путь до файла лога.
 
-``__main_target``
+``backups``
-    Главный `target` для хранения локальных резервных копий. Эта переменная содержит первый по порядку URI со схемой `file` из массива `targets`. Директория (`path`) из этой точки используется в качестве буфферной, если в `targets` указаны дополнительные точки.
+    Массив со списком созданных бэкапов. Содержит абсолютные пути к файлам. Заполняется функциями-обработчиками `sources`.
 
-``__source_handler``
+    Умолчание: ()
-    Содержит имя функции, которая будет обрабатывать URI из `sources`. 
 
-``__target_handler``
+``errors``
-    Аналогично ``__source_target``, но для `targets`.
+    Массив с текстами ошибок. Заполняется функцией ``err()`` с опцией ``-a``.
+
+    Умолчание: ()
+
+``log_date_fmt``
+    Формат даты в логе. См. ``date``\(1).
+
+    Умолчание: %d/%b/%Y:%H:%M:%S %z
+
+``name_prefix``
+    Префикс имени файла. Может быть задан в скрипте.
+
+    Умолчание: имя_скрипта\_
+
+``name``
+    Соответствует имени архивируемой директории/файла полученного из `path` с помощью утилиты ``basename``\(1).
+
+    Умолчание: нет
+
+``name_date_fmt``
+    Дата, интерпретируемая утилитой ``date``\(1).
+
+    Умолчание: _%Y%m%d-%H%M
+
+``name_ext``
+    Расширение имени файла, соответствующее формату архива.
+
+    Умолчание: .tar.gz
+
+``tar_options``
+    Опции ``tar``\(1).
+
+    Умолчание: -acf
+
+``tar_compression``
+    Работа этой фичи базируется на ``tar --auto-compress``. Переменная может принимать значения, в соответствии с табилцей ниже.
+
+    ======================== ================ ========
+    Значение tar_compression Расширение файла Утилита
+    ======================== ================ ========
+    gzip, gz                 .tar.gz          gzip
+    tgz                      .tgz             gzip
+    taz                      .taz             gzip
+    compress, Z              .tar.Z           compress
+    taZ                      .taZ             compress
+    bzip2, bz2               .tar.bz2         bzip2
+    tz2                      .tz2             bzip2
+    tbz2                     .tbz2            bzip2
+    tbz                      .tbz             bzip2
+    lzip, lz                 .tar.lz          lzip
+    lzma                     .tar.lzma        lzma
+    tlz                      .tlz             lzma
+    lzop, lzo                .tar.lzo         lzop
+    xz                       .tar.xz          xz
+    zstd, zst                .tar.zst         zstd
+    tzst                     .tzst            zstd
+    ======================== ================ ========
+
+    Если переменная имеет значение, отличное от перечисленныых, то будет использован ``gzip``.
 
 Функции
 -------
+
+``backup``
+    Пользовательская функция резервного копирования. Если она задана в скрипте, то вызывается вместо ``builtin_backup()``.
+
+``backup_files URI``
+    Архивация файлов с помощью ``tar``.
+
+``backup_mysql URI``
+    Не реализовано.
+
+``backup_postgres URI``
+    Не реализовано.
+
+``backup_sqlite URI``
+    Не реализовано.
+
+``builtin_backup``
+    Встроенная функция, запускает резервное копирвоание. Вызывает функции ``process_source()`` и ``process_target()``.
+
+``err [-eao] MESSAGE``
+    Печатает сообщение об ошибке MESSAGE на экран и в лог и выполняет обработку ошибок.
+    
+    -e  Выйти из скрипта с кодом выхода 1.
+    -a  Добавить сообщение MESSAGE в массив ``errors``.
+    -o  Вызвать функцию ``on_error()``.
+
+``finalise``
+    Пользовательская функция. Если задана, то запускается после функции ``backup()`` или ``builtin_backup()``.
+
+``gen_backup_name FILE_EXT``
+    Печатает полученное имя файла в STDOUT. Имя является выводом команды ``date`` и строки ``${prefix}${name}${date_fmt}${name_ext}``. См. переменные ``name_prefix``, ``name``, ``name_date_fmt``, ``name_ext``.
+
+``try COMMAND``
+    Функция выполняет команду COMMAND и в случае ненулевого кода выхода вызывает ``err() -eao``. Рекомендуется для использования в качестве враппера для команд правильное выполнение которых важно.
+
+``is_installed COMMAND``
+    Проверяет установлена ли программа COMMAND.
+
+``is_function_set FUNCTION``
+    Проверяет задана ли функция FUNCTION.
+
+``log [-p] MESSAGE``
+    Печатает лог в файл ``__log_file`` (лог задаётся опцией --log-file) и на экран, если указана опция ``-p``. Формат даты в логе можно изменить с помощью переменной ``log_date_fmt``.
+
+``on_error``
+    Пользовательская функция для обработки ошибок. Если задана, то запускается при обработке ошибки в функции ``err()`` с опцией ``-o``.
+
+``parse_uri URI``
+    Парсер URI. Задаёт переменные ``scheme``, ``username``, ``password``, ``hostname``, ``port``, ``path``, ``query``, ``fragment`` и выполняет декодинг пароля, если он закодирован в percent code.
+
+``prepare``
+    Пользовательская функция. Если задана, то запускается до функции ``backup()`` или ``builtin_backup()``.
+
+``process_source URI``
+    На основе схемы запускает соответсвующую функцию-обработчика.
+
+``process_target URI``
+    На основе схемы запускает соответсвующую функцию-обработчика.
+
+``source_script FILE``
+    Выполняет ``source`` пользовательского скрипта и проверяет его корректность. Проверяется синтаксис Bash, наличие непустых массивов `sources` и `targets`, наличие поинта `file` в `targets`. Во вспомогательной функции ``validate_targets()`` задаются значения переменных ``__main_target`` и ``__main_target_path``.
+
+``transfer_files URI``
+    Копирует файлы в новое назначение с помощью ``cp``.
+
+``transfer_ftp URI``
+    Не реализовано.
+
+``transfer_sftp URI``
+    Не реализовано.
+
+``transfer_rsync URI``
+    Не реализовано.
+
+``transfer_s3 URI``
+    Не реализовано.
+
+``transfer_sj URI``
+    Не реализовано.
+
+``transfer_swift URI``
+    Не реализовано.
+
+``transfer_dav URI``
+    Не реализовано.
+
+``transfer_davs URI``
+    Не реализовано.
+
 Использование функций в сценариях
 ---------------------------------
-See also
+Примеры
---------
+-------
+См. также
+---------
 
-``bash``\(1), ``tar``\(1), ``date``\(1), ``mysqldump``\(1), ``pg_dump``\(1)
+``bash``\(1), ``tar``\(1), ``cp``\(1), ``date``\(1), ``mysqldump``\(1), ``pg_dump``\(1)
 
 RFC 3986 https://datatracker.ietf.org/doc/html/rfc3986