نام (NAME)

r2e - دریافت خوراک‌های RSS از طریق ایمیل

خلاصه دستور (SYNOPSIS)

r2e [options] <command> [<args>]

توضیحات (DESCRIPTION)

r2e یک برنامه ساده است که می‌توانید آن را در crontab(5) خود اجرا کنید. این برنامه خوراک‌های RSS را پایش می‌کند و برای هر مورد جدید، یک پیام ایمیل با قالب‌بندی مناسب برای شما می‌فرستد.

برای شروع سریع با r2e این مراحل را امتحان کنید:

r2e new your@yourdomain.com
r2e add feedname http://feed.url/somewhere.rss
r2e run

اگر می‌خواهید موارد به‌طور خودکار برای شما ارسال شوند، در نهایت باید دستور آخر در crontab شما قرار داده شود.

گزینه‌ها (OPTIONS)

-h, --help: نمایش راهنمای rss2email و خروج.
-v, --version: نمایش نسخه rss2email و خروج.
--full-version: نمایش نسخه Python، کامپایلر استفاده‌شده برای کامپایل Python و بسته‌های استفاده‌شده توسط rss2email.
-c, --config <path>: پیکربندی برنامه به‌طور پیش‌فرض از $XDG_CONFIG_HOME/rss2mail.cfg خوانده می‌شود (همچنین بخش‌های FILES و ENVIRONMENT VARIABLES را در زیر ببینید). از این گزینه برای تنظیم یک فایل پیکربندی متفاوت استفاده کنید.
-d, --data <path>: داده‌های پویای برنامه به‌طور پیش‌فرض از $XDG_DATA_HOME/rss2mail.json خوانده می‌شود (همچنین بخش‌های FILES و ENVIRONMENT VARIABLES را در زیر ببینید). از این گزینه برای تنظیم یک فایل داده متفاوت استفاده کنید.
-V, --verbose: افزایش سطح پرگویی گزارش‌ها.

دستورها (COMMANDS)

new [<email>]: ایجاد یک پایگاه‌داده جدید برای خوراک‌ها. اگر آرگومان <email> داده شود، نشانی ایمیل پیش‌فرضی را تنظیم می‌کند که ایمیل‌ها به آن ارسال می‌شوند.
email [<email>]: به‌روزرسانی نشانی ایمیل مقصد پیش‌فرض به <email>.
add [--only-new] <name> <url> [<email>]: اشتراک در یک خوراک. آرگومان <name> نامی را برای استفاده‌های بعدی به خوراک اختصاص می‌دهد. <url> نشانی اینترنتی خوراک است. آرگومان اختیاری <email> نشانی ایمیلی است که موارد جدید به آن ارسال می‌شوند و جایگزین نشانی پیش‌فرض برای این خوراک خاص می‌شود. این کار را برای هر خوراکی که می‌خواهید در آن مشترک شوید تکرار کنید.

گزینه --only-new خوراک را در زمان افزودن بدون ارسال ورودی‌ها واکشی می‌کند، به‌طوری که اجرای بعدی run آن‌ها را از قبل ارسال‌شده در نظر می‌گیرد. این گزینه زمانی باید استفاده شود که فرد فقط به ورودی‌هایی علاقه‌مند است که در زمان اجرای add هنوز در خوراک وجود ندارند.

run [--no-send] [--clean] [<index> [<index> ...]]: پویش خوراک‌ها و ارسال ایمیل برای موارد جدید. این دستور می‌تواند در یک کار cron اجرا شود.

گزینه --no-send از ارسال هرگونه ایمیل توسط r2e جلوگیری می‌کند. این کار می‌تواند در اولین باری که آن را اجرا می‌کنید مفید باشد، زیرا در غیر این صورت برای هر ورودی موجود در خوراک یک ایمیل ارسال خواهد شد.

گزینه --clean با حذف ورودی‌های قدیمی، اندازه پایگاه‌داده را کاهش می‌دهد. این گزینه دانلود اجباری خوراک‌های انتخاب‌شده یا تمام خوراک‌ها را اعمال می‌کند، و فقط باید به‌صورت هفتگی یا ماهانه استفاده شود.

اگر یک <index> مشخص شود، r2e فقط آن خوراک را دانلود خواهد کرد. <index> می‌تواند نام خوراک (تنظیم‌شده توسط add) یا نمایه خوراک (نمایش‌داده‌شده توسط list) باشد.

