flnews_post_proc 1.73 → 1.75

data/doc/rst/flnews_post_proc.rst

@@ -1,342 +1,275 @@
-=======================
- flnews_post_proc
-=======================
+===========================
+flnews_post_proc
+===========================
 ------------------------------------------
- Post-Processor for the flnews newsreader
+Post-Processor for the flnews Newsreader
 ------------------------------------------
 
 SYNOPSIS
-=======================
+===========================
+The post-processor is invoked by piping an article into it. This typically occurs
+automatically when the "post_proc" variable is set to `flnews_post_proc` in the
+flnews configuration file.
 
-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.
-
-Locally stored articles can be piped in to the post-processor, as needed
-for testing purposes, with a command-line like the following:
+For testing purposes, you can also pipe locally stored articles into the post-processor
+using a command like:
 
 **flnews_post_proc < article**
 
 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.
-  My 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. You can even specify that a signature should be
-  picked randomly from a file, containing several signatures.
-
-* 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 the X-No-Archive header 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 both headers for all posts to certain
-  newsgroups.
-
-  **ATTN** As of 2024, the header “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 <ref/> 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=%
-
-Dialog to override settings
----------------------------
-ATTN! As of version 1.72, YAD or Zenity cannot be used for the dialog.
-
-You can have a dialog displayed just before the post-processor is invoked, to
-**disable** some configuration options. Provided that 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**.
-* The Archive- and X-No-Archive headers, if set for the current newsgroup,
-  **can be ignored**.
-* Logging can be **switched off**, if set.
-
-Pushing Esc or the cancle-button of the dialog interrupts the process, flnews
+===========================
+The flnews newsreader fully supports Usenet access, enabling the reception and reading
+of articles from newsgroups, as well as composing and posting them.
+
+When comparing various news clients, differences will often influence your choice of
+preferred client. Flnews distinguishes itself by not only offering control over its
+internal behavior, but also by allowing you to modify outgoing posts just before they
+are sent to the configured NNTP server.
+
+The `flnews_post_proc` program can be used to modify and enhance a post in ways that
+flnews alone cannot. It is configurable and may meet the needs of some Usenet users,
+though it is primarily intended as a starting point for creating your own custom solutions.
+
+Limitations of Basic Newsreaders
+--------------------------------------------------------
+While flnews creates posts that are generally complete and ready for submission, there are
+instances where users might find the output unsatisfactory for arbitrary reasons:
+
+* If you're posting to different newsgroups in multiple languages, the introductory line
+  referencing a prior post can only be set once in the flnews configuration file. As a
+  result, posts to a French newsgroup, for example, may start with an introduction in
+  English. The post-processor can address this by setting specific introductory lines
+  for each newsgroup.
+
+* Similar issues arise when you set a standard signature and want it to vary based on
+  the newsgroup. The post-processor allows different signatures to be used for different
+  newsgroups, and you can even randomize the selection from a list of signatures stored
+  in a file.
+
+* Custom headers, such as GnuPG key IDs or your language proficiency, can also be added
+  to posts, though signatures may be a better alternative. Custom headers can be defined
+  in the configuration file and will be added to outgoing posts.
+
+* Headers like "Archive" and "X-No-Archive" are sometimes set to prevent an article from
+  being indexed by search engines (e.g., Google). For example, test posts likely don't need
+  to be included in search results. The post-processor can apply both headers to all posts
+  sent to certain newsgroups.
+
+  **NOTE**: As of 2024, the "X-No-Archive" header has limited effectiveness, and it is
+  up to server operators whether or not to honor it.
+
+* Posts that include many references to other posts or URLs can become cluttered. The
+  post-processor can convert marked text into footnotes, similar to the <ref/> link format
+  used in Wikipedia, with the delimiter configurable in the configuration file.
+  Example (using %=):
+  "This is an object %=and this becomes the footnote, describing the object further=%"
+
+Dialog for Overriding Settings
+------------------------------
+**IMPORTANT**: As of version 1.72, YAD or Zenity cannot be used for the dialog interface.
+
+Before the post-processor runs, a dialog can be displayed to allow users to **disable**
+certain configuration options. If Whiptail or xterm are available, you can choose to
+disable the following options. You **cannot** enable options that haven't already been set
+in the configuration.
+
+* Signatures (if set in the configuration) can be **ignored**. A default signature will
+  be used, or no signature at all.
+* Custom headers can be **omitted**.
+* The "Archive" and "X-No-Archive" headers can be **ignored** if set for the current
+  newsgroup.
+* Logging can be **disabled**, if enabled.
+
+Pressing Esc or the Cancel button on the dialog will interrupt the process, and 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). 
+To disable the dialog entirely (and apply all configured options without further interaction),
+set the **OVERRIDE_CONFIG** option.
 
 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.
