flnews_post_proc 1.75 → 1.80

data/doc/rst/flnews_post_proc.rst

@@ -1,236 +1,289 @@
 ===========================
 flnews_post_proc
 ===========================
+
+.. |program| replace:: **flnews_post_proc**
+
 ------------------------------------------
 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.
+The post-processor is invoked by piping an article into it. This typically
+occurs automatically when the "post_proc" variable is set to |program|
+in the flnews `configuration`_ file.
+
+For testing purposes, you can also pipe locally stored articles into the
+post-processor using a command like:
+
+    |program| < article
 
-For testing purposes, you can also pipe locally stored articles into the post-processor
-using a command like:
+or:
 
-**flnews_post_proc < article**
+    cat article.txt | |program|
 
 DESCRIPTION
 ===========================
-The flnews newsreader fully supports Usenet access, enabling the reception and reading
-of articles from newsgroups, as well as composing and posting them.
+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.
+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.
+The |program| 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=%"
+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.
+**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.
+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.
+* 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.
+* 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.
+Pressing Esc or the Cancel button on the dialog will interrupt the process, and
+flnews will not post the article.
 
-To disable the dialog entirely (and apply all configured options without further interaction),
-set the **OVERRIDE_CONFIG** option.
+To disable the dialog entirely (and apply all configured options without
+further interaction), set the **OVERRIDE_CONFIG** option.
 
 CONFIGURATION
 ===============
-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.
+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 uses YAML syntax and includes detailed explanations. The variables
-within it fall into two categories:
+The configuration file uses YAML syntax and includes detailed explanations. The
+variables within it fall into two categories:
+
+1. Variables that represent values originally set by flnews, which can be used
+   or replaced.  These elements are typically captured using regular
+   expressions.
 
-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.
 
-Example Configuration Variables
+Configuration Options
 -------------------------------
 
-**FUP_NAME**
-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*.
-
-Leave this field empty to retain the default value from the FLNews configuration.
-
-CONTENT: A string representing a regular expression.
+.. empty lines in the following definition list are in reality '\ '
 
-DEFAULT: EMPTY
-
-EXAMPLE1: "On \\\\d+.\\\\d+.\\\\d{2,4} at \\\\d+:\\\\d+ **(.*)** wrote:"
+**FUP_NAME**
 
