flnews_post_proc 1.75 → 1.91

data/doc/rst/flnews_post_proc.rst

@@ -1,239 +1,334 @@
 ===========================
 flnews_post_proc
 ===========================
+
+.. |program| replace:: **flnews_post_proc**
+
 ------------------------------------------
 Post-Processor for the flnews Newsreader
 ------------------------------------------
 
+.. contents::
+    :local:
+    :backlinks: none
+    :depth: 3
+
+.. _SYNOPSIS:
+
 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:
 
 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 |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.
 
-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:
 
 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:
 
 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:
 
 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.
-
-DEFAULT: EMPTY
+.. empty lines in the following definition list are in reality '\ '
 
-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.
 
-DEFAULT: Undefined
+    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::
 
-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.
+    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::
 
-DEFAULT: Empty
-
-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.
+
+    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.
+    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: '---------'
 
-DEFAULT: Empty
+**REFERENCES_DELIMITER**
 
-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: '%?'
 
-**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.
+**REFERENCE_FORMAT**
 
-CONTENT: A quoted symbol or sequence.
+    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)
 
-DEFAULT: None (empty)
+**VFY_URLS**
 
-EXAMPLE: '%?'
+    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 dialog:
 
-**REFERENCE_FORMAT**
-A format string using `%s` for a number to replace the reference text in the body.
+**OVERRIDE_CONFIG**
 
-DEFAULT: " %s)" → becomes 1) ... 2) ... 3)
+    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
 
-EXAMPLE: "(%s)" → becomes (1) ... (2) ... (3)
+.. _Other Information:
 
-**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):".
+Other Information
+========================
 
-CONTENT: One of YES, yes, NO, no (case insensitive).
+.. _Signatures in Supersedes:
 
-DEFAULT: yes
+Signatures in Supersedes
+------------------------
+When superseding an existing post, the post-processor will NOT automatically add a signature.
+This preserves the original post content as much as possible.
 
-EXAMPLE: ... I leave this to your discretion.
+To retain the signature from the original post:
 
-**OVERRIDE_CONFIG**
-A boolean constant that controls whether configuration options can be overridden before posting.
+1. In flnews, select the entire article body with the mouse—from the first line 
+   (including any introductions) down to the last line of the signature.
 
-Set this to "no" to disable the dialog.
+2. From the Article menu, select **Supersede**.
 
-DEFAULT: yes
+3. Edit the article text as needed. The signature will be included in the 
+   editable text (normally, flnews strips signatures before opening the editor).
 
-EXAMPLE: No
+4. Send the article.
 
-Other Information
-========================
+**Note:** The `override dialog`_ (see above) does not affect signatures in superseding posts.
+
+.. _Testing:
 
 Testing
 -------
@@ -243,15 +338,23 @@ 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:
 
 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`
@@ -259,15 +362,22 @@ the source code and documentation (this page included). To extract it, do the fo
 
 This will create the directories `bin`, `doc`, and `lib`.
 
+.. _License:
+
 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:
 
 Author
 ------
-flnews_post_proc has been developed by  
+|program| has been developed by  
 Michael Uplawski <michael.uplawski@uplawski.eu>
 
 Ω

data/lib/basic_logging.rb

@@ -116,7 +116,6 @@ module BasicLogging
   alias :error :log
   alias :fatal :log
 
-
   private 
 
   def lock_target(&block)

data/lib/body.rb

@@ -151,15 +151,23 @@ class Body
   end
 
   def set_signature(signature)
-    # unless no changes requested.
-    if signature && !signature.empty? 
-      # remove any signature(s) from 
-      # the current article
-      sigpos = @lines.index('-- ')
-      debug('found signature in line ' << sigpos.to_s) if sigpos
-      @lines = @lines.slice(0, sigpos ) if sigpos
-      debug('setting signature ' << signature) if signature
-      @lines << "-- " << signature if signature
+    unless @@config.SUPERSEDES
+      debug 'is not a supersedes'
+      # unless no changes requested.
+      debug 'signature is ' << (signature ? signature.to_s : 'NIL')
+      if signature && !signature.empty? 
+        # remove any signature(s) from 
+        # the current article
+        sigpos = @lines.index('-- ')
+        debug('found signature in line ' << sigpos.to_s) if sigpos
+        @lines = @lines.slice(0, sigpos ) if sigpos
+        debug('setting signature ' << signature) if signature
+        @lines << "-- " << signature if signature
+      else
+        debug 'signature is ' << (signature ? signature.to_s : 'not set.' )
+      end
+    else
+      debug 'ignoring signature in spersedes'
     end
   end
 
@@ -293,6 +301,7 @@ class Body
     end
   end
 
+  # formatting http URLs, not much is done here.
   def handle_http(l)
     debug('handle http')
     l_array = l.split

data/lib/configuration.rb

@@ -77,33 +77,33 @@ class Configuration
   # updates the configuration file, if need be.
   def update_config(i_config)
     if @conf
-    conf_version = @conf[:CONFIG_VERSION]
-    if !conf_version || conf_version < PROGVERSION.to_f
-      info "configuration has an older version number, looking for changes"
-      i_conf = YAML::load_file(i_config)
-      i_conf.transform_keys!{|k| k.to_sym}
-      i_keys = i_conf.keys
-      i_keys.each do |k|
-        if !@conf[k]
-          info('new configuration option: ' << k.to_s)
-          @conf[k] = ''
+      conf_version = @conf[:CONFIG_VERSION]
+      if !conf_version || conf_version < PROGVERSION.to_f
+        info "configuration has an older version number, looking for changes"
+        i_conf = YAML::load_file(i_config)
+        i_conf.transform_keys!{|k| k.to_sym}
+        i_keys = i_conf.keys
+        i_keys.each do |k|
+          if !@conf[k]
+            info('new configuration option: ' << k.to_s)
+            @conf[k] = ''
+          end
+        end
+        @conf[:CONFIG_VERSION] = PROGVERSION.to_f
+        bak_conf = @config_file.dup << '_' << conf_version.to_s
+        bak_conf.gsub!('.' << PROGNAME,  'bak_' << PROGNAME)
+        info('Old configuration is saved to ' << bak_conf ) 
+        info('New configuration is saved to ' << @config_file ) 
+        begin
+          File::write(bak_conf, File.read(@config_file))
+          File::write(@config_file, @conf.to_yaml)
+        rescue Exception => ex
+          msg = "Cannot write altered configuration to " << @config_file << "!\n\t" << ex.message
+          STDERR.puts(msg << "\nAborting, bye\n")
+          error msg
+          exit false
         end
       end
-      @conf[:CONFIG_VERSION] = PROGVERSION.to_f
-      bak_conf = @config_file.dup << '_' << conf_version.to_s
-      bak_conf.gsub!('.' << PROGNAME,  'bak_' << PROGNAME)
-      info('Old configuration is saved to ' << bak_conf ) 
-      info('New configuration is saved to ' << @config_file ) 
-      begin
-        File::write(bak_conf, File.read(@config_file))
-        File::write(@config_file, @conf.to_yaml)
-      rescue Exception => ex
-        msg = "Cannot write altered configuration to " << @config_file << "!\n\t" << ex.message
-        STDERR.puts(msg << "\nAborting, bye\n")
-        error msg
-        exit false
-      end
-    end
     else
       error "User-version of the configuration (#{@conf}) inaccessibble."
       exit false