todos-0.4: 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 — описание записи. Все
поля кроме статуса и заголовка необязательны. В случае, если указана опция
«-w», поле статуса не читается. Описание отделяется от заголовка
не менее чем двумя пробелами.

С помощью разных отступов можно создавать вложенные записи. Кроме того,
зависимости интерпретируются также как вложенные записи; они позволяют
создавать не только дерево записей, но и произвольный граф, в том числе и с
циклами. В случае наличия циклов (когда задача 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 (заголовки записей — полужирным, некоторые статусы выделяются цветом)
-H, --highlight ::  подсвечивать подходящие записи, вместо того чтобы фильтровать их
-I, --show-ids :: показывать идентификаторы записей
-A, --prefix= ::    использовать альтернативный формат файлов, тут же указывается префикс
--dot :: вывести записи в виде графа для DOT (graphviz)
-D, --format ::   можно указать формат вывода записей (см. ниже)
-k, --indent-string :: использовать указанную строку для создания отступов, вместо двух пробелов
-w, --no-status ::  не читать поле статуса из файлов
--set-status=STRING :: установить статус всех TODO равным STRING
--set-root-status=STRING :: установить статусы корневых TODO равным STRING
-F, --by-file :: группировать записи по исходному файлу
-T, --by-tag  :: группировать записи по тегам
-Z, --by-status :: группировать записи по статусам
-p, --prune ::      ограничить максимальную высоту дерева (для каждой из отобранных записей будет показано не более чем N уровней вложенности)
-m, --min-depth ::  ограничить минимальную высоту дерева
-t, --tag ::        вывести только записи с заданным тегом и их вложенные записи
-g, --grep ::       искать по заголовкам записей
-G, --description :: искать по описаниям записей
-s, --status ::     искать по статусам записей
-i, --id ::  искать по идентификаторам записей
-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 недели или раньше (в т.ч. и в прошлом).

С указанной опцией «-H» записи не фильтруются совсем. Вместо этого те записи,
которые подходят под ваш запрос, будут подсвечены цветом (только с включённой
опцией «-c»).

Если указана опция «-I», перед каждой записью будет напечатан её идентификатор.
Идентификатор записи — это просто хэш от заголовка, описания, статуса, тегов и
описания; так что только одинаковые записи будут иметь одинаковые
идентификаторы. Можно попросить вывести только запись с данным идентификатором
при помощи опции «-i».

С помощью опции «-k» можно указать другую строку для формирования отступов при
выводе записей в консоль. По умолчанию используются два пробела. Попробуйте,
например, `todos -k"| "`. Опция «-k» без аргумента отключает формирование
отступов совсем.

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

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

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

С опцией «--dot» todos выведет на стандартный выход описание графа для DOT
(graphviz) вместо обычного вывода. Можно попробовать, например, так:

  todos --dot | dot -Tpng -o todos.png

и см. получившийся файл todos.png. Записи со статусом «GROUP» становятся
кластерами. Точнее говоря, если какая-то запись имеет статус «GROUP», она будет
отображаться как кластер, а все её дочерние записи будут находиться внутри
этого кластера. При этом есть одно ограничение, накладываемое DOT: DOT не умеет
правильно рисовать графы, в которых один узел находится сразу в нескольких
кластерах; в таких случаях узел будет нарисован только в одном кластере.

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

Кроме того, todos можно настраивать под себя «в стиле xmonad». Вы пишете файл
`~/.config/todos/todos.hs` и запускаете todos. todos компилирует и запускает
тот файл. Простейший возможный пример этого `todos.hs` — это файл `todos.hs` в
этой директории. Вот чуть более сложный пример:

.................................................................
    import System.Console.ANSI

    import Todos

    main :: IO ()
    main = todos $ defaultConfig {
                      itemConsoleColor = myItemColor
                   }

    myItemColor item =
      if itemStatus item == ":"
         then Just (Dull, Blue)
         else Nothing
.................................................................

Таким образом, записи со статусом «:» будут напечатаны синим цветом.