pr2nntp 1.0.1 Manual

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

pr2nntp 1.0.1 Manual
1 Введение
- 1.1 Как работает гейт
2 Third party software
3 Конфигурирование
4 Параметры командной строки
5 Выявление неисправностей
6 Bugs
7 Автор

1 Введение

pr2nntp (Post RSS To NNTP) – гейт из RSS в группы новостей. Каждая entry преобразуется в письмо и постится в группу, по принципу одна RSS – одна группа.

1.1 Как работает гейт

Из конфигурационного файла читается список подписки RSS feeds.
Если необходимо, создаются соответствующие группы новостей, удаляются старые.
RSS скачиваются, каждая из них разбивается на письма и постится в соответствующую этой RSS группу новостей.

pr2nntp всю лишнюю работу старается сбросить на сторонние программы. Так, ей необходим NNTP сервер, утилита для скачивания файлов и конвертор из HTML в текст.

Если все проходит б.м. удачно, были обнаружены новые entries в RSS и отправлены в группы, pr2nntp возвращает 0 в конце работы, иначе что-то отличное от нуля.

2 Third party software

Правильный выбор компаньонов для pr2nntp позволит значительно улучшить и сделать приятнее ее работу.

2.1 NNTP сервер

Раз pr2nntp предполагает персональное использование, выбор хотелось бы остановить на небольшом и простом в настройке. К сожалению, большинство из таких серверов не очень хорошо управляются с командной строки, а pr2nntp требует некоторые действия (see Setup) исполнять в реальном времени (и именно посредством такого интерфейса).

В дальнейшем по этому руководству предполагает, что у вас установлен INN.

2.2 File downloader

В принципе, тут сгодится любой, часто именно тот, который идет в комплекте с вашей UNIX-like ОС. Для FreeBSD это будет fetch, для Linux, скорее всего, curl.

File downloader должен заканчивать свою работу возвращая exit status 0 если все прошло хорошо и >= 1 когда все плохо (в т.ч. когда был HTTP ответ 404/500/etc). Если это не выполняется, ждите веселых результатов.

2.3 Конвертор в текст

Условие выбора: программа должна уметь читать HTML в UTF8 (если RSS entries в этом формате) из файла и вываливать отфильтрованный результат в stdout в UTF-8. w3m работает хорошо. (elinks имеет некоторые проблемы с UTF8, например.)

3 Конфигурирование

pr2nntp ищет свою конфигурацию в файле ~/.pr2nntp/config, правда каталог можно изменить, если воспользоваться опцией ‘-c’ (see Invoking).

~/.pr2nntp/config – это обычный файл программы на языке Tcl. В этом файле предпологаются только установка переменных.

Каждый параметр pr2nntp – это 1 переменная. Бывает их 4 вида.

— Параметр: глобальный

Это такой параметр, который по умолчанию устанавливает свойство для всех RSS.

— Параметр: локальный

Это такой параметр, который может переопределять глобальный параметр для одной конкретной RSS.

— Параметр: обязательный R

Без этой переменной pr2nntp просто работать не будет.

— Параметр: необязательный O

pr2nntp в случаи отсутствия переменной возьмет какое-то свое значение по умолчанию.

Некоторые параметры поддерживают свой мини-язык, т.е. интерпретируют некоторую последовательность символов по своим правилам. Короткая спецификация:

‘%f’: Будет подставлено имя файла. Какого именно, это зависит от контекста переменной.
‘%g’: Имя группы новостей.
‘%m’: Message-ID.
‘%u’: URL.
‘%%’: Просто заменит на одиночный ‘%’.

Имейте ввиду, этот список не означает, что любая переменная с мини-языком будет это все анализировать; многим из них нужна только небольшая его часть.

Пример обозначений: ‘RM’ – обязательная переменная с поддержкой мини-языка, ‘O 524288’ – необязательная переменная (в случаи с ее отсутствием, будет взято значение по умолчанию ‘524288’).

3.1 Как подписаться на RSS