list: فهرست کردن تمام خوراک‌های موجود در پایگاه‌داده.
pause [<index> [<index> ...]]: مکث در خوراک‌ها (غیرفعال کردن واکشی). گزینه <index> خوراک(ها) را برای مکث انتخاب می‌کند (برای مقادیر ممکن به run مراجعه کنید). اگر هیچ <index> داده نشود، همه خوراک‌ها به حالت مکث درمی‌آیند.
unpause [<index> [<index> ...]]: خروج خوراک‌ها از حالت مکث (فعال کردن واکشی).
delete <index> [<index> [<index> ...]]: حذف یک یا چند خوراک از پایگاه‌داده. گزینه <index> خوراک(ها) را برای حذف انتخاب می‌کند (برای مقادیر ممکن به run مراجعه کنید).
reset [<index> [<index> ...]]: فراموش کردن داده‌های پویای خوراک (مثلاً برای ارسال مجدد ورودی‌های قدیمی). گزینه <index> خوراک(ها) را برای بازنشانی انتخاب می‌کند (برای مقادیر ممکن به run مراجعه کنید). اگر هیچ <index> داده نشود، همه خوراک‌ها بازنشانی می‌شوند.
opmlimport [<path>]: وارد کردن خوراک‌های جدید از OPML. مقدار <path> فایلی است که داده‌های OPML از آن خوانده می‌شوند. اگر <path> داده نشود، r2e داده‌ها را از stdin می‌خواند.
opmlexport [<path>]: صادر کردن تمام خوراک‌ها به OPML. مقدار <path> فایلی است که داده‌های OPML در آن نوشته خواهند شد. اگر <path> داده نشود، r2e داده‌ها را در stdout می‌نویسد..SH "پیکربندی (CONFIGURATION)" رفتار این برنامه را می‌توان از طریق $XDG_CONFIG_HOME/rss2email.cfg کنترل کرد (همچنین بخش‌های فایل‌ها (FILES) و متغیرهای محیطی (ENVIRONMENT VARIABLES) را در زیر ببینید). قالب این فایل مشابه فایل‌های INI مایکروسافت ویندوز است. این فایل توسط کلاس ConfigParser پایتون تجزیه می‌شود، بنابراین برای جزئیات قالب به مستندات پایتون در http://docs.python.org/3/library/configparser.html مراجعه کنید.

فایل پیکربندی، تنظیمات عمومی (اعمال‌شده بر روی تمام فیدها) را در بخش [DEFAULT] ذخیره می‌کند. دستور new یک فایل پیکربندی برای شما می‌سازد که می‌توانید آن را به دلخواه ویرایش کنید. دستور add بخش‌های مربوط به فیدهای خاص را اضافه می‌کند. برای بازنویسی هر تنظیمی برای همهٔ فیدها، مقدار آن را در بخش [DEFAULT] تغییر دهید. برای بازنویسی یک تنظیم برای فیدی خاص، آن تنظیم را به بخش ویژهٔ همان فید اضافه کنید. در اینجا نمونه‌ای برای بازنویسی use-publisher-email و name-format برای فید feedname آورده شده است.

[DEFAULT]
from = user@rss2email.invalid
force-from = False
use-publisher-email = False
name-format = {feed-title}: {author}
  ...
verbose = warning
[feed.feedname]
url = http://feed.url/somewhere.rss
use-publisher-email = True
name-format = {author} ({feed.title})

می‌توانید موارد زیر را پیکربندی کنید:

نشانی‌دهی (Addressing)

from: نشانی ایمیلی که پیام‌ها به‌طور پیش‌فرض از آن فرستاده می‌شوند
use-8bit: تنظیمات Transfer-Encoding. برای ارسال ایمیل به‌صورت محلی، استفاده از 8bit امن و راحت است.
force-from: مقدار True: تنها از نشانی 'from' استفاده کند. مقدار False: در صورت امکان از نشانی ایمیل مشخص‌شده توسط فید استفاده کند.
use-publisher-email: مقدار True: اگر ایمیل نویسنده یافت نشد، از ایمیل ناشر استفاده کند. مقدار False: به‌جای آن فقط از ایمیل 'from' استفاده کند.
name-format: در صورت خالی بودن، به‌جای نام خوانا به‌همراه نشانی ایمیل، تنها از نشانی ایمیل فید استفاده می‌کند. صفت‌های در دسترس ممکن است شامل 'feed'، 'feed-name'، 'feed-url'، 'feed-title'، 'author' و 'publisher' باشند، اما تنها وجود 'feed'، 'feed-name' و 'feed-url' تضمین شده است.
to: این گزینه را برابر نشانی‌های ایمیل پیش‌فرض To (گیرنده) قرار دهید.