+Upon first execution of the program, a copy of the original configuration file is created
+in */home/[user]/.flnews_post_proc.conf*. This file is used thereafter. Deleting it will
+cause the file to be recreated, but any custom 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:
+The configuration file uses YAML syntax and includes detailed explanations. The variables
+within it fall into 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.
+1. Variables that represent values originally set by flnews, which can be used or replaced.
+   These elements are typically captured using regular expressions.
+2. Variables that define new or modified content.
 
-* Variables defining the new or altered content.
+Example Configuration Variables
+-------------------------------
 
 **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
- from *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,
- like 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.
+A regular expression that matches the name of the previous poster in a quoted post. This
+string is recognized in the original article and used with the matching element from
+*GROUP_INTRO*.
 
- CONTENT: A String equivalent of a regular expression.
+Leave this field empty to retain the default value from the FLNews configuration.
 
- DEFAULT: EMPTY
+CONTENT: A string representing a regular expression.
 
- EXAMPLE1: "On \\\\d+.\\\\d+.\\\\d{2,4} at \\\\d+:\\\\d+ **(.*)** wrote:"
+DEFAULT: EMPTY
 
- EXAMPLE2: "**(.*)** wrote:"
+EXAMPLE1: "On \\\\d+.\\\\d+.\\\\d{2,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.
+A regular expression that matches the newsgroup where the quoted post was published.
 
- Leave this field empty to ignore the precise group.
+Leave this field empty to ignore the exact group.
 
- CONTENT: A String equivalent of a regular expression.
+CONTENT: A string representing a regular expression.
 
- DEFAULT: EMPTY
+DEFAULT: EMPTY
 
- EXAMPLE: "wrote in **(.*)**:"
+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.
+Introductory strings referring to the previous poster in a quoted post. When the newsgroup
+matches *FUP_GROUP*, these variables are used in the resulting introduction.
 
- CONTENT: A newsgroup or regexp per line, followed by a colon, a space and a String
+CONTENT: A newsgroup or regular expression per line, followed by a colon, space, and string.
 
- DEFAULT: As configured in FLNews
- 
- EXAMPLE: alt.test: "Thus spoke %fup_name% on that baleful %fup_date%:"
+DEFAULT: As configured in FLNews.
+
+EXAMPLE: alt.test: "Thus spoke %fup_name% on that baleful %fup_date%:"
 
 **GROUP_SIGS**
- A signature line per Newsgroup or a file path. The file should contain signatures,
- already formatted and separated by 1 empty line. The program will randomly pick 
- one signature from the list. You can source another file inside the original
- signature file: a line starting with a point and a space will indicate that
- additional signatures should be picked from the named file, like in:
- . /home/user/.other_signature_file
- This works only in the file named in the configuration, not in the sourced files.
- Remember to separate lines sourcing a file by an empty line, also separate several
- such lines by an empty line between them.
+Signature lines for each newsgroup or a path to a file containing signatures, which should be
+formatted and separated by one empty line. A random signature is picked from the file for each
+newsgroup. You can also source another file within the signature file by starting a line with
+". /path/to/other/file".
 
- CONTENT: A newsgroup or regexp per line, followed by a colon, a space and a String.
+CONTENT: A newsgroup or regular expression per line, followed by a colon, space, and string.
 
- DEFAULT: As configured in flnews
+DEFAULT: As configured in flnews.
 
- EXAMPLE: alt.test: "Signature for alt.test\\r\\nsecond line"
- 
- EXAMPLE: comp.*: /home/[user]/.my_sigs
+EXAMPLE: alt.test: "Signature for alt.test\\r\\nsecond line"
+EXAMPLE: comp.*: /home/[user]/.my_sigs
 
 **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. 
+Additional custom headers to be added to outgoing articles.
 
- DEFAULT: undefined
+CONTENT: One line per header, starting with a dash and space, followed by the header name and value.
 
- | EXAMPLE (2 headers): 
- | - 'X-My-Header: nothing fancy'
- | - 'X-Another-Header: care not!' 
+DEFAULT: Undefined
 