Для этого вам нужно заполнить хэш rss. Ничего сложного в этом нет. Например:

     set rss(comp.dragonfly_bsd_digest) {
     	url {http://www.shiningsilence.com/dbsdlog/category/lazy-reading/feed}
     }

‘comp.dragonfly_bsd_digest’ – будет имя группы новостей (без обязательного префикса, см. ниже). ‘url’ – локальный параметр этой конкретной RSS.

3.2 Глобальные параметры

— User Option: rss_conf(server.host) R

Имя хоста, где запущен NNTP сервер.

— User Option: rss_conf(server.port) R

Порт, который слушает NNTP сервер.

— User Option: rss_conf(server.login) O “”
— User Option: rss_conf(server.login) O “”

Логин и пароль для NNTP сервера.

— User Option: rss_conf(daemon.group.create) RM

Комманда, с помощью которой можно заставить NNTP сервер создать группу новостей. Например: sudo /usr/local/news/bin/ctlinnd newgroup %g y pr2nntp

— User Option: rss_conf(daemon.group.remove) RM

Комманда, с помощью которой можно заставить NNTP сервер удалить группу новостей. Например: sudo /usr/local/news/bin/ctlinnd rmgroup %g

— User Option: rss_conf(daemon.msg.cancel) RM

Комманда, с помощью которой можно заставить NNTP сервер удалить 1 пост. Например: sudo /usr/local/news/bin/ctlinnd cancel %m

— User Option: rss_conf(hierarchy) O rss

Префикс, который будет прибавляться к именам всех групп новостей, с которыми будет работать pr2nntp. Переменная не должна содержать оконечной точки.
Скажем, вы его установили в значение ‘rss’, тогда группа с именем test будет на самом деле на NNTP сервере названа rss.test. Это важный параметр. Хорошо подумайте перед тем, как его установить.

— User Option: rss_conf(size.max) O 4194304

Максимальный размер RSS, при достижении которого эта feed не будет анализироваться. Скачается она все равно, но анализироваться не будет. Установите переменную в значение ‘0’, если не хотите таких проверок.

— User Option: rss_conf(mail.mime) O 1

Способ конструирования писем. Когда переменная равна ‘1’, будет создано MIME multipart/alternative письмо, в котором будет и отфильтрованый от HTML текст и оригинал. Ваш newsreader должен автоматически выбрать наиболее подходящий для него вариант.
Когда переменная равна ‘0’, вы увидите только отфильтрованный текст (если rss_conf(filter.post) != “” ).

— User Option: rss_conf(mail.from) O “”

От кого письма идут в группы новостей. Это не почтовый адрес, а имя персоны или, скорее, робота. Впрочем, указанное вами имя будет игнорироваться, если в конкретной RSS будут т.н. person constructs, что крайне полезно, если вы читаете блог, в который пишут несколько человек (каждый под своим именем).

— User Option: rss_conf(fetch) RM

Программа, которая будет скачивать RSS. Например: curl -RfL --progress-bar --noproxy * -o %f %u

— User Option: rss_conf(filter.post) OM “”

Программа, которая конвертирует HTML в текст. Вывод в stdout этой программы обязан быть в UTF8. Например: w3m -T text/html -dump -I UTF-8 -O UTF-8 -cols 72 -no-graph %f

3.3 Локальные параметры

— User Option: url R

URI.

— User Option: fetch OM “”

Соответствует rss_conf(fetch).

— User Option: filter.post OM “”

Соответствует rss_conf(filter.post). Можно написать 1 символ ‘-’ вместо предполагаемой программы и тогда фильтрование будет запрещено.

4 Параметры командной строки

Синтаксис:

     pr2nntp [-vtfsRGTh] [-c directory] [-r regexp]

‘-v’: Делает программу более разговорчивой. По умолчанию, не выводятся никаких сообщений, кроме ошибок и предупреждений. Для максимальной разговорчивости “удваивайте” эту опцию: ‘-vv’.
‘-h’: Выводит табличкой список текущих RSS подписок с датой последнего обновления (прочерком, если в кеше такая RSS отсутствует) и URL, где лежит оригинал.
‘-t’: Вместо обычных своей занятий, заставляет программу сделать тестовый пост в тестовую группу новостей и на этом завершить работу.
‘-T’: Вместо обычных своей занятий, заставляет программу распарсить тестовую RSS, послать тестовых 3 письма в тестовую группу и на этом завершить работу.
‘-s’: После окончания своих занятий выводит статистику: сколько-де было скачано RSS, сколько не получилось, какой число новостей появилось в группах, какое было отвергнуто и т.д.
‘-f’: Вынуждает программу обрабатывать все подписанные RSS, даже если они не изменились на удаленном сервере.
‘-R’: Вынуждает программу не обновлять подписанные RSS, а брать их из кеша и пытаться запостить.
‘-G’: Вынуждает программу заново создать для подписанных RSS группы новостей на сервере NNTP. Полезно, если вы полностию очистили БД NNTP сервера или перенесли pr2nntp вместе с настройками на другую машину. Неплохо чувствует себя вместе с опцией ‘-R’.
‘-c directory’: Искать конфигурационный файл, кеш и проч. не в каталоге по умолчанию (~/.pr2nntp), а в заданном пользователем.
‘-r regexp’: Выбирает для обработки только те подписанные RSS, которые подпадают под регулярное выражение regexp. См. также re_syntax(n).
‘-V’: Показывает версию программы и легальные параметры.

5 Выявление неисправностей

Виновен NNTP сервер:

RSS не хочет гейтоватся, поскольку, сервер говорит, что новости от “слишком старые”! See RSS with quite old entries.
Если вы перейменовали в конфигурационном файле имя группы для RSS и хотите что-бы из кеша pr2nntp было все перенесенно в эту новую группу. К несчастию, это вот так сразу, не работает. See How to rename RSS.

Виновен File downloader:

RSS качаются, но pr2nntp ни черта не постит в группы!
Не постит, потому, что, за его данными, все новости уже в группе. Вы можете насильно заставить изменить свое мнение посредством опции ‘-f’.

Виновен конвертор из HTML в текст:

Если вы часто получаете ‘Filter return no output’ в теле письма, значит либо это “плохая” RSS, либо не очень удачный фильтр. Если ваш newsreader понимает HTML, попробуйте установить параметр rss_conf(mail.mime) в 1. See Setup.

5.1 Самотестирование

В pr2nntp встроены простые некоторые функции самотестирования и, когда программа настроена, правильно, то обязана их проходить все.

Каждый раз, когда вы запускаете pr2nntp, она пытается создать тестовую группу, послать туда сообщение и тут же удалить его. Только после такого теста pr2nntp начинает обновлять RSS и проч. Если вы просто хотите выполнить такую проверку и более ничего, воспользуйтесь опцией ‘-t’ (see Invoking).

Более серьезный тест, который одновременно даст вам некоторое представление в каком виде генерируются письма в группы новостей:

Берется нехитрая RSS (вам не нужно ее искать, она идет в комплекте с pr2nntp и та берет ее самостоятельно).
RSS парсится.
Генерируются 3 письма в тестовую группу с разными параметрами настройки. Эти параметры меняются виртуально, т.е. настоящая настройка пользователя остается нетронутой.

Такая проверка выполняется, если вызвать программу с опцией ‘-T’. pr2nntp сообщит вам, если тест провалился.

5.2 Как перейменовать RSS

Если у вас была группа foo.bar, в которой были сообщения с Message-ID A, B, C и вы перейменовали ее (группу) в bar.foo, то теперь вам необходимо вручную удалить письма c Message-ID A, B, C из (удаленной) группы foo.bar, иначе при попытке запостить их снова (уже в bar.foo), сервер будет упрямо говорить, что они ему не нужны

Так будет с INN, поскольку он, удаляя группу, не удаляет сообщения, которые в ней хранились.

Run something like

          pr2nntp -vvR -r foo.bar | grep 'is already on' | \
               sed -E 's/.*(<.*>).*/\1/g' | \
               xargs -L 1 sudo /usr/local/news/bin/ctlinnd cancel

Change ‘/remember/’ in expire.ctl to 0.
Run /usr/local/news/bin/expire.
Return ‘/remember/’ in expire.ctl to your default value.

5.3 RSS с весьма старыми записями

Подписавшись на новую RSS, вы случайно можете заметить, что некоторая часть entries в ней отторгается NNTP сервером. Визуально это выглядит так:

     Posting #22 of 25 <1160079136_shenderovich.livejournal.com+\
             17175.html@shenderovich.livejournal.com+data+rss>... \
             pr2nntp warning: NNTPERROR: 441 437 Too old – \
             "Thu, 05 Oct 2006 20:12:16 +0000"

Единственные выход из положения – подкрутить настройки NNTP сервера на прием более старых писем. Для INN смотрите переменную artcutoff в файле inn.conf.

6 Bugs

В случаи генерации писем в виде MIME multipart/alternative, pr2nntp ставит Content-Type text/plain и text/html. Поменять это нельзя.
Если генератор RSS – болван и неправильно указал кодировку, будет плохо.
Я писал pr2nntp 6 лет назад, а потом только исправлял баги. Сейчас бы я за такой код оторвал руки и пристрелил. Т.е. ее нужно переписать с 0.

О других найденных ошибках сообщайте на <alexander.gromnitsky.at.gmail.com> с пометочкой “pr2nntp bug” в поле Subject.

7 Автор

Alexander Gromnitsky <alexander.gromnitsky.at.gmail.com>.