دریافت (Fetching)

proxy: تنظیم یک پراکسی HTTP (مانند 'http://your.proxy.here:8080')
feed-timeout: تنظیم مهلت زمانی (به ثانیه) برای دریافت پاسخ از سرور فید

پردازش (Processing)

active: مقدار True: دریافت، پردازش و ارسال فیدها از طریق ایمیل. مقدار False: فیدها را دریافت، پردازش یا ایمیل نکند.
digest: مقدار True: در هر بار اجرای rss2email، برای هر فید یک ایمیل تجمیعی واحد شامل چندین ورودی ارسال کند. مقدار False: به ازای هر ورودی یک ایمیل جداگانه بفرستد.
digest-type: نوع Content-Type پیام برای ایمیل‌های تجمیعی. مقادیر معتبر شامل 'multipart/digest' و 'multipart/mixed' هستند. مورد اول پیش‌فرض است، اما بسیاری از برنامه‌های کاربری ایمیل از آن پشتیبانی نمی‌کنند.
date-header: مقدار True: در صورت امکان، هدر Date را بر اساس تاریخ ورودی تولید کند. مقدار False: هدر Date را بر اساس زمان ارسال ایجاد کند.
date-header-order: فهرستی جداشده با کاما از ترکیبی از موارد ('issued', 'created', 'modified', 'expired') که ترتیب اولویت تاریخ‌ها را برای استفاده در هدر Date ایمیل مشخص می‌کند.
bonus-header: تنظیم این گزینه برای افزودن هدرهای اضافی به تمامی ایمیل‌ها مثال: bonus-header = 'Approved: joe@bob.org'
trust-guid: مقدار True: به ازای هر پست، یک ایمیل دریافت شود. مقدار False: با هر بار تغییر یک پست، یک ایمیل دریافت شود.
trust-link: مقدار True: به ازای هر پیوند یکتای url، یک ایمیل دریافت شود. مقدار False: بر اساس اولویت تنظیم trust-guid عمل کند. تغییر این گزینه برای فیدهای موجود ممکن است منجر به دریافت موارد تکراری شود، زیرا ورودی‌های قدیمی تحت شناسه‌های جدید مبتنی بر پیوندشان ثبت نخواهند شد.
encodings: برای کدگذاری دقیق‌تر ایمیل‌های حاوی نویسه‌های بین‌المللی، فهرست زیر پیمایش شده و از نخستین مجموعه نویسه (character set) کارآمد استفاده می‌شود.
post-process: قلاب‌های پردازشی کاربر. به فاصلهٔ پس از نام ماژول دقت کنید. مثال: post-process = 'rss2email.post_process.downcase downcase_message'
digest-post-process: قلاب‌های پردازشی کاربر برای پیام‌های تجمیعی (digest). اگر 'digest' فعال باشد، قلاب معمول 'post-process' پیام‌های مربوط به هر ورودی را پردازش می‌کند، اما این قلاب پیش از ارسال، همراه با کل پیام تجمیعی فراخوانی می‌شود. مثال: digest-post-process = 'rss2email.post_process.downcase downcase_message'
subject-format: قالب خط موضوع (Subject). صفت‌های در دسترس عبارتند از 'feed'، 'feed-name'، 'feed-url' و 'feed-title'.

تبدیل اچ‌تی‌ام‌ال (HTML conversion)

html-mail: مقدار True: در صورت امکان، پیام‌ها با قالب text/html ارسال شوند. مقدار False: تبدیل HTML به متن ساده (plain text).
use-css: استفاده از CSS
css: استایل‌دهی اختیاری CSS
unicode-snob: استفاده از نویسه‌های یونیکد (Unicode) به‌جای معادل‌های شبه‌اسکی (ascii) آن‌ها.
links-after-each-paragraph: قرار دادن پیوندها پس از هر بند به‌جای قرار دادن آن‌ها در انتها.
inline-links: استفاده از قالب‌بندی درون‌خطی (inline) به‌جای مرجع (reference) برای تصاویر و پیوندها.
wrap-links: شکستن خطوط پیوندها بر اساس عرض متن.
body-width: شکستن خطوط طولانی در موقعیت مشخص‌شده. هر مقدار منفی برای غیرفعال کردن شکستن خطوط، 0 برای عرض 78 (جهت سازگاری)، یا هر عرض مثبت دیگر.

ارسال ایمیل

email-protocol: انتخاب پروتکل از میان: sendmail، smtp، imap، maildir
sendmail: مسیر sendmail (یا موارد سازگار با آن)

پیکربندی SMTP

smtp-auth: تنظیم روی True برای استفاده از SMTP AUTH
smtp-username: نام کاربری برای SMTP AUTH
smtp-password: گذرواژه برای SMTP AUTH
smtp-server: سرور SMTP
smtp-ssl: اتصال به سرور SMTP با استفاده از SSL

پیکربندی IMAP

imap-auth: تنظیم روی True برای استفاده از احراز هویت IMAP.
imap-username: نام کاربری برای احراز هویت IMAP
imap-password: گذرواژه برای احراز هویت IMAP
imap-server: سرور IMAP
imap-port: درگاه (پورت) IMAP
imap-ssl: اتصال به سرور IMAP با استفاده از SSL
imap-mailbox: جایی که پیام‌های جدید باید در آن ذخیره شوند

پیکربندی Maildir

maildir-path: مسیر maildir برای نوشتن پیام‌ها در آن
maildir-mailbox: صندوق پستی (mailbox) درون maildir-path برای نوشتن پیام‌ها در آن

متفرقه

user-agent: رشته‌ای که به عنوان HTTP User-Agent در درخواست‌های وب و به عنوان سرایند User-Agent در ایمیل‌های خروجی استفاده می‌شود. در صورت وجود، __VERSION__ و __URL__ با شماره نسخه و وب‌سایت rss2email جایگزین می‌شوند.
verbose: میزان پرگویی (یکی از 'error'، 'warning'، 'info' یا 'debug').

فایل‌ها (FILES)

$XDG_CONFIG_HOME/rss2email.cfg: اگر این فایل وجود داشته باشد، برای پیکربندی برنامه خوانده می‌شود.
$XDG_DATA_HOME/rss2email.json: پایگاه داده فیدها. برای افزودن، حذف یا تغییر فیدها از r2e استفاده کنید؛ آن را مستقیماً ویرایش نکنید.

متغیرهای محیطی (ENVIRONMENT VARIABLES)

تمام متغیرهای محیطی استفاده‌شده توسط r2e در «مشخصات دایرکتوری پایه XDG» (XDG Base Directory Specification) تعریف شده‌اند که هدف آن استانداردسازی مکان فایل‌های پیکربندی و داده‌های مخصوص کاربر است.

XDG_CONFIG_HOME: دایرکتوری ترجیحی برای فایل‌های پیکربندی. پیش‌فرض آن $HOME/.config است.
XDG_DATA_HOME: دایرکتوری ترجیحی برای فایل‌های داده. پیش‌فرض آن $HOME/.local/share است.
XDG_RUNTIME_DIR: دایرکتوری ترجیحی برای فایل‌های قفل (lockfiles). پیش‌فرض آن /tmp/rss2email-UID است.
XDG_CONFIG_DIRS: فهرستی از دایرکتوری‌های پایه برای فایل‌های پیکربندی علاوه بر $XDG_CONFIG_HOME که با دونقطه «:» از هم جدا شده و بر اساس اولویت مرتب شده‌اند. پیش‌فرض آن /etc/xdg است. اگر چندین فایل پیکربندی در این مسیر یافت شود، همگی توسط کلاس ConfigParser خوانده خواهند شد (بخش CONFIGURATION در بالا را نیز ببینید).
XDG_DATA_DIRS: فهرستی از دایرکتوری‌های پایه برای فایل‌های داده که با دونقطه «:» از هم جدا شده و بر اساس اولویت مرتب شده‌اند. پیش‌فرض آن /usr/local/share/:/usr/share/ است. تنها از نخستین فایل منطبق استفاده می‌شود.

نویسندگان (AUTHORS)

پروژه rss2email توسط Aaron Swartz آغاز شد و هم‌اکنون توسط گروهی از افراد نگه‌داری می‌شود. برای مشاهده فهرست کامل‌تری از مشارکت‌کنندگان، فایل AUTHORS را در توزیع rss2email ببینید.

گزارش باگ‌ها (REPORTING BUGS)

گزارش باگ‌ها با ایجاد یک issue در: https://github.com/rss2email/rss2email.