-**NO_ARCHIVE_GROUPS** 
- The newsgroups, where the headers “Archive: no” and “X-No-Archive: YES” shall
- be set.
+EXAMPLE:
+  - 'X-My-Header: nothing fancy'
+  - 'X-Another-Header: care not!'
 
- CONTENT: a dash and space, then a String, containing the name of the group or a regexp.
+**NO_ARCHIVE_GROUPS**
+Newsgroups where the "Archive: no" and "X-No-Archive: YES" headers should be set.
 
- DEFAULT: empty
+CONTENT: A line with a dash and space, followed by the group name or a regular expression.
 
- | EXAMPLE (1 group, 1 hierarchy): 
- | - "alt.test"
- | - "^news.*"
+DEFAULT: Empty
 
+EXAMPLE:
+  - "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.
+The name of the file where debug messages are logged. If specified, logging will be enabled.
+If empty, logging is disabled.
 
- CONTENT: The name of a writable file, which will be created if inexistent 
- and overwritten if need be.
+CONTENT: The name of a writable file, which will be created if it doesn't exist and overwritten if necessary.
 
- DEFAULT: empty
+DEFAULT: Empty
 
- EXAMPLE: '/tmp/a_log-file.txt'
+EXAMPLE: '/tmp/a_log-file.txt'
 
 **LOG LEVEL**
- One of debug, fatal, error, info, warn
+One of: debug, fatal, error, info, warn.
 
 **REFERENCES_SEPARATOR**
- A symbol or sequence of 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*.
+A symbol or sequence marking the end of the message body and the beginning of a footnote list.
+If not defined, footnotes are appended directly after the message body.
 
- 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.
 
- CONTENT: A quoted symbol or sequence of symbols.
+DEFAULT: Empty
 
- DEFAULT: empty
-
- EXAMPLE: '---------'
+EXAMPLE: '---------'
 
 **REFERENCES_DELIMITER**
- A sequence of at least two 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.
+A sequence marking the beginning and end of text to be used as a footnote or reference. The reversed
+sequence is used to mark the end.
 
- CONTENT a quoted symbol or sequence of symbols.
+CONTENT: A quoted symbol or sequence.
 
- DEFAULT: none/empty
+DEFAULT: None (empty)
 
- EXAMPLE: '%?'
+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)
+A format string using `%s` for a number to replace the reference text in the body.
 
- EXAMPLE: "(%s)"  -> becomes (1) ... (2)  ... (3)
+DEFAULT: " %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
- * Slashes are added, if they are found missing after "http(s):" 
+EXAMPLE: "(%s)" → becomes (1) ... (2) ... (3)
 
- If the variable is not set, a value 'yes' is assumed.
+**VFY_URLS**
+A boolean constant determining whether URLs should be verified and corrected if necessary.
+URL manipulations include adding angular brackets ('<', '>') and slashes after "http(s):".
 
- CONTENT: One of YES, yes, NO, no, and other variations of case.
+CONTENT: One of YES, yes, NO, no (case insensitive).
 
- DEFAULT: yes
+DEFAULT: yes
 
- Example: ... I let you guess.
+EXAMPLE: ... I leave this to your discretion.
 
 **OVERRIDE_CONFIG**
- A Boolean constant. You can choose to override the following configuration
- options before an article is posted: GROUP_SIGS, XNAY_GROUPS, CUSTOM_HEADERS,
- DEBUG_LOG and VFY_URLS.  A dialog may be displayed which allows you to disable
- any of these five options, so that the defaults from flnews prevail.
+A boolean constant that controls whether configuration options can be overridden before posting.
 
- ATTN! Canceling the dialog or pushing the Esc-key does interrupt the process.
- Flnews will not post the article.
+Set this to "no" to disable the dialog.
 
- Set this option to no, NO or similar to disable the dialog.
+DEFAULT: yes
 
- DEFAULT: yes
-
- EXAMPLE: No
+EXAMPLE: No
 
 Other Information
-=================
+========================
 
 Testing
 -------
-The effects that the execution of the program will have on a posting can be
-verified in two ways:
+You can verify the post-processor’s effect by using one of two methods:
 
-1. By piping-in a post that had previously been saved to a file:
+1. Pipe a saved post into the program:
 
    **:~$ /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.
-2. 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.
+   This will show the modified article, and you can pipe it into another file for further testing.
 