-EXAMPLE2: "**(.*)** wrote:"
+    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_INTROS`_.
+     
+    Leave this field empty to retain the default value from the FLNews
+    configuration.
+     
+    CONTENT: A string representing a regular expression.
+     
+    DEFAULT: EMPTY
+     
+    EXAMPLE1: "On \\\\d+.\\\\d+.\\\\d{2,4} at \\\\d+:\\\\d+ **(.*)** wrote:"
+     
+    EXAMPLE2: "**(.*)** wrote:"
+
+    .. _fup_group:
 
 **FUP_GROUP**
-A regular expression that matches the newsgroup where the quoted post was published.
-
-Leave this field empty to ignore the exact group.
-
-CONTENT: A string representing a regular expression.
 
-DEFAULT: EMPTY
+    A regular expression that matches the newsgroup where the quoted post was
+    published.
+     
+    Leave this field empty to ignore the exact group.
+     
+    CONTENT: A string representing a regular expression.
+     
+    DEFAULT: EMPTY
+     
+    EXAMPLE: "wrote in **(.*)**:"
 
-EXAMPLE: "wrote in **(.*)**:"
+    .. _group_intros:
 
 **GROUP_INTROS**
-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 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%:"
+    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 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%:"
 
 **GROUP_SIGS**
-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 regular expression per line, followed by a colon, space, and string.
+    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 regular expression per line, followed by a colon,
+    \ \ \ \ space, and string.
+     
+    DEFAULT: As configured in flnews.
 
-DEFAULT: As configured in flnews.
+    EXAMPLE::
 
-EXAMPLE: alt.test: "Signature for alt.test\\r\\nsecond line"
-EXAMPLE: comp.*: /home/[user]/.my_sigs
+     alt.test: "Signature for alt.test\\r\\nsecond line"
+     comp.*: /home/[user]/.my_sigs
 
 **CUSTOM_HEADERS**
-Additional custom headers to be added to outgoing articles.
 
-CONTENT: One line per header, starting with a dash and space, followed by the header name and value.
+    Additional custom headers to be added to outgoing articles.
+     
+    CONTENT: One line per header, starting with a dash and space, followed by
+    the header name and value.
+     
+    DEFAULT: Undefined
+     
+    EXAMPLE::
 
-DEFAULT: Undefined
-
-EXAMPLE:
-  - 'X-My-Header: nothing fancy'
-  - 'X-Another-Header: care not!'
+     - 'X-My-Header: nothing fancy'
+     - 'X-Another-Header: care not!'
 
 **NO_ARCHIVE_GROUPS**
-Newsgroups where the "Archive: no" and "X-No-Archive: YES" headers should be set.
-
-CONTENT: A line with a dash and space, followed by the group name or a regular expression.
 
-DEFAULT: Empty
+    Newsgroups where the "Archive: no" and "X-No-Archive: YES" headers should
+    be set.
+     
+    CONTENT: A line with a dash and space, followed by the group name or a
+    regular expression.
+     
+    DEFAULT: Empty
+     
+    EXAMPLE::
 
-EXAMPLE:
-  - "alt.test"
-  - "^news.*"
+     - "alt.test"
+     - "^news.*"
 
 **DEBUG_LOG**
-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 it doesn't exist and overwritten if necessary.
-
-DEFAULT: Empty
-
-EXAMPLE: '/tmp/a_log-file.txt'
+    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 it doesn't
+    exist and overwritten if necessary.
+     
+    DEFAULT: Empty
+     
+    EXAMPLE: '/tmp/a_log-file.txt'
 
 **LOG LEVEL**
-One of: debug, fatal, error, info, warn.
-
-**REFERENCES_SEPARATOR**
-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.
 
-CONTENT: A quoted symbol or sequence.
+    One of: debug, fatal, error, info, warn.
 
-DEFAULT: Empty
+**REFERENCES_SEPARATOR**
 
-EXAMPLE: '---------'
+    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.
+     
+    CONTENT: A quoted symbol or sequence.
+     
+    DEFAULT: Empty
+     
+    EXAMPLE: '---------'
 
 **REFERENCES_DELIMITER**
-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.
 
-DEFAULT: None (empty)
-
-EXAMPLE: '%?'
+    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.
+     
+    DEFAULT: None (empty)
+     
+    EXAMPLE: '%?'
 
 **REFERENCE_FORMAT**
-A format string using `%s` for a number to replace the reference text in the body.
-
-DEFAULT: " %s)" → becomes 1) ... 2) ... 3)
 
-EXAMPLE: "(%s)" → becomes (1) ... (2) ... (3)
+    A format string using `%s` for a number to replace the reference text in
+    the body.
+     
+    DEFAULT: " %s)" → becomes 1) ... 2) ... 3)
+     
+    EXAMPLE: "(%s)" → becomes (1) ... (2) ... (3)
 
 **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 (case insensitive).
-
-DEFAULT: yes
-
-EXAMPLE: ... I leave this to your discretion.
+    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 (case insensitive).
+     
+    DEFAULT: yes
+     
+    EXAMPLE: ... I leave this to your discretion.
 
 **OVERRIDE_CONFIG**
-A boolean constant that controls whether configuration options can be overridden before posting.
-
-Set this to "no" to disable the dialog.
-
-DEFAULT: yes
 
-EXAMPLE: No
+    A boolean constant that controls whether configuration options can be
+    overridden before posting.
+     
+    Set this to "no" to disable the dialog.
+     
+    DEFAULT: yes
+     
+    EXAMPLE: No
 
 Other Information
 ========================
@@ -243,15 +296,21 @@ You can verify the post-processor’s effect by using one of two methods:
 
    **:~$ /usr/local/bin/[post-processor] < [test-article]**
 
-   This will show the modified article, and you can pipe it into another file for further testing.
+   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.
+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
 -----------
-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:
+
+.. _rubygems.org: https://rubygems.org/gems/flnews_post_proc
+
+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. Extract the gem file: `tar -xf flnews_post_proc-0.1.gem`
 2. Uncompress the data archive: `gunzip data.gz`
@@ -261,13 +320,16 @@ This will create the directories `bin`, `doc`, and `lib`.
 
 License
 -------
-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.
+
+.. _WTFPL-2.0: https://www.wtfpl.net/about/
+
+The |program| is distributed under the `WTFPL-2.0`_ or later License.  For
+the complete license text, 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  
+|program| has been developed by  
 Michael Uplawski <michael.uplawski@uplawski.eu>
 
 Ω

data/lib/newsgroups.rb

@@ -116,7 +116,7 @@ class Newsgroups
           end # if no signature
         end # gsigs.each
       end # gsigs for group?
-      if tsig && tsig.strip.start_with?('/')
+      if tsig && tsig.rstrip.start_with?('/')
         tsig = pick_sig(tsig.strip)
       end
       @signature = correct_linebreaks(tsig) if tsig
@@ -138,7 +138,7 @@ class Newsgroups
       ssigs = Array.new
       all_sigs = Array.new
       File::read(sigfile).split(delim).collect do |item| 
-        item.strip!
+        item.rstrip!
         # find a sourced file
         psrc = item.match(srcregex)
         if(psrc ) 

data/lib/version.rb

@@ -14,9 +14,9 @@
 =end
 
 PROGNAME = 'flnews_post_proc'
-PROGVERSION = "1.75"
+PROGVERSION = "1.80"
 AUTHORS = "Michael Uplawski"
 EMAIL = "michael.uplawski@uplawski.eu"
 YEARS = "2023 - 2025"
-SUMMARY = "new documentation- and homepage URIs"
+SUMMARY = "Generation of documentation simplified. BUG in signatures corrected."
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: flnews_post_proc
 version: !ruby/object:Gem::Version
-  version: '1.75'
+  version: '1.80'
 platform: ruby
 authors:
 - Michael Uplawski
 bindir: bin
 cert_chain: []
-date: 2025-08-27 00:00:00.000000000 Z
+date: 2025-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diffy
@@ -103,5 +103,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: new documentation- and homepage URIs
+summary: Generation of documentation simplified. BUG in signatures corrected.
 test_files: []