X-Git-Url: http://git.tremily.us/?p=rss2email.git;a=blobdiff_plain;f=r2e.1;h=07e8e501602714228821e96e3aa7c2149e200045;hp=4cd9baade6f342a9b7443882c22be75aff3e7967;hb=a97a8f0c9f50d98bd03c674b934ccadfe5064d7e;hpb=6675198ded779bf5e381f92f72987539a6de7117

diff --git a/r2e.1 b/r2e.1
index 4cd9baa..07e8e50 100644
--- a/r2e.1
+++ b/r2e.1
@@ -29,12 +29,14 @@ Print the rss2email help and exit.
 Print the rss2email version and exit.
 .TP
 \-c, \-\-config \fI<path>\fR
-The program is configured by ~/\&.config/rss2mail/config by
-default. Use this option to set a different config file.
+The program configuration is read from $XDG_CONFIG_HOME/rss2mail.cfg
+by default (see also FILES and ENVIRONMENT VARIABLES below).  Use this
+option to set a different configuration file.
 .TP
 \-d, \-\-data \fI<path>\fR
-The program is configured by ~/\&.config/rss2mail/config by
-default. Use this option to set a different config file.
+Dynamic program data is read from $XDG_DATA_HOME/rss2mail\&.json by
+default (see also FILES and ENVIRONMENT VARIABLES below).  Use this
+option to set a different data file.
 .TP
 \-V, \-\-verbose
 Increment the logging verbosity.
@@ -99,10 +101,11 @@ data will be written.  If \fI<path>\fR is not given \fBr2e\fR writes
 the data to stdout.
 .SH "CONFIGURATION"
 The program's behavior can be controlled via the
-~/.config/rss2email/config file. The file format is similar to a
-Microsoft Windows INI file.  It is parsed by Python's ConfigParser
-class, so see the Python documentation at
-http://docs\&.python\&.org/py3k/library/configparser\&.html for format
+$XDG_CONFIG_HOME/rss2email.cfg (see also FILES and ENVIRONMENT
+VARIABLES below). The file format is similar to a Microsoft Windows
+INI file.  It is parsed by Python's ConfigParser class, so see the
+Python documentation at
+http://docs\&.python\&.org/3/library/configparser\&.html for format
 details.
 .P
 The config file stores general configuration (applied to all feeds) in
@@ -112,7 +115,7 @@ configuration file for you, which you can edit as you see fit.  The
 setting for all feeds, change the value in the \fB[DEFAULT]\fR
 section.  To override a setting for a particular feed, add that
 setting to the feed-specific section.  Here is an example overriding
-\fBuse-publisher-email\fR and \fBfriendly-name\fR for the
+\fBuse-publisher-email\fR and \fBname-format\fR for the
 \fBfeedname\fR feed.
 .P
 .RS 4
@@ -121,28 +124,188 @@ setting to the feed-specific section.  Here is an example overriding
 from = user@rss2email.invalid
 force-from = False
 use-publisher-email = False
-friendly-name = True
-...
+name-format = {feed-title}: {author}
+  .\|.\|.
 verbose = warning
 
 [feed.feedname]
 url = http://feed.url/somewhere.rss
 use-publisher-email = True