+2. Post directly to a test newsgroup (e.g., alt.test). This is essential before posting to
+   real newsgroups, especially when the post-processor will alter the article.
 
-Source-Code
+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
+The gem file for the program, available via the gem utility or rubygems.org, contains all
+the source code and documentation (this page included). To extract it, do the following:
 
-1. untar the gem-file with tar -xf flnews_post_proc-0.1.gem
-2. uncompress the data.gz archive: gunzip data.gz
-3. untar the resultig data.tar archive: tar -xf data.tar
+1. Extract the gem file: `tar -xf flnews_post_proc-0.1.gem`
+2. Uncompress the data archive: `gunzip data.gz`
+3. Extract the data archive: `tar -xf data.tar`
 
-This creates the directories bin, doc and lib.
+This will create 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).
+The flnews_post_proc is distributed under the WTFPL-2.0 or later License.
+For more details, visit http://www.wtfpl.net/txt/copying/ or refer to the license file in the
+documentation directory of the gem.
 
 Author
 ------
-| flnews_post_proc has been developed by 
-| Michael Uplawski <michael.uplawski@uplawski.eu>
+flnews_post_proc has been developed by  
+Michael Uplawski <michael.uplawski@uplawski.eu>
 
 Ω
 ==
+

data/lib/basic_logging.rb

@@ -2,7 +2,7 @@
 #encoding: UTF-8
 =begin
 /***************************************************************************
- *   2023-2024, Michael Uplawski <michael.uplawski@uplawski.eu>            *
+ *   2023-2025, Michael Uplawski <michael.uplawski@uplawski.eu>            *
  *   This program is free software; you can redistribute it and/or modify  *
  *   it under the terms of the WTFPL 2.0 or later, see                     * 
  *   http://www.wtfpl.net/about/                                           *

data/lib/body.rb

@@ -2,7 +2,7 @@
 
 =begin
   /***************************************************************************
-   *   2023-2024, Michael Uplawski <michael.uplawski@uplawski.eu>            *
+   *   2023-2025, Michael Uplawski <michael.uplawski@uplawski.eu>            *
    *   This program is free software; you can redistribute it and/or modify  *
    *   it under the terms of the WTFPL 2.0 or later, see                     * 
    *   http://www.wtfpl.net/about/                                           *

data/lib/configuration.rb

@@ -1,7 +1,7 @@
 #encoding: UTF-8
 =begin
 /***************************************************************************
- *   2023-2024, Michael Uplawski <michael.uplawski@uplawski.eu>            *
+ *   2023-2025, Michael Uplawski <michael.uplawski@uplawski.eu>            *
  *   This program is free software; you can redistribute it and/or modify  *
  *   it under the terms of the WTFPL 2.0 or later, see                     * 
  *   http://www.wtfpl.net/about/                                           *

data/lib/flnews_post_proc.conf

@@ -1,5 +1,5 @@
 #/***************************************************************************
-# *   2023-2024, Michael Uplawski <michael.uplawski@uplawski.eu>           *
+# *   2023-2025, Michael Uplawski <michael.uplawski@uplawski.eu>           *
 # *                                                                         *
 # *   This program is free software; you can redistribute it and/or modify  *
 # *   it under the terms of the DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE *
@@ -123,7 +123,7 @@ REFERENCES_SEPARATOR: "──────────────────"
 # REFERENCE_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 origimal
+# 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.
@@ -136,7 +136,7 @@ REFERENCES_DELIMITER: "%="
 # REFERENCE_FORMAT
 # A format-string, using %s for a number, replacing the reference-
 # text in the message body. 
-# DEFAULT: " %s]"  -> becomes 1) ... 2)  ... 3) 
+# DEFAULT: " %s)"  -> becomes 1) ... 2)  ... 3) 
 # EXAMPLE: "(%s)"  -> becomes (1) ... (2)  ... (3) 
 REFERENCE_FORMAT: " ➤%s"
 

data/lib/flnews_post_proc.rb

@@ -1,7 +1,7 @@
 #encoding: UTF-8
 =begin
 /***************************************************************************
- *   2023-2024, Michael Uplawski <michael.uplawski@uplawski.eu>            *
+ *   2023-2025, Michael Uplawski <michael.uplawski@uplawski.eu>            *
  *   This program is free software; you can redistribute it and/or modify  *
  *   it under the terms of the WTFPL 2.0 or later, see                     * 
  *   http://www.wtfpl.net/about/                                           *