flnews_post_proc
Post-Processor for the flnews newsreader ——————————————
IMPORTANT
Please give priority to the documentation which is delivered with the gem
file, as the markdown syntax plays tricks, sometimes, and I may not be
quick enough to correct this file. This applies especially to the section
Configuration, below.
The gem-file contains different formats of the man-page in English and French. See section Source Code, below, for instructions to access these texts. Or see the same files on the Web.
SYNOPSIS
An article is piped-in to the post-processor. This is normally done
automatically as soon as the variable “post_proc“ in the flnews configuration
file is set to the flnews_post_proc executable, i.e.:
post_proc : /usr/local/bin/flnews_post_proc
Locally stored articles can be piped in to the post-processor, as needed
for testing purposes, with a command-line like the following:
flnews_post_proc < article
INSTALLATION
You must have a Ruby interpreter installed (see ruby-lang.org ).
Your Linux distribution will probably let you choose one from its
software resources. Use the package management utility of your choice.
While you can download the current gem file for flnews_post_proc from
rubygems.org, it is probably best to use the “gem”-utility
for the installation. It should be available from the same source as your
Ruby interpreter.
With the interpreter and the gem utility in place, the installation effort is
reduced to a simple command:
user@machine:~$ sudo gem install flnews_post_proc
This way, the gem file will be downloaded from rubygems.org and installed in
the designated path for ruby-gems. If the installation completes without
errors, the command flnews_post_proc will become immediately available.
For other uses of the gem utility, see the output of
user@machine:~$ gem –help
DESCRIPTION
The flnews newsreader is sufficient for Usenet access, i.e. to receive and read
articles from -, as well as to write and post articles to newsgroups.
When you compare news-clients, you will always notice the differences and
choose the software that you prefer. Flnews however, has the charm that you can
influence how the program itself works but also modify posts that flnews
produces, just before the program will transmit them to the chosen nntp-server.
The flnews_post_proc can add and change details of a post, in ways that are
currently not possible with flnews alone. As the program is configurable, it
can probably respond to the needs of some Usenet users. You should, however,
rather take it as an example for what can be done and an inspiration for your
own creations.
The limits of a basic newsreader — what the program can do
While the articles that flnews creates, are complete and ready to be posted,
some users may not always agree with the result and for arbitrary reasons:
-
There may be inconveniences when you post to different newsgroups in
different languages, as an introductory line which refers to a previous
post can only be set once in the flnews configuration. The consequence
can be that your post to a french newsgroup begins with an introduction
in English.
The post-processor program can set an introductory line specifically
chosen for one or several newsgroups. -
The same conflict arises, when you have set a standard signature text and
would like to replace it against another, based on the newsgroup you are
about to post to.
The post-processor program sets specific signatures as configured for one
or several newsgroups. -
Some custom headers may serve to convey additional information to
interested readers of your post, like GnuPG key IDs, your language skills
or the like. The signature may be a better choice than custom headers.
You are free. I just mention face and x-face but prefer that you do not
remember I did.
Custom headers may be defined in the configuration file for the program
and will then be added to each outgoing post. -
The Archive- and X-No-Archive headers are sometimes set to avoid that an article be saved and stays available to search-engines (Google, notably). Test- postings, for example, do probably not justify at all that they would be referenced in search results. The post-processor program can impose the Archive- and X-No-Archive header for all posts to certain newsgroups.
ATTN As of 2024, the X-No-Archive has lost most of its utility and it is the decision of server operators to honor it or not.
-
If a news post contains many references to either other posts or Web
pages, the text can be cluttered with URLs.
The post-processor can identify marked text fragments and transform them
into footnotes, which will be attached as a list at the bottom of the
post.
This works almost like the references-link in Wikipedia, but the delimiter
can be determined in the configuration file.
Example (with %=):
This is an object %=and this becomes the footnote, describing the object
further=% -
The program can attempt to correct ill formatted references. This is an
option, you can disable it by setting the option VFY_URLS to “no” in the
configuration. Beware that mailto: links are not recognized and cannot be
corrected. See the explanations for VFY_URLS, below.
Dialog to override settings
You can have a dialog displayed just before the post-processor is invoked, to
disable some configuration options. Provided that either YAD, Zenity,
Whiptail or only xterm are available on your computer, you can choose from
the following options. You cannot use the dialog to enable options which
have not yet been set in the configuration.
- Signatures, as set in the configuration can be ignored. Either
a default signature will appear as set in flnews or none. - Custom Headers, if configured, can be omitted.
- Archive- and X-No-Archive headers, if set for the current newsgroup, can be ignored.
- The verification & correction of references can be disabled.
- Logging can be switched off, if set.
Pushing Esc or the cancle-button of the dialog interrupts the process, flnews
will not post the article.
You can disable the dialog, which ensures that all configured options will be
applied, without the need for further interaction (see below, option
OVERRIDE_CONFIG).
CONFIGURATION
On first execution of the program, a copy of the original configuration file is
created in /home/[user]/.flnews_post_proc.conf
It is this file which is used from then on. If you delete it, it will be
recreated, on the next occasion, but your own changes will be lost.
The configuration file is in YAML syntax and full of explanations. The
variables defined in this file can be classified as belonging to one of two
categories:
-
Variables describing values originally set by flnews, which should be used or
replaced. The important elements are usually matched in a capture group. -
Variables defining the new or altered content.
FUP_NAME
A Regular Expression, describing the string which contains the name of
previous poster who is the author of a quoted post. This string is
recognized in the original article and may be used with the fitting element
rom GROUP_INTRO, below. The Regexp format is that of the Regexp class in
Ruby, noted as a String. Beware to mask a backslash ‘\’ by another one,
ike in the example. A capture-group ‘()’ serves to extract the name from the
match result.
Leave this field empty to keep the default from the FLNews configuration
intact.
CONTENT: A String equivalent of a regular expression.
DEFAULT: EMPTY
EXAMPLE1: “On \d+.\d+.\d2,4 at \d+:\d+ (.*) wrote:”
EXAMPLE2: “(.*) wrote:”
FUP_GROUP
A Regular Expression, describing the string which contains the newsgroup
where the previous post, that you are referring to in the followup, had been
published.
Leave this field empty to ignore the precise group.
CONTENT: A String equivalent of a regular expression.
DEFAULT: EMPTY
EXAMPLE: “wrote in (.*):”
GROUP_INTROS
Introductory strings, referring to the previous poster who is the author of a
quoted post. If you match the newsgroup of the post (see FUP_GROUP), you can
use these variables in the result.
Currently only %fup_name% and %fup_group% are reproduced in the resulting
introductory string.
CONTENT: A newsgroup or regexp per line, followed by a colon, a space and a String
DEFAULT: As configured in FLNews
EXAMPLE: alt.test: “Thus spoke #fup_name on that baleful #fup_date:”
GROUP_SIGS
A signature line per Newsgroup.
ATTN! In multi line signatures, you have to use \r\n for line breaks.
CONTENT: A newsgroup or regexp per line, followed by a colon, a space and a String.
DEFAULT: As configured in flnews
EXAMPLE: alt.test: “Signature for alt.test\\r\\nsecond line”
CUSTOM_HEADERS
Additional headers for the outgoing article
CONTENT: 1 line per header : a dash and space, then a String, comprising the
name of the header, ending in a colon and the value of the header.
DEFAULT: undefined
EXAMPLE (2 headers):
- ‘X-My-Header: nothing fancy’
- ‘X-Another-Header: care not!’
NO_ARCHIVE_GROUPS
The newsgroups, where the headers “Archive: no” and “X-No-Archive: YES” shall be set.
CONTENT: a dash and space, then a String, containing the name of the group or
a regexp.
DEFAULT: empty
EXAMPLE (1 group, 1 hierarchy):
- “alt.test”
- “^news.*“
DEBUG_LOG
The name of a file, where debug messages are written. Setting this
variable will enable the log. Leave empty to disable logging.
CONTENT: The name of a writable file, which will be created if inexistent
and overwritten if need be.
DEFAULT: empty
EXAMPLE: ‘/tmp/a_log-file.txt’
LOG LEVEL
One of debug, fatal, error, info, warn
REFERENCES_SEPARATOR
A sequence of 2 or more symbols marking the end of the message-body and the
beginning of a list of “references” or “footnotes”. It will only appear, if
the original message-body contains text marked for use as such a footnote. See
REFERENCES_DELIMITER.
If the option is not defined or empty, the list of footnotes will appear
below the last line of the message body and no separator will be inserted.
CONTENT: A quoted symbol or sequence of symbols.
DEFAULT: empty
EXAMPLE: ’———‘
REFERENCES_DELIMITER
A symbol or sequence of symbols marking the beginning of a text which will
serve as footnote (or reference). The reversed sequence musst be used to
mark the end of the text. The presence of this sequence or symbol in the
original message body will cause the enclosed text to be moved below the
message body.
The REFERENCES_SEPARATOR, if defined, will separate the message from the
list of footnotes.
If this option is not defined or empty, footnotes are not created.
CONTENT a quoted symbol or sequence of symbols.
DEFAULT: none/empty
EXAMPLE: ’%?’
REFERENCE_FORMAT
A format-string, using %s for a number, replacing the reference text in the
message body.
DEFAULT: “ %s)” -> becomes 1) … 2) … 3)
EXAMPLE: ”(%s)” -> becomes (1) … (2) … (3)
VFY_URLS
A Boolean constant. It determines if the program shall verify and possibly
try to correct URLs. Even if URLs are identified as such, only a few
manipulations are attempted :
- Angular brackets ‘<’ and ‘>’ are added, if missing
- Article-references are prepended with “news:”, if missing
- Slashes are added, if they are found missing after “http(s):”
ATTN! The program is unable to discern “mailto:” and “news:” references. If
neither is given, but ‘@’ is present, “news:” is automatically prepended.
If the variable is not set, a value ‘yes’ is assumed.
CONTENT: One of YES, yes, NO, no, and other variations of case.
DEFAULT: yes
EXAMPLE: … I let you guess.
OVERRIDE_CONFIG
GROUP_SIGS, XNAY_GROUPS, CUSTOM_HEADERS and DEBUG_LOG.
A dialog may be displayed which allows you to disable any of these
four options, so that the defaults from flnews prevail.
ATTN! Canceling the dialog or pushing the Esc-key does interrupt
the process. Flnews will not post the article.
Set this option to no, NO or similar to disable the dialog.
DEFAULT: yes
EXAMPLE: No
Other Information
Testing
The effects that the execution of the program will have on a posting can be
verified in two ways:
-
By piping-in a post that had previously been saved to a file:
:~$ /usr/local/bin/[post-processor] < [test-article]
This will show the resulting new version of the article on screen, but you
can also pipe the output into another file. This is a great way to test a
program during development or to test your own configuration of the program. -
By posting directly into a test-newsgroup (like alt.test or similar). This
is mandatory before you really post to thematic newsgroups and when the
settings of the post-processor will affect the article.
Source-Code
The gem-file that you get with the gem-utility or from rubygems.org contains
all the code of the program and some documentation (this page notably). To read
its content, you must
- untar the gem-file with tar -xf flnews_post_proc-0.1.gem
- uncompress the data.gz archive: gunzip data.gz
- untar the resultig data.tar archive: tar -xf data.tar
This creates the directories bin, doc and lib.
License
flnews_post_proc is distributed under the conditions of the WTFPL-2.0 or later
License (see http://www.wtfpl.net/txt/copying/ or license-text in the doc
directory of the gem-file).
Author
flnews_post_proc has been developed by
Michael Uplawski [email protected]