-friendly-name = False
+name-format = {author} ({feed.title})
+.RE
+.P
+You can configure the following items:
+.SS Addressing
+.RS
+.IP from
+The email address messages are from by default
+.IP use-8bit
+Transfer-Encoding. For local mailing it is safe and
+convenient to use 8bit.
+.IP force-from
+True: Only use the 'from' address.
+False: Use the email address specified by the feed, when possible.
+.IP use-publisher-email
+True: Use the publisher's email if you can't find the author's.
+False: Just use the 'from' email instead.
+.IP name-format
+If empty, only use the feed email address rather than
+friendly name plus email address.  Available attributes may
+include 'feed', 'feed-title', 'author', and 'publisher', but
+only 'feed' is guaranteed.
+.IP to
+Set this to default To email addresses.
+.RE
+.SS Fetching
+.RS
+.IP proxy
+Set an HTTP proxy (e.g. 'http://your.proxy.here:8080/')
+.IP feed-timeout
+Set the timeout (in seconds) for feed server response
+.RE
+.SS Processing
+.RS
+.IP active
+True: Fetch, process, and email feeds.
+False: Don't fetch, process, or email feeds
+.IP digest
+True: Send a single, multi-entry email per feed per rss2email run.
+False: Send a single email per entry.
+.IP date-header
+True: Generate Date header based on item's date, when possible.
+False: Generate Date header based on time sent.
+.IP date-header-order
+A comma-delimited list of some combination of
+('issued', 'created', 'modified', 'expired')
+expressing ordered list of preference in dates
+to use for the Date header of the email.
+.IP bonus-header
+Set this to add bonus headers to all emails
+Example: bonus-header = 'Approved: joe@bob.org'
+.IP trust-guid
+True: Receive one email per post.
+False: Receive an email every time a post changes.
+.IP trust-link
+True: Receive one email per unique link url.
+False: Defer to trust-guid preference.
+Toggling this for existing feeds may result in duplicates,
+because the old entries will not be recorded under their new
+link-based ids.
+.IP encodings
+To most correctly encode emails with international
+characters, we iterate through the list below and use the
+first character set that works.
+.IP post-process
+User processing hooks.  Note the space after the module name.
+Example: post-process = 'rss2email.post_process.downcase downcase_message'
+.IP digest-post-process
+User processing hooks for digest messages.  If 'digest' is
+enabled, the usual 'post-process' hook gets to message the
+per-entry messages, but this hook is called with the full
+digest message before it is mailed.
+Example: digest-post-process = 'rss2email.post_process.downcase downcase_message'
+.RE
+.SS HTML conversion
+.RS
+.IP html-mail
+True: Send text/html messages when possible.
+False: Convert HTML to plain text.
+.IP use-css
+Use CSS
+.IP css
+Optional CSS styling
+.RE
+.SS html2text options
+.RS
+.IP unicode-snob
+Use Unicode characters instead of their ascii psuedo-replacements
+.IP links-after-each-paragraph
+Put the links after each paragraph instead of at the end.
+.IP body-width
+Wrap long lines at position. 0 for no wrapping.
+.RE
+.SS Mailing
+.RS
+.IP email-protocol
+Select protocol from: sendmail, smtp, imap
+.IP sendmail
+Path to sendmail (or compatible)
+.RE
+.SS SMTP configuration
+.RS
+.IP smtp-auth
+Set to True to use SMTP AUTH
+.IP smtp-username
+username for SMTP AUTH
+.IP smtp-password
+password for SMTP AUTH
+.IP smtp-server
+SMTP server
+.IP smtp-ssl
+Connect to the SMTP server using SSL
+.IP smtp-ssl-protocol
+TLS/SSL version to use on STARTTLS when not using 'smtp-ssl'.
+.RE
+.SS IMAP configuration
+.RS
+.IP imap-auth
+set to True to use IMAP auth.
+
+.IP imap-username
+username for IMAP authentication
+.IP imap-password
+password for IMAP authentication
+.IP imap-server
+IMAP server
+.IP imap-port
+IMAP port
+.IP imap-ssl
+connect to the IMAP server using SSL
+.IP imap-mailbox
+where we should store new messages
+.RE
+.SS Miscellaneous
+.RS
+.IP verbose
+Verbosity (one of 'error', 'warning', 'info', or 'debug').
 .RE
 .P
 .SH FILES
+.TP 4
+.B $XDG_CONFIG_HOME/rss2email.cfg
+If this file exists, it it read to configure the program.
 .TP
-.B ~/.rss2email/feeds\&.dat
+.B $XDG_DATA_HOME/rss2email\&.json
 The database of feeds. Use \fBr2e\fR to add, remove, or modify feeds,
 do not edit it directly.
+.SH "ENVIRONMENT VARIABLES"
+The environment variables used by \fBr2e\fR are all defined in the XDG
+Base Directory Specification, which aims to standardize locations for
+user-specific configuration and data files.
+.TP 4
+.B XDG_CONFIG_HOME
+The preferred directory for configuration files.  Defaults to
+$HOME/\&.config.
 .TP
-.B ~/.rss2email/config\&.py
-If this file exists, it it read to configure the program.
+.B XDG_DATA_HOME
+The preferred directory for data files.  Defaults to
+$HOME/\&.local/share.
+.TP
+.B XDG_CONFIG_DIRS
+A colon ':' separated, preference ordered list of base directories for
+configuration files in addition to $XDG_CONFIG_HOME.  Defaults to
+/etc/xdg.  If multiple configuration files are found in this path,
+they will all be read by the ConfigParser class (see also
+CONFIGURATION above).
+.TP
+.B XDG_DATA_DIRS
+A colon ':' separated, preference ordered list of base directories for
+data files.  Defaults to /usr/local/share/:/usr/share/.  Only the
+first matching file is used.
+.B 
 .SH AUTHORS
 rss2email was started by Aaron Swartz, and is currently maintained by
-Lindsey Smith.  For a more complete list of contributors, see the
-__contributors__ list in rss2email\&.py.
-.SH "REPORTING BUGS"                                                            
-Report bugs to the current maintainer (see the __author__ string in
-rss2email\&.py).
+W. Trevor King.  For a more complete list of contributors, see the
+__contributors__ list in rss2email/__init__\&.py.
+.SH "REPORTING BUGS"
+Report bugs to the mailing list (see the README for details).