flnews_post_proc 1.40

data/doc/rst/flnews_post_proc_fr.rst

@@ -0,0 +1,377 @@
+=======================
+ flnews_post_proc
+=======================
+------------------------------------------
+ Post-Traitement pour flnews
+------------------------------------------
+
+SYNOPSIS
+=======================
+
+Un article est envoyé au logiciel de post-traitement via STDIN. Ceci se passe
+automatiquement, quand la variable « post_proc » dans le fichier de
+configuration de flnews a la valeur *flnews_post_proc*.
+
+Si un article a été sauvegardé dans un fichier, il peut servir pour tester le
+fonctionnement de flnews_post_proc, en lançant une commande comme :
+
+    **flnews_post_proc < article.txt**
+
+ou si vous préférez l'équivalent :
+
+    **cat article.txt | flnews_post_proc**
+
+DESCRIPTION
+=======================
+
+Le lecteur de news **flnews** est suffisant pour l'accès au Usenet, c'est à
+dire pour lire les articles et pour les rédiger et les envoyer aux newsgroups
+de votre choix.
+
+Quand vous comparez les clients pour les news, vous allez toujours identifier
+le logiciel qui correspond à vos attentes et vos habitudes. Flnews, comme un
+logiciel basique, vous offre la possibilité d'influencer comment il fonctionne
+et aussi de manipuler directement les articles qu'il produit, juste avant qu'ils
+soient envoyés au serveur nntp.
+
+Ce post-traitement peut servir à ajouter et à modifier des détails du message
+d'une manière qui n'est actuellement pas possible avec seulement flnews.  Comme
+le logiciel est configurable, il peut probablement répondre aux besoins de
+quelques utilisateurs du Usenet. Quand même, vous devez le comprendre comme un
+exemple pour ce qui est possible et pour inspiration, afin de créer vos propres
+solutions.
+
+Les limites d'un lecteur basique de news – ce qui peut faire flnews_post_proc
+-----------------------------------------------------------------------------
+
+Bien que les articles qui sont créés avec flnews sont complets et prêt pour
+l'envoi, certains utilisateurs ne seront pas toujours d'accord avec le résultat
+et ce pour des raisons arbitraires :  
+
+* Il peut y avoir des inconvénients quand vous communiquez dans de groupes
+  diverses en plusieurs langues. La ligne d'introduction qui fait référence à
+  un article précédent, ne peut être configurée qu'une seule fois pour flnews.
+  La conséquence peut être une introduction en Anglais quand vous postez dans
+  un groupe français.
+
+  Avec mon logiciel de post-traitement vous pouvez imposer des introductions
+  spécifiques, à chaque fois pour une ou plusieurs newsgroups.
+
+* Le même conflit se produit quand vous avez défini une signature mais voudriez
+  la remplacer contre une autre, selon le groupe dans lequel vous êtes en train
+  de poster.
+
+  flnews_post_proc peut faire exactement ça, quand vous avez configuré quel
+  signature doit apparaître dans quel newsgroup ou liste de newsgroups.
+
+* Quelques entêtes supplémentaires peuvent servir à transmettre des informations
+  aux lecteurs intéressés, comme l'ID de votre clé GnuPG, vos connaissances en
+  langues ou pareil. Il se trouve que la signature est mieux pour ça, mais vous
+  êtes libres. Je veux mentionner « face » et « x-face » mais préfère que vous
+  ne vous en souvenez pas.
+
+  Ces entêtes, – Custom-Headers – peuvent être définis dans la configuration
+  du logiciel et vont être utilisées dans chaque article sortant.
+
+* L'entête « X-No-Archive » est parfois utilisé afin d'éviter l'archivage
+  d'un article. Il ne devrait par conséquence pas être trouvé par les moteurs
+  de recherche ( Google notamment ). Les articles dans les groupes de test, par
+  exemple, ne valent probablement pas qu'on les trouve parmi les résultats des
+  recherches.
+
+  Avec flnews_post_proc vous pouvez décider et imposer que vos articles dans
+  certains newsgroups contiendront d'office une entête **X-No-Archive: Yes**.
+
+  **ATTN** Depuis l'année 2024, cet entête n'a probablement plus de fonction.
+
+* Certains messages mentionnent d'autres articles ou des URLs de pages Web.
+  S'ils sont nombreux, ces références peuvent déranger la lecture à cause de
+  leur syntaxe spécifique.
+
+  Mon logiciel est capable d'identifier des fragments de text marqué – pas
+  seulement des références – et les transformer en notes en bas de page.  Vous
+  pouvez imaginer ça comme le fonctionnement de la balise <ref/> de Wikipedia,
+  mais vous pouvez définir votre propre séparateur pour marquer les fragments
+  de text dans le fichier de configuration.
+
+  Exemple ( avec séparateur **%=** ) :
+  « Ceci est un objet %=et ceci devient la note en bas de page, qui décrit
+  l'objet plus précisement=% » 
+
+Dialogue pour désactiver des options
+------------------------------------
+Juste avant d'entrer en action, flnews_post_proc peut afficher un dialogue, qui
+vous laisse **désactiver** des options fixées dans la configuration. Sous
+condition qu'un des outils YAD, Zenity, Whiptail ou seulement xterm est
+disponible, vous pouvez choisir dans les options suivantes, ceux que vous
+voulez ignorer pour l'article en préparation. Vous **ne pouvez pas** activer
+des options, qui ne l'ont pas été auparavant :
+
+* Signatures, comme définis dans la configuration **peuvent être ignorées**.
+  Soit une signature par défaut sera appliquée, si prévue, ou aucune.
+
+* Entêtes supplémentaires, si définis, peuvent rester absentes de l'article.
+
+* L'entête X-No-Archive, si prévu pour le newsgroup choisi, peut être ignoré.
+
+* L'auto correction de URLs et références à d'autres articles peut être
+  désactivé. 
+
+* L'écriture d'un protocole peut être arrêtée.  
+
+En tapant Esc ou en poussant le bouton « Annuler » du dialogue, vous pouvez
+interrompre le processus, flnews ne vas pas envoyer l'article.
+
+Vous pouvez même désactiver le dialogue, ce qui assure que toutes les options
+configurées seront appliquées sans plus d'interaction ( à voir dessous : optoin
+OVERRIDE_CONFIG ).
+
+CONFIGURATION
+=============
+La première fois que vous exécutez le logiciel, une copie de la configuration
+par défaut sera écrit dans */home/[utilisateur]/.flnews_post_proc.conf* C'est
+ce fichier qui sera désormais utilisé. Si vous l'effacez, il sera recréé à la
+prochaine occasion, mais vos modifications seront perdues.
+
+Le fichier de configuration est en format YAML et plein d'explications. Les
+variables définis dans ce fichier peuvent être classées en deux catégories :
+
+* Variables qui décrivent des valeurs déterminées par flnews. Ils peuvent être
+  utiilisées ou remplacées. Les composants importants sont normalement
+  spécifiés dans une « capture group ».
+
+* Variables qui définissent du nouveau contenu ou des changements dans le
+  contenu.
+
+**FUP_NAME**
+ Une « expression régulière » ( “regular expression” ) décrivant la chaîne de
+ caractères qui contient le nom de l'auteur d'un article précédent, qu'on veut
+ citer en partie.  Cet élément est reconnu dans l'article d'origine et peut
+ être utilisé à la place de l'élément correspondant dans *GROUP_INTRO* ( à voir
+ plus bas ). Le format de l'expression est celui de la classe Regexp dans Ruby.
+ Veillez de masquer le backslash '\\' avec un autre, comme dans l'exemple.  Un
+ « capture group » '()' sert à extraire le nom du résultat de la comparaison.
+ 
+ Laissez ce champs vide afin de maintenir le comportement configuré pour flnews.
+
+ CONTENU    : L'équivalent d'une regular expression en chaîne de caractères.
+
+ PAR DÉFAUT : Vide
+
+ EXEMPLE 1  : "On \\\\d+.\\\\d+.\\\\d{2,4} at \\\\d+:\\\\d+ **(.*)** wrote:"
+ 
+ EXEMPLE 2  : "**(.*)** wrote:"
+
+**FUP_GROUP**
+ Une « expression régulière » ( “regular expression” ) décrivant la chaîne de
+ caractères qui contient le newsgroup où a été publié l'article précédent à qui nous
+ faisons référence dans un « followup ».
+
+ Laissez ce champs vide afin d'ignorer le groupe précis.
+
+ CONTENU    : l'équivalent d'une regular expression en chaîne de caractères.
+
+ PAR DÉFAUT : Vide
+
+ EXEMPLE    : "wrote in **(.*)**:"
+
+**GROUP_INTROS**
+ Des introductions qui font référence à l'auteur de l'article précédent que
+ nous souhaitons citer. Si vous avez trouvé le newsgroup où l'article a été
+ publié ( à voir : FUP_GROUP, ci-dessus ), et le nom de son auteur 
+ ( FUP_NAME ), vous pouvez utiliser ces valeurs ici.
+
+ Jusqu'à prochaine ordre, seulement %fup_name% est %fup_group% sont reproduit
+ dans l'introduction resultant.
+
+ | CONTENU    : Un newsgroup ou regexp par ligne, suivi de deux points, un espace et
+ |              une chaîne de caractères.
+
+ PAR DÉFAUT : Comme configuré dans flnews.
+ 
+ | EXEMPLE ( un groupe et une hiérarchie )   : 
+ |   alt.test: "Thus spoke %fup_name% in %fup_group%"   
+ |   fr\\.*: "C'était dans %fup_group%, que %fup_name% c'est exprimé ainsi"
+
+**GROUP_SIGS**
+ Une signature par newsgroup ou expression.
+ ATTN! Vous devez noter \\r\\n pour les sautes de lignes, si une signature
+ s'étend sur plusieurs lignes. 
+
+ CONTENU : un newsgroup ou expression par ligne, suivi de deux poins, un espace
+ et une chaîne de caractères.
+
+ PAR DÉFAUT : Comme configuré dans flnews.
+
+ EXEMPLE : fr.test: "Signature pour alt.test\\r\\nseconde ligne"
+
+**CUSTOM_HEADERS**
+ Entêtes supplémentaires pour l'article sortant.
+
+ CONTENU : 1 ligne par entête : un trait d'union, un espace, puis une chaîne de
+ caractères comprenant le nom de l'entête, puis deux points et la valeur de
+ l'entête.
+
+ PAR DÉFAUT : Vide ( pas défini )
+
+ | EXEMPLE ( 2 entêtes ) : 
+ | - 'X-My-Header: nothing fancy'
+ | - 'X-Another-Header: care not!' 
+
+**XNAY_GROUPS**
+ Les newsgroups, où une entête X-No-Arcive: YES doit être présent.  
+ **ATTN** Depuis l'année 2024, cet entête n'a probablement plus de fonction.
+
+ CONTENU : Un trait d'union et un espace, puis une chaîne de caractères,
+ contenant le nom du groupe ou une expression.
+
+ PAR DÉFAUT : Vide
+
+ | EXEMPLE ( 1 groupe, 1 hiérarchie ) : 
+ | - "alt.test"
+ | - "^news.*"
+
+
+**DEBUG_LOG**
+ Le nom d'un fichier, qui va servir comme protocol. Si le nom d'un fichier
+ valide est donné, le protocol est activé. Laissez vide pour désactiver le
+ protocol.
+
+ | CONTENU : Le nom d'un fichier dont les droits permettent l'écriture.
+ |     Il sera créé s'il n'existe pas encore et remplacé à chaque exécution 
+ |     du logiciel.
+
+ PAR DÉFAUT : Vide
+
+ EXEMPLE : '/tmp/a_log-file.txt'
+
+**LOG LEVEL**
+ Un de debug, fatal, error, info, warn
+
+ | EXEMPLE : 
+ |     LOG_LEVEL: 'debug'
+
+**REFERENCES_SEPARATOR**
+ Un symbole ou une séquence de symboles qui marquent la fin du corps du message
+ et le début d'une liste de « références » ou « notes de pied de page ». Il
+ apparaîtra seulement, si  le message contient du text marqué pour servir comme
+ note de pied de page.  À voir *REFERENCES_DELIMITER* ci-dessous.
+
+ Si l'option n'est pas défini ou vide, la liste suit à la dernière ligne du
+ corps du message, sans séparation supplémentaire. 
+
+ CONTENU    : Un symbol ou séquence de symboles entre guillemets " " ou ' '.
+
+ PAR DÉFAUT : Vide
+
+ EXEMPLE    : '---------'
+
+**REFERENCES_DELIMITER**
+ Une séquence d'au moins deux symboles qui marque le début  d'un text qui sera
+ transformé en note de pied de page ( ou référence ). La **séquence inversée**
+ doit marquer la fin du même fragment de text. La présence de cette séquence
+ dans le message d'origine, a comme conséquence que le text marqué sera déplacé
+ vers la fin, au-dessous du corps du message.
+ Si *REFERENCES_SEPARATOR* ( option ci-dessus ) est défini, il va séparer le message
+ de la liste des notes du pied de page.  
+
+ Laissez ce champs vide pour éviter la création des noted du pied de page.
+
+ CONTENU : Une séquence de symboles entre guillemets ( '' )
+
+ PAR DÉFAUT : Vide
+
+ EXEMPLE: '%?'
+
+**REFERENCE_FORMAT**
+ Une chaîne de formatage, contenant %s pour représenter une nombre, qui
+ remplace le texte d'une future note du pied de page dans le corps du message.
+
+ PAR DÉFAUT : " %s)" -> devient 1) ... 2) ... 3)
+
+ EXEMPLE : "(%s)" -> devient (1) ... (2) ... (3)
+
+**VFY_URLS**  
+ Une constante booléen. Elle détermine si le programme doit essayer de corriger
+ des URIs. Même si les URIs sont identifiables, seulement quelques manipulations
+ sont temptées :
+
+ * '<' et '>' sont ajoutés, si manquants
+ * "news:" est ajouté au début des références à d'autres articles 
+ * Des slashes sont insérés, s'ils manquent après "http(s):"
+
+ ATTN! Le programme ne peut pas différencier entre "mailto:" et "news:". Si ni l'un
+ ni l'autre est donné, mais '@' est présent, "news:" est ajouté automatiquement.
+
+ Si la variable n'est pas défini, la valeur 'yes' est présumée.
+
+ CONTENU: Un de YES, yes, NO, no, et autres tels variations 
+
+ PAR DÉFAUT: yes
+
+ EXEMPLE: No
+
+**OVERRIDE_CONFIG**
+ Une constante booléenne. Vous pouvez décider d'ignorer les options
+ suivantes avant qu'un article est posté :
+ GROUP_SIGS, XNAY_GROUPS, CUSTOM_HEADERS, VFY_URLS et DEBUG_LOG.
+ Un dialogue peut être affiché, qui permet la désactivation de chacune de ces
+ options. Les valeurs par défaut, définis pour flnews, vont donc prévaloir.
+
+ ATTN ! En poussant Esc ou le bouton « Annuler » du dialogue, vous interrompez 
+ le programme et flnews ne va rien envoyer.
+
+ Notez la valeur 'no', 'NO' ou pareil pour désactiver le dialogue.
+
+ PAR DÉFAUT : yes
+
+ EXEMPLE: No
+
+Autres Informations
+===================
+
+Tester
+------
+L'effet qu'aura l'exécution du programme peut être vérifié de deux manières :
+
+1. En fournissant un article, sauvegardé auparavant dans un fichier :
+
+   **:~$ /usr/local/bin/[post-processor] < [test-article]**
+
+   Ceci va vous présenter la nouvelle version de l'article sur l'écran, mais 
+   vous pouvez aussi diriger le résultat dans un autre fichier. C'est une 
+   excellente technique pour tester un logiciel pendant le développement ou
+   votre configuration avant que vous vous en servez.
+
+2. En envoyant un message directement dans un groupe de test ( comme alt.test,
+   fr.test ou similaires ). 
+   Ceci est obligatoire avant que vous postez dans des groupes thématiques et 
+   si les réglages du post-traitement vont modifier l'article.
+
+Code source
+-----------
+Le  fichier flnews_post_proc.gem, que vous recevez à l'aide de l'outil *gem* ou
+directement du site *rubygems.org*, contient tout le code source du logiciel et
+de la documentation ( cette page notamment ). Pour lire le code du logiciel,
+vous devez 
+
+1. utiliser *tar -xf flnews_post_proc-[version].gem* 
+2. décomprimer l'archive data.gz : *gunzip data.gz*
+3. Extraire le contenu du fichier résultant « data.tar » :
+   *tar -xf data.tar*   
+
+À la fin les répertoires bin, doc et lib seront créés.
+
+License
+-------
+flnews_post_proc est distribué sous les conditions de la WTFPL-2.0 ou plus
+récent ( À voir http://www.wtfpl.net/txt/copying/ ou license-text dans le
+répertoire « doc » de la gem ).
+
+Auteur
+------
+| flnews_post_proc a été développé par 
+| Michael Uplawski <michael.uplawski@uplawski.eu>
+
+Ω
+==

data/lib/basic_logging.rb

@@ -0,0 +1,170 @@
+#!/bin/env ruby
+#encoding: UTF-8
+=begin
+/***************************************************************************
+ *   2023-2024, 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/                                           *
+ *                                                                         *
+ *   This program is distributed in the hope that it will be useful,       *
+ *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                  *
+ *                                                                         *
+ ***************************************************************************/
+=end
+
+#
+# Simplified logging. 
+# See example code at the bottom of this file.
+# Execute this file to see the output.
+module BasicLogging
+
+  DEBUG = 0
+  INFO =  1
+  WARN =  2
+  ERROR = 3
+  FATAL = 4
+  UNKNOWN = nil
+  
+  # this is mainly for the translation of method calls into log levels
+  Levels = {:debug => DEBUG, :info => INFO, :warn => WARN, :error => ERROR,
+            :fatal => FATAL, :unknown => UNKNOWN}
+
+  @@log_level = UNKNOWN
+  @@target = STDOUT
+  @@muted = []
+
+  # do not log, if caller is obj (class or instance)
+  def self.mute(obj)
+    name = obj.class == Class ? obj.name.dup : obj.class.name
+    @@muted << name
+  end
+
+  def self.is_muted?(obj)
+    name = obj.class == Class ? obj.name.dup : obj.class.name
+    @@muted.include?(name)  
+  end
+
+  # set the log level 
+  def set_level(lv)
+    if lv.respond_to?(:to_str)
+      lv = Levels[lv.to_sym]
+    end
+
+    if(!lv || (lv.respond_to?(:to_int) && lv >= DEBUG && lv <= FATAL) )
+      @@log_level = lv
+    else
+      STDERR.puts __FILE__.dup << ": ERROR : invalid log level \"" << lv.to_s << "\""
+      STDERR.puts "Keepinng old log level " << Levels.keys.detect {| k| Levels[k] == @@log_level}.to_s
+    end
+  end
+
+  # set the log target 
+  def set_target(tg)
+    if !tg || tg.strip.empty?
+      @@target = nil
+    elsif tg.respond_to?(:to_io) 
+      @@target = tg
+    elsif(!File::exist?(tg) || ( File.file?(tg) && File.writable?(tg) ) )
+      @@target = File.open(tg, 'w+')  
+    else
+      STDERR.puts __FILE__.dup << ': ERROR : target ' << tg << ' cannot be set'
+      STDERR.puts "Keeping old target " << @@target.inspect
+      return
+    end
+  end
+
+  # Output of log messages, depending on the log level set for the calling class
+  # and the name of the alias method which is actually called.
+  def log(message)
+    if !BasicLogging.is_muted?(self)
+      # how has this method been called?
+      mlevel = __callee__
+      if Levels.has_key?(mlevel) && Levels[mlevel] <=  FATAL
+        # output only for levels equal or above the value that corresponds to
+        # the calling alias.
+        format_log( message, mlevel) if @@log_level && Levels[mlevel] >= @@log_level 
+      else
+        STDERR.puts __FILE__.dup << ": ERROR : invalid log level \"" << mlevel.to_s << "\""
+      end
+    end
+  end
+
+  alias :debug :log
+  alias :info :log
+  alias :warn :log
+  alias :error :log
+  alias :fatal :log
+
+  attr_reader :target, :log_level
+
+  private 
+
+  # 1 format_log for all loggers.
+  def format_log(message, mlevel)
+    if @@target
+      # indicate if a registered class or the registered object of a class is calling.
+      name = self.class == Class ? self.name.dup << ' [class]' : self.class.name
+      @@target.puts '' << name << ' ' << mlevel.to_s << ' ' << Time.now.strftime("%H:%M:%S:%6N")  << ': ' << message.gsub("\n", "\n |")
+    end
+  end
+end
+#---------test: execute file----------
+if $0 == __FILE__
+  Array.extend(BasicLogging)
+  Array.set_level(BasicLogging::INFO)
+  Array.info('TEST')
+  ar = Array.new
+  ar.extend(BasicLogging)
+  # --- no output : 
+  l = __LINE__
+  ar.debug(l.next.to_s << ': debug-test 0')
+  # output
+  ar.set_level(BasicLogging::DEBUG)
+  l = __LINE__
+  ar.debug(l.next.to_s << ': debug-test 1')
+
+  obj = Object.new
+  obj.extend(BasicLogging)
+  obj.set_level(BasicLogging::DEBUG)
+  puts "--------debug-----------"
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts "--------info-----------"
+  obj.set_level("info")
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts "--------fatal-----------"
+  obj.set_level("fatal")
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts "--------UNKNOWN-----------"
+  obj.set_level(nil)
+  obj.debug('debug')
+  obj.info('info')
+  obj.warn('warn')
+  obj.error('error')
+  obj.fatal('fatal')
+  puts " ------ Output into file ----"
+  obj.set_target "/tmp/test_log.log"
+  puts " ------ INFO -----------"
+  obj.set_level BasicLogging::INFO
+  obj.info('info output')
+
+  obj.info('info output 2') 
+  puts "---------- invalid -------"
+  obj.set_target "/dev/sr0"
+  obj.set_level "power"
+end
+
+# EOF