Add POD.
Signed-off-by: Thomas Hochstein <thh@thh.name>
This commit is contained in:
parent
848507f37c
commit
ec2268737a
3 changed files with 417 additions and 3 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
yapfaq 1.0.0 (unreleased)
|
||||
* Complete rewrite.
|
||||
* Add POD.
|
||||
|
||||
yapfaq 0.10 (unreleased)
|
||||
* Add: Charset definition.
|
||||
|
|
|
|||
417
bin/yapfaq.pl
417
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<yapfaq> [B<-Vhcfto>] [B<-p> I<project name>[B<-n> I<newsgroup>] [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<yapfaq> 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<Message-ID>) 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<yapfaq> can be set by modifying the I<configuration>
|
||||
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<datadir> = I<path>
|
||||
|
||||
Path to the directory for all project files.
|
||||
|
||||
Each project needs a F<I<project>.hdr> file with all headers and a
|
||||
F<I<project>.txt> file containing the content (body) to be posted.
|
||||
B<yapfaq> will track the project status in a F<I<project>.cfg> file.
|
||||
|
||||
You can override this option on the command line by using
|
||||
B<--datadir> I<path>.
|
||||
|
||||
=item B<verbose> = 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<verbose> if you want to pipe your text to another program!
|
||||
|
||||
=item B<debug> = 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<debug> if you want to pipe your text to another program!
|
||||
|
||||
=item B<nntp-server> = I<hostname>
|
||||
|
||||
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<hostname>.
|
||||
|
||||
=item B<nntp-port> = I<port>
|
||||
|
||||
Port on B<nntp-server> to connect to. Default is 119.
|
||||
|
||||
B<yapfaq> 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<port>.
|
||||
|
||||
=item B<nntp-user> = I<user name>
|
||||
|
||||
User name for AUTHINFO authentication.
|
||||
|
||||
You can override this option on the command line by using
|
||||
B<--nntp-user> I<user name>.
|
||||
|
||||
=item B<nntp-pass> = I<password>
|
||||
|
||||
Password for AUTHINFO authentication.
|
||||
|
||||
You can override this option on the command line by using
|
||||
B<--nntp-pass> I<password>.
|
||||
|
||||
=item B<force-auth> = 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<starttls> = 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<I<project>.hdr> and a F<I<project>.text> file,
|
||||
and will get a F<I<project>.cfg> file after the first posting. These
|
||||
files need to be in B<datadir>.
|
||||
|
||||
=head3 Headers file
|
||||
|
||||
Needs to have at least I<From:>, I<Subject:> and I<Newsgroups:> and
|
||||
can contain all other headers that the posting should have.
|
||||
|
||||
I<Subject:> may contain a I<%LM> placeholder that will be replaced
|
||||
with the I<Last-modified:> pseudo-header from the text file
|
||||
(see below), if present. If no I<Last-modified:> pseudo-header is
|
||||
found, the placeholder (and surrounding brackets, angle brackets or
|
||||
curly brackets and spaces) is removed.
|
||||
|
||||
If a I<Message-ID:> 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<yapfaq>. If no I<Message-ID:> header is present, the I<Message-ID>
|
||||
will be generated with the hostname of the system B<yapfaq> is
|
||||
running on and I<%n-%y-%m-%d> as template for the left hand side. If
|
||||
the I<Message-ID:> header in the headers file does not contain
|
||||
placeholders, the next repost will most probably fail.
|
||||
|
||||
If an I<Expires:> 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<d>, I<w>, I<m> or I<y>, e.g. I<Expires: 4w> for four weeks: If no
|
||||
such I<Expires:> header is present, no such header will be set.
|
||||
|
||||
If a I<Supersedes:> header is present (e.g. I<Supersedes: yes>, it
|
||||
will be replaced with a I<Supersedes:> header containing the
|
||||
I<Message-ID> of the last posted article.
|
||||
|
||||
If a I<Posting-Frequency:> header is present, it must contain a time
|
||||
period in the same way as for I<Expires:>, e.g. I<Posting-Frequency: 1m>
|
||||
for a monthly posting. The I<Posting-Frequency:> header will be
|
||||
removed. Alternatively a I<Posting-Frequency:> pseudo-header in the
|
||||
text file may be used (see below). If no I<Posting-Frequency:> is set,
|
||||
the default ist one month (I<1m>).
|
||||
|
||||
B<Example headers file>
|
||||
|
||||
From: John Doe <john-doe@example.com>
|
||||
Reply-To: <john@doe.example>
|
||||
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<Last-modified:> and I<Posting-frequency> will be evaluated by
|
||||
B<yapfaq>.
|
||||
|
||||
If your content contains 8bit characters, you'll need suitable MIME
|
||||
headers in your headers file.
|
||||
|
||||
B<Example text file with pseudo-headers>
|
||||
|
||||
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<newsgroup>
|
||||
|
||||
Override the I<Newsgroups:> header for all texts posted. Intended for
|
||||
testing purposes.
|
||||
|
||||
Combine with B<--test> to avoid updating project status and to get a
|
||||
unique I<Message-ID:> (and no I<Supersedes:> 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<inews> or I<tinews.pl>. 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<project name>
|
||||
|
||||
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<Supersedes:> header and modify the
|
||||
I<Message-ID:> 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<Newsgroups:> header.
|
||||
|
||||
=item B<-V>, B<--version>
|
||||
|
||||
Display version and copyright information and exit.
|
||||
|
||||
=item B<OPTIONS>
|
||||
|
||||
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<cron>.
|
||||
|
||||
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<example> text to I<alt.test>, 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<inews> from INN:
|
||||
|
||||
yapfaq.pl -o | inews
|
||||
|
||||
You may run this command daily from B<cron>, 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<bin/yapfaq.pl>
|
||||
|
||||
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<datadir>/I<project>.hdr>
|
||||
|
||||
Headers for I<project>.
|
||||
|
||||
=item F<I<datadir>/I<project>.txt>
|
||||
|
||||
Content (body) for I<project>.
|
||||
|
||||
=item F<I<datadir>/I<project>.cfg>
|
||||
|
||||
Status data of I<project>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
Please report any bugs or feature requests to the author or use the
|
||||
bug tracker at L<https://code.virtcomm.de/thh/yapfaq/issues>!
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<https://th-h.de/net/software/yapfaq/> will have the current
|
||||
version of this program.
|
||||
|
||||
This program is maintained using the Git version control system at
|
||||
L<https://code.virtcomm.de/thh/yapfaq/>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Thomas Hochstein <thh@thh.name>
|
||||
|
||||
Original author (up to version 0.5b, dating from 2003):
|
||||
Marc Brockschmidt <marc@marcbrockschmidt.de>
|
||||
|
||||
=head1 COPYRIGHT AND LICENSE
|
||||
|
||||
Copyright (c) 2003 Marc Brockschmidt <marc@marcbrockschmidt.de>
|
||||
|
||||
Copyright (c) 2010-2017, 2026 Thomas Hochstein <thh@thh.name>
|
||||
|
||||
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 <urs@tin.org> and
|
||||
Marc Brockschmidt <marc@marcbrockschmidt.de>
|
||||
|
||||
This program contains (modified) code from pgpverify.pl,
|
||||
written April 1996, <tale@isc.org> (David C Lawrence),
|
||||
currently maintained by Russ Allbery <eagle@eyrie.org>
|
||||
|
||||
=cut
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue