From ec2268737a86fb0b46d4b66d11493c0607a41567 Mon Sep 17 00:00:00 2001 From: Thomas Hochstein Date: Mon, 19 Jan 2026 01:53:09 +0100 Subject: [PATCH] Add POD. Signed-off-by: Thomas Hochstein --- .yapfaqrc.sample | 2 +- ChangeLog | 1 + bin/yapfaq.pl | 417 ++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 417 insertions(+), 3 deletions(-) diff --git a/.yapfaqrc.sample b/.yapfaqrc.sample index 0f894e0..54d63d1 100644 --- a/.yapfaqrc.sample +++ b/.yapfaqrc.sample @@ -5,7 +5,7 @@ # - nntp-pass password for AUTHINFO # - force-auth force AUTHINFO # - starttls 1 = use STARTTLS if possible, 0 = don't -# - verbose 1 = show warning messages, 0 = don't +# - verbose 1 = show status messages, 0 = don't # - debug 1 = show debug output, 0 = don't nntp-server = localhost nntp-port = 119 diff --git a/ChangeLog b/ChangeLog index b18a354..3d35539 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,6 @@ yapfaq 1.0.0 (unreleased) * Complete rewrite. +* Add POD. yapfaq 0.10 (unreleased) * Add: Charset definition. diff --git a/bin/yapfaq.pl b/bin/yapfaq.pl index ed6ee62..27298ba 100755 --- a/bin/yapfaq.pl +++ b/bin/yapfaq.pl @@ -45,10 +45,10 @@ $Config{'nntp-server'} = 'news'; # your NNTP server name, may be set via $NNTP $Config{'nntp-port'} = 119; # NNTP-port, may be set via $NNTPPORT $Config{'nntp-user'} = ''; # username for AUTHINFO $Config{'nntp-pass'} = ''; # password for AUTHINFO -$Config{'force-auth'} = 0; # set to 1 to force authentification +$Config{'force-auth'} = 0; # set to 1 to force authentication $Config{'starttls'} = 0; # set to 1 to use STARTTLS if possible -$Config{'verbose'} = 0; # set to 1 to get warning messages +$Config{'verbose'} = 0; # set to 1 to get status messages $Config{'debug'} = 0; # set to 1 to get some debug output, # set to 2 for NNTP debug output @@ -569,3 +569,416 @@ sub UpdateStatus { return; } +__END__ + +################################ Documentation ################################# + +=head1 NAME + +yapfaq - Post FAQs to Usenet I<(yet another postfaq)> + +=head1 SYNOPSIS + +B [B<-Vhcfto>] [B<-p> I[B<-n> I] [OPTIONS] + +=head1 REQUIREMENTS + +=over 2 + +=item - + +Perl 5.8 or later with core modules + +=item - + +DateTime + +=item - + +Path::Tiny + +=back + +Furthermore you need access to a news server to actually post FAQs. + +=head1 DESCRIPTION + +B can post (one or more) FAQs (or other texts) to Usenet every +n days, weeks, months or years. The content (article body) for each +text will be read from a project file, and headers (with some +placeholders) will be read from another project file. Posting +frequency can be defined as header, or in the body in form of a +news.answers pseudo-header. + +Project status (last time posted, last used I) will be +tracked in a config file for each project. + +Configuration can be done by modifying the source (disapproved), by +adding a config file in your home directory or by overriding those +options on the command line. + +=head2 Runtime configuration + +Options for B can be set by modifying the I +section of the source or by using a config file located at +F<$XDG_CONFIG_HOME/yapfaqrc>, F<$HOME/.config/yapfaqrc> or +F<$HOME/.yapfaqrc> (in order of precedence). Options in config files +will override options in source. Both can be overridden by using +command line options. + +=over 2 + +=item B = I + +Path to the directory for all project files. + +Each project needs a F.hdr> file with all headers and a +F.txt> file containing the content (body) to be posted. +B will track the project status in a F.cfg> file. + +You can override this option on the command line by using +B<--datadir> I. + +=item B = I<0|1> + +Display some status messages on STDOUT if set to I<1>. + +You can override this option on the command line by using +B<--verbose> (B<-v>) or B<--noverbose> accordingly. + +Don't use B if you want to pipe your text to another program! + +=item B = I<0|1> + +Display debug messages (and NNTP dialogue) on STDOUT if set to I<1>. + +You can override this option on the command line by using +B<--debug> (B<-d>) or B<--nodebug> accordingly. + +Don't use B if you want to pipe your text to another program! + +=item B = I + +News (NNTP) server to connect to. + +Can be overridden by setting I<$NNTPSERVER> or I<$NEWSHOST> in your +environment. + +You can override this option on the command line by using +B<--nntp-server> I. + +=item B = I + +Port on B to connect to. Default is 119. + +B can't use NNTPS on port 563, but can use STARTTLS if +available. + +Can be overridden by setting I<$NNTPPORT> in your environment. + +You can override this option on the command line by using +B<--nntp-port> I. + +=item B = I + +User name for AUTHINFO authentication. + +You can override this option on the command line by using +B<--nntp-user> I. + +=item B = I + +Password for AUTHINFO authentication. + +You can override this option on the command line by using +B<--nntp-pass> I. + +=item B = I<0|1> + +Force AUTHINFO authentication, even if the server reports that you +may post. Necessary for some servers. + +You can override this option on the command line by using +B<--force-auth> or B<--noforce-auth> accordingly. + +=item B = I<0|1> + +Use a TLS encrypted connection (via STARTTLS) if available. + +You can override this option on the command line by using +B<--starttls> or B<--nostarttls> accordingly. + +=back + +=head2 Project files + +Each project needs a F.hdr> and a F.text> file, +and will get a F.cfg> file after the first posting. These +files need to be in B. + +=head3 Headers file + +Needs to have at least I, I and I and +can contain all other headers that the posting should have. + +I may contain a I<%LM> placeholder that will be replaced +with the I pseudo-header from the text file +(see below), if present. If no I pseudo-header is +found, the placeholder (and surrounding brackets, angle brackets or +curly brackets and spaces) is removed. + +If a I header is present, placeholders in that header +will be replaced: I<%n> with the project name, I<%y> with the current +year (YYYY), I<%m> with the current month (MM), I<%d> with the +current day (DD) and I<%p> with the current process ID (PID) of +B. If no I header is present, the I +will be generated with the hostname of the system B is +running on and I<%n-%y-%m-%d> as template for the left hand side. If +the I header in the headers file does not contain +placeholders, the next repost will most probably fail. + +If an I header is present, it must contain a time period of +n days, weeks, months or years in the form of a number followed by +I, I, I or I, e.g. I for four weeks: If no +such I header is present, no such header will be set. + +If a I header is present (e.g. I, it +will be replaced with a I header containing the +I of the last posted article. + +If a I header is present, it must contain a time +period in the same way as for I, e.g. I +for a monthly posting. The I header will be +removed. Alternatively a I pseudo-header in the +text file may be used (see below). If no I is set, +the default ist one month (I<1m>). + +B + + From: John Doe + Reply-To: + Subject: <%LM> FAQ for alt.example.discussions + Newsgroups: alt.example.discussions + Message-ID: <%n-%y-%m-%d@my-domain.example> + Posting-frequency: 1w + Expires: 1m + Supersedes: yes + Mime-Version: 1.0 + Content-Type: text/plain; charset=utf-8 + Content-Transfer-Encoding: 8bit + +=head3 Text file + +The content (body) of your FAQ or other text. + +It may contain pseudo-headers, starting on the first line and +separated from the reamining content by a blank line. + +I and I will be evaluated by +B. + +If your content contains 8bit characters, you'll need suitable MIME +headers in your headers file. + +B + + Archive-name: alt-example/discussions-faq + Posting-frequency: weekly + Last-modified: 2025-12-15 + URL: https://doe.example/faqs/alt-example-discussions-faq.txt + + This is a list of frequently asked questions (FAQs) and their + answers for the alt.example.discussions newsgroup. + + 1. What is the topic of alt.example.discussions? + + We discuss examples. + + That's quite enought, isn't it? + +=head1 OPTIONS + +=over 4 + +=item B<-c>, B<--config> + +Display current runtime configuration from source or config file. + +=item B<-f>, B<--force> + +Post text unconditionally, even if not due according to the defined +posting frequency. This refers either to all projects or just one +defined by B<--project>. + +=item B<-n>, B<--newsgroup> I + +Override the I header for all texts posted. Intended for +testing purposes. + +Combine with B<--test> to avoid updating project status and to get a +unique I (and no I header). + +=item B<-o>, B<--output> + +Don't post via NNTP, but print to STDOUT. + +Combine with B<--test> to avoid updating project status. + +Intended for testing purposes or to pipe in another program like +I or I. If you want to pipe the output to another +program, neither B<--verbose> nor B<--debug> should be set. + +=item B<-p>, B<--project> I + +Run for just one project (FAQ, text). Default is running for all +projects. + +=item B<-h>, B<--help> + +Display this man page and exit. + +=item B<-t>, B<--test> + +Test mode. Don't update project status (time and Message-ID of last +posting), dont' add a I header and modify the +I with a random part. + +The text(s) will still be posted if due or forced by B<--force>. + +Combine with B<--output> to redirect output to STDOUT or with +B<--newsgroup> to override the I header. + +=item B<-V>, B<--version> + +Display version and copyright information and exit. + +=item B + +You can override all runtime configuration options set in the source +or a config file from the command line, as described above. + +=back + +=head1 EXAMPLES + +Post all FAQs that are due for posting: + + yapfaq.pl + +You may run this command daily from B. + +Do a dry run, showing which FAQs would be posted and print them on +STDOUT: + + yapfaq.pl -t -v -o + (or yapfaq.pl -tvo) + +The same, with debugging output: + + yapfaq.pl -tdo + +Force a test post of your I text to I, even if +the text is not due to be posted: + + yapfaq.pl -t -f -n alt.test + +The same, with debugging output: + + yapfaq.pl -tfdn alt.test + + +Pipe all FAQs (that are due for posting) to I from INN: + + yapfaq.pl -o | inews + +You may run this command daily from B, too. + +=head1 ENVIRONMENT + +=over 2 + +=item B<$NEWSHOST> + +Set to override the NNTP server configured in the source or config +file. It has lower priority than B<$NNTPSERVER> and should be +avoided. The B<--nntp-server> command line option overrides +B<$NEWSHOST>. + +=item B<$NNTPSERVER> + +Set to override the NNTP server configured in the source or config +file. This has higher priority than B<$NEWSHOST>. The +B<--nntp-server> command line option overrides B<$NNTPSERVER>. + +=item B<$NNTPPORT> + +The NNTP TCP port to connect news to. This variable only needs to be +set if the TCP port is not 119 (the default). The B<--nntp-port> +command line option overrides B<$NNTPPORT>. + +=back + +=head1 FILES + +=over 2 + +=item F + +The script itself. + +=item F<$XDG_CONFIG_HOME/yapfaqrc> F<$HOME/.config/yapfaqrc> F<$HOME/.yapfaqrc> + +Config file (on order of precedence). + +=item F/I.hdr> + +Headers for I. + +=item F/I.txt> + +Content (body) for I. + +=item F/I.cfg> + +Status data of I. + +=back + +=head1 BUGS + +Please report any bugs or feature requests to the author or use the +bug tracker at L! + +=head1 SEE ALSO + +L will have the current +version of this program. + +This program is maintained using the Git version control system at +L. + +=head1 AUTHOR + +Thomas Hochstein + +Original author (up to version 0.5b, dating from 2003): +Marc Brockschmidt + +=head1 COPYRIGHT AND LICENSE + +Copyright (c) 2003 Marc Brockschmidt + +Copyright (c) 2010-2017, 2026 Thomas Hochstein + +This program is free software; you may redistribute it and/or modify it +under the same terms as Perl itself. + +This program contains (modified) code from tinews.pl, +copyright (c) 2002-2024 Urs Janssen and +Marc Brockschmidt + +This program contains (modified) code from pgpverify.pl, +written April 1996, (David C Lawrence), +currently maintained by Russ Allbery + +=cut