flnews_post_proc 1.94 → 1.97

data/doc/rst/flnews_post_proc.rst

@@ -1,34 +1,39 @@
+
 ===========================
 flnews_post_proc
 ===========================
 
 .. |program| replace:: **flnews_post_proc**
 
-.. _flnews: https://micha.freeshell.org/flnews/
+.. _flnews: https://micha.freeshell.org/flnews
+.. _WTFPL-2.0: https://www.wtfpl.net/about/
+.. _CC By-ND 4.0: https://creativecommons.org/licenses/by-nd/4.0/
+.. _rubygems.org: https://rubygems.org/gems/flnews_post_proc
+.. _en Français: https://www.uplawski.eu/div/flnews/gem_doc/fr
+
 
 ------------------------------------------
 Post-Processor for the flnews_ Newsreader
 ------------------------------------------
-
 .. contents::
-    :local:
-    :backlinks: none
-    :depth: 3
+   :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 |program|
-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:
+  For testing purposes, you can also pipe locally stored articles into the
+  post-processor using a command like:
 
     |program| < article
 
-.or:
+  .or:
 
     cat article.txt | |program|
 
@@ -37,365 +42,412 @@ post-processor using a command like:
 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 |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:
 
 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.
+  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=%". See also the hints under 
-  `EDITING FOOTNOTES`_, below.
+  * 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=%". See also the hints under 
+    `EDITING FOOTNOTES`_, below.
 
 .. _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.
-* 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.
+    * Signatures (if set in the `CONFIGURATION`_) can be **ignored**. A default signature will be used, or no signature at all.
 
-Pressing Esc or the Cancel button on the dialog will interrupt the process, and
-flnews will not post the article.
+    * Custom headers can be **omitted**.
 
-To disable the dialog entirely (and apply all configured options without
-further interaction), set the **OVERRIDE_CONFIG** option.
+    * 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.
+
+  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.
 
-The configuration file uses YAML syntax and includes detailed explanations. The
-variables within it fall into two categories:
+  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.
 
-1. Variables that represent values originally set by flnews, which can be used
-   or replaced.  These elements are typically captured using regular
-   expressions.
+  The configuration file uses YAML syntax and includes detailed explanations. The
+  variables within it fall into two categories:
 
-2. Variables that define new or modified content.
+  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.
 
 Configuration Options
 -------------------------------
-
 .. empty lines in the following definition list are in reality '\ '
 
 **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_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:
+  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
-     
-    EXAMPLE: "wrote in **(.*)**:"
+  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
 
-    .. _GROUP_INTROS:
+  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.
-     
-    DEFAULT: As configured in flnews.
+  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".
 
-    EXAMPLE::
+  CONTENT: A newsgroup or regular expression per line, followed by a colon,
+  \ \ \ \ space, and string.
 
-     alt.test: "Signature for alt.test\\r\\nsecond line"
-     comp.*: /home/[user]/.my_sigs
+  DEFAULT: As configured in flnews.
+
+  EXAMPLE::
+
+    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
-     
-    EXAMPLE::
+  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
 
-     - 'X-My-Header: nothing fancy'
-     - 'X-Another-Header: care not!'
+  EXAMPLE::
+
+    - '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
-     
+
     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.
-     
-    DEFAULT: Empty
-     
-    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:
 
 **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 dialog:
 
 **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
+
+**USE_OLD**
+
+  A boolean constant that controls whether |program| handles subject changes.
+  See `Subject changes`_ for the details.
+
+  Set to "false" or leave empty to ignore subject changes.
+
+  DEFAULT: false
+
+  EXAMPLE: yes
 
 .. _Other Information:
 
 Other Information
 ========================
 
+.. _Subject changes:
+
+Subject changes:
+----------------
+  |program| can handle subject changes, provided the configuration option **USE_OLD**
+  is set to **true**.  In this case, additional prefixes are recognized (flnews
+  handles "Was:" on its own).  The additional prefixes are case insensitive 
+  variations of the German "*War:*" and a french "*Était:*", with or without
+  Accent. The french prefix can also contain 1 space before the colon.
+
+  When you write a follow-up to an Article with 
+  *Subject: This topic (Was: old topic)*
+  |program| will remove the part in parenthesis, also (War: old topic) and 
+  (était : old topic).
+
+  This necessitates that **your own subject changes must not use one of those
+  prefixes**.  Instead, use *(Old: ...)* like in 
+  *Subject: new topic (Old: previous topic)*
+
+  |program| will replace Old: by Was: in the posted article.
+
+  **Important**: When *USE_OLD* is true, none of the recognized prefixes will
+  survive. If you forget to use *Old* instead, the subject change will not be
+  recognizable as such, your article will only carry the new subject.
+
+  Leave the option USE_OLD untouched or set it to **false** to ignore subject
+  changes. 
+
+  **NOTE** that Flnews may continue to remove the part of the subject line that
+  is prefixed with *(Was:* or *(was:*.
+
 .. _EDITING FOOTNOTES:
 
 Editing footnotes
 -----------------
-Writing footnote text (or URL references) inline while composing an article may
-be tempting, but it will likely break your line formatting. It's difficult to
-predict line lengths after footnotes are automatically moved to the end.
-Instead, write your complete article first, then add footnotes just before
-posting.
-This lets you anticipate how the final article will look after footnote markers
-replace the inline text (see REFERENCE_FORMAT_, above).
+  Writing footnote text (or URL references) inline while composing an article may
+  be tempting, but it will likely break your line formatting. It's difficult to
+  predict line lengths after footnotes are automatically moved to the end.
+  Instead, write your complete article first, then add footnotes just before
+  posting.
+  This lets you anticipate how the final article will look after footnote markers
+  replace the inline text (see REFERENCE_FORMAT_, above).
 
 .. _Signatures in Supersedes:
 
 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.
+  When superseding an existing post, the post-processor will NOT automatically add a signature.
+  This preserves the original post content as much as possible.
 
-To retain the signature from the original post:
+  To retain the signature from the original post:
 
-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.
+  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.
 
-2. From the Article menu, select **Supersede**.
+  2. From the Article menu, select **Supersede**.
 
-3. Edit the article text as needed. The signature will be included in the 
-   editable text (normally, flnews strips signatures before opening the editor).
+  3. Edit the article text as needed. The signature will be included in te editable text (normally, flnews strips signatures before opening the editor).
 
-4. Send the article.
+  4. Send the article.
 
-**Note:** The `override dialog`_ (see above) does not affect signatures in superseding posts.
+  **Note:** The `override dialog`_ (see above) does not affect signatures in superseding posts.
 
 .. _Testing:
 
 Testing
 -------
-You can verify the post-processor’s effect by using one of two methods:
+  You can verify the post-processor’s effect by using one of two methods:
 
-1. Pipe a saved post into the program:
+  1. Pipe a saved post into the program:
 
-   **:~$ /usr/local/bin/[post-processor] < [test-article]**
+     **:~$ /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
+  1. Extract the gem file: `tar -xf flnews_post_proc-0.1.gem`
 
-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:
+  2. Uncompress the data archive: `gunzip data.gz`
 
-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`
+  3. Extract the data archive: `tar -xf data.tar`
 
-This will create the directories `bin`, `doc`, and `lib`.
+  This will create the directories `bin`, `doc`, and `lib`.
 
 .. _License:
 
 License
 -------
-
-.. _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.
+  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
 ------
-|program| has been developed by  
-Michael Uplawski <michael.uplawski@uplawski.eu>
+  |program| has been developed by Michael Uplawski <michael.uplawski@uplawski.eu>
+
+.. |date| date::
+
+This document
+-------------
+  ©Michael Uplawski <michael.uplawski@uplawski.eu>
+
+  License: `CC BY-ND 4.0`_
+
+  Date: |date|
 
+**Ω**