todos-0.1: README.ru

todos README
============
Ilya V. Portnov <portnov84@rambler.ru>

todos — это простой TODO-менеджер. Сами записи TODO описываются в простом
текстовом файле, а todos позволяет показывать из них только нужные, работая как
специализированная утилита grep. При этом формат вывода по умолчанию совпадает
с форматом входных файлов, поэтому вывод todos можно опять подавать на вход
todos через конвейер. Если входные файлы не указаны в командной строке,
читается файл TODO в текущей директории. Если вместо имени файла указано «-»,
читается стандартный ввод.

todos поддерживает два формата входных файлов. В первом случае файл содержит
только сами записи TODO и ничего больше. В «альтернативном» формате входные
файлы могут содержать произвольный текст, но он игнорируется, а читаются только
строки, начинающиеся с заданного префикса (по умолчанию TODO:), при этом формат
строки после префикса тот же, что в первом случае. Альтернативный формат
позволяет отбирать записи TODO из произвольных файлов, например исходных
текстов программы.

Формат записи TODO следующий:

    [spaces]status (dates) [TAGS] title (depends) description

Здесь [spaces] — это необязательный отступ пробелами, status — статус записи
(например URGENT или DONE, но может быть произвольным словом), dates —
информация о датах (см. ниже), TAGS — список тегов через пробел в квадратных
скобках, title — заголовок записи, depends — список зависимостей (заголовков
других записей) в скобках через запятую, description — описание записи. Все
поля кроме статуса и заголовка необязательны. Описание отделяется от заголовка
не менее чем двумя пробелами.

С помощью разных отступов можно создавать вложенные записи. Кроме того,
зависимости интерпретируются также как вложенные записи; они позволяют
создавать не только дерево записей, но и произвольный граф, в том числе и с
циклами. В случае наличия циклов (когда задача A зависит от B, а B — от A)
контроль за разумным выводом программы возлагается на пользователя (например,
можно ограничить высоту выводимого дерева опцией -p).

Информация о датах записывается в скобках, в виде не более чем трёх записей
через точку с запятой, каждая запись имеет вид «тип_даты: дата». Тип даты может
быть start, end, или deadline (предполагается, что так обозначаются
соответственно дата начала выполнения задачи, планируемая дата окончания и
дедлайн соответственно). Для дат поддерживается довольно много форматов;
например, «18 Feb», или «02/18/2010», и мн. др. Тут могут указываться и
относительные даты (вида «in 2 weeks», «2 days ago» или просто «tomorrow»), но
это имеет мало смысла — относительные даты считаются от момента запуска
программы.

Поддерживаются следующие опции командной строки:

-1, --only-first :: показывать только первую запись из всех, что должны быть показаны
-c, --color  ::     раскрашивать вывод todos (заголовки записей — полужирным, некоторые статусы выделяются цветом)
-A, --prefix= ::    использовать альтернативный формат файлов, тут же указывается префикс
-D, --describe ::   можно указать формат для выводимого описания (см. ниже)
-p, --prune ::      ограничить максимальную высоту дерева (для каждой из отобранных записей будет показано не более чем N уровней вложенности)
-m, --min-depth ::  ограничить минимальную высоту дерева
-t, --tag ::        вывести только записи с заданным тегом и их вложенные записи
-g, --grep ::       искать по заголовкам записей
-s, --status ::     искать по статусам записей
-a, --and ::        логическое И; например, todos -s! -a -tBUG — искать записи со статусом «!» и тегом «BUG»
-o, --or ::         логическое ИЛИ;
-n, --not ::        логическое НЕ;
-e, --exec ::       вместо того, чтобы показывать записи, для каждой записи выполнить заданную команду; в строке для команды можно использовать символы подстановки, см. ниже
-S, --start-date :: искать по дате начала
-E, --end-date  ::  искать по планируемой дате завершения
-d, --deadline  ::  искать по дедлайну
-h, --help ::       показать краткую справку по опциям командной строки

Даты в командной строке могут быть во всех тех же форматах, что и во входных
файлах. Тут как раз обычно более удобны относительные даты. Если указана дата в
прошлом, записи ищутся по признаку «больше или равно», например, todos
--deadline=yesterday будет искать записи с дедлайном вчера, сегодня или где
угодно в будущем. Если указана дата в будущем, записи ищутся по признаку
«меньше или равно»; например, todos --start-date="in 2 weeks" будет искать
записи с датой начала через 2 недели или раньше (в т.ч. и в прошлом).

Для опций --describe и --exec указываются строки формата с символами
подстановки в стиле printf. Поддерживаются следующие символы подстановки:

%n :: заменяется на заголовок записи
%t :: список тегов записи
%s :: статус записи
%d :: описание записи
%f :: имя файла, в котором встретилась запись
%l :: номер строки в файле, где встретилась запись

Например, todos -tBUG -e"vi %f +%l" для каждой записи с тегом BUG откроет vi на
строчке с этой записью.

todos может читать конфигурационные файлы: ~/.config/todos (глобальный) и
.todos.conf в текущей директории (локальный). Конфигурационные файлы содержат
ключи командной строки. «Эффективная командная строка» составляется как (ключи
в глобальном конфиге) + (ключи в локальном конфиге) + ключи в командной строке.
Если какого-то из конфигов нет, todos это проигнорирует.