flnews_post_proc 1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,342 @@
1
+ <?xml version="1.0" encoding="utf-8"?>
2
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6
+ <meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
7
+ <title>flnews_post_proc</title>
8
+ <style type="text/css">
9
+
10
+ /*
11
+ :Author: Michael Uplawski
12
+ :Contact: michael.uplawski@uplawski.eu
13
+ :License: WTFPL 2.0, see http://www.wtfpl.net/about/
14
+
15
+ Stylesheet for use with Docutils.
16
+ */
17
+
18
+ /* The defaults for docutils */
19
+ @import url(html4css1.css);
20
+
21
+ body {
22
+ background-color:#e0f0a0;
23
+ font-family: Verdana,Helvetica,Univers;
24
+ }
25
+
26
+ h1 {color:darkblue;font-size:1.5em;}
27
+ h1.title {color:#a0a0f0;font-size:2em;}
28
+
29
+ p, ul.simple, ol.simple, dt {margin-left:2em;}
30
+ dd {margin-left:4em;}
31
+
32
+ /* correct left margin of nested block tags*/
33
+ dd p, li p {margin-left:0;}
34
+ dd * ul {margin-left:0 ! important; }
35
+ dd ul {margin-left:0 ! important; }
36
+ dd dl dt, dd dl dd {margin-left:0 ! important;}
37
+
38
+ em {color:#000080;
39
+ background-color:#ffffa0;
40
+ }
41
+
42
+ blockquote {background-color:#ffc090;
43
+ padding:0.5em;
44
+ border-radius:0.5em;
45
+ }
46
+
47
+ </style>
48
+ </head>
49
+ <body>
50
+ <div class="document" id="flnews-post-proc">
51
+ <h1 class="title">flnews_post_proc</h1>
52
+ <h2 class="subtitle" id="post-processor-for-the-flnews-newsreader">Post-Processor for the flnews newsreader</h2>
53
+
54
+ <div class="section" id="synopsis">
55
+ <h1>SYNOPSIS</h1>
56
+ <p>An article is piped-in to the post-processor. This is normally done
57
+ automatically as soon as the variable “post_proc“ in the flnews configuration
58
+ file is set to the flnews_post_proc.</p>
59
+ <p>Locally stored articles can be piped in to the post-processor, as needed
60
+ for testing purposes, with a command-line like the following:</p>
61
+ <p><strong>flnews_post_proc &lt; article</strong></p>
62
+ </div>
63
+ <div class="section" id="description">
64
+ <h1>DESCRIPTION</h1>
65
+ <p>The flnews newsreader is sufficient for Usenet access, i.e. to receive and read
66
+ articles from -, as well as to write and post articles to newsgroups.</p>
67
+ <p>When you compare news-clients, you will always notice the differences and
68
+ choose the software that you prefer. Flnews however, has the charm that you can
69
+ influence how the program itself works but also modify posts that flnews
70
+ produces, just before the program will transmit them to the chosen nntp-server.</p>
71
+ <p>The flnews_post_proc can add and change details of a post, in ways that are
72
+ currently not possible with flnews alone. As the program is configurable, it
73
+ can probably respond to the needs of some Usenet users. You should, however,
74
+ rather take it as an example for what can be done and an inspiration for your
75
+ own creations.</p>
76
+ <div class="section" id="the-limits-of-a-basic-newsreader-what-the-program-can-do">
77
+ <h2>The limits of a basic newsreader — what the program can do</h2>
78
+ <p>While the articles that flnews creates, are complete and ready to be posted,
79
+ some users may not always agree with the result and for arbitrary reasons:</p>
80
+ <ul>
81
+ <li><p class="first">There may be inconveniences when you post to different newsgroups in
82
+ different languages, as an introductory line which refers to a previous
83
+ post can only be set once in the flnews-configuration. The consequence
84
+ can be that your post to a french newsgroup begins with an introduction
85
+ in English.
86
+ My post-processor program can set an introductory line specifically
87
+ chosen for one or several newsgroups.</p>
88
+ </li>
89
+ <li><p class="first">The same conflict arises, when you have set a standard signature-text and
90
+ would like to replace it against another, based on the newsgroup you are
91
+ about to post to.
92
+ The post-processor program sets specific signatures as configured for one
93
+ or several newsgroups. You can even specify that a signature should be
94
+ picked randomly from a file, containing several signatures.</p>
95
+ </li>
96
+ <li><p class="first">Some custom headers may serve to convey additional information to
97
+ interested readers of your post, like GnuPG key IDs, your language skills
98
+ or the like. The signature may be a better choice than custom headers.
99
+ You are free. I just mention face and x-face but prefer that you do not
100
+ remember I did.
101
+ Custom-headers may be defined in the configuration file for the program
102
+ and will then be added to each outgoing post.</p>
103
+ </li>
104
+ <li><p class="first">The Archive- and the X-No-Archive header are sometimes set to avoid that an
105
+ article be saved and stays available to search-engines (Google, notably).
106
+ Test- postings, for example, do probably not justify at all that they would
107
+ be referenced in search-results.
108
+ The post-processor program can impose both headers for all posts to certain
109
+ newsgroups.</p>
110
+ <p><strong>ATTN</strong> As of 2024, the header “X-No-Archive“ has lost most of its utility
111
+ and it is the decision of server operators to honor it or not.</p>
112
+ </li>
113
+ <li><p class="first">If a news post contains many references to either other posts or Web
114
+ pages, the text can be cluttered with URLs.
115
+ The post-processor can identify marked text fragments and transform them
116
+ into footnotes, which will be attached as a list at the bottom of the
117
+ post.
118
+ This works almost like the &lt;ref/&gt; link in Wikipedia, but the delimiter
119
+ can be determined in the configuration file.
120
+ Example (with %=):
121
+ This is an object %=and this becomes the footnote, describing the object
122
+ further=%</p>
123
+ </li>
124
+ </ul>
125
+ </div>
126
+ <div class="section" id="dialog-to-override-settings">
127
+ <h2>Dialog to override settings</h2>
128
+ <p>You can have a dialog displayed just before the post-processor is invoked, to
129
+ <strong>disable</strong> some configuration options. Provided that either YAD, Zenity,
130
+ Whiptail or only xterm are available on your computer, you can choose from
131
+ the following options. You <strong>cannot</strong> use the dialog to enable options which
132
+ have not yet been set in the configuration.</p>
133
+ <ul class="simple">
134
+ <li>Signatures, as set in the configuration <strong>can be ignored</strong>. Either
135
+ a default signature will appear as set in flnews or none.</li>
136
+ <li>Custom Headers, if configured, can be <strong>omitted</strong>.</li>
137
+ <li>The Archive- and X-No-Archive headers, if set for the current newsgroup,
138
+ <strong>can be ignored</strong>.</li>
139
+ <li>Logging can be <strong>switched off</strong>, if set.</li>
140
+ </ul>
141
+ <p>Pushing Esc or the cancle-button of the dialog interrupts the process, flnews
142
+ will not post the article.</p>
143
+ <p>You can disable the dialog, which ensures that all configured options will be
144
+ applied, without the need for further interaction (see below, option
145
+ OVERRIDE_CONFIG).</p>
146
+ </div>
147
+ </div>
148
+ <div class="section" id="configuration">
149
+ <h1>CONFIGURATION</h1>
150
+ <p>On first execution of the program, a copy of the original configuration file is
151
+ created in <em>/home/[user]/.flnews_post_proc.conf</em>
152
+ It is this file which is used from then on. If you delete it, it will be
153
+ recreated, on the next occasion, but your own changes will be lost.</p>
154
+ <p>The configuration file is in YAML syntax and full of explanations. The
155
+ variables defined in this file can be classified as belonging to one of two
156
+ categories:</p>
157
+ <ul class="simple">
158
+ <li>Variables describing values originally set by flnews, which should be used or
159
+ replaced. The important elements are usually matched in a capture group.</li>
160
+ <li>Variables defining the new or altered content.</li>
161
+ </ul>
162
+ <dl class="docutils">
163
+ <dt><strong>FUP_NAME</strong></dt>
164
+ <dd><p class="first">A Regular Expression, describing the string which contains the name of
165
+ previous poster who is the author of a quoted post. This string is
166
+ recognized in the original article and may be used with the fitting element
167
+ from <em>GROUP_INTRO</em>, below. The Regexp-format is that of the Regexp class in
168
+ Ruby, noted as a String. Beware to mask a backslash '\' by another one,
169
+ like in the example. A capture-group '()' serves to extract the name from the
170
+ match result.</p>
171
+ <p>Leave this field empty to keep the default from the FLNews configuration
172
+ intact.</p>
173
+ <p>CONTENT: A String equivalent of a regular expression.</p>
174
+ <p>DEFAULT: EMPTY</p>
175
+ <p>EXAMPLE1: &quot;On \\d+.\\d+.\\d{2,4} at \\d+:\\d+ <strong>(.*)</strong> wrote:&quot;</p>
176
+ <p class="last">EXAMPLE2: &quot;<strong>(.*)</strong> wrote:&quot;</p>
177
+ </dd>
178
+ <dt><strong>FUP_GROUP</strong></dt>
179
+ <dd><p class="first">A Regular Expression, describing the string which contains the newsgroup
180
+ where the previous post, that you are referring to in the followup, had been
181
+ published.</p>
182
+ <p>Leave this field empty to ignore the precise group.</p>
183
+ <p>CONTENT: A String equivalent of a regular expression.</p>
184
+ <p>DEFAULT: EMPTY</p>
185
+ <p class="last">EXAMPLE: &quot;wrote in <strong>(.*)</strong>:&quot;</p>
186
+ </dd>
187
+ <dt><strong>GROUP_INTROS</strong></dt>
188
+ <dd><p class="first">Introductory strings, referring to the previous poster who is the author of a
189
+ quoted post. If you match the newsgroup of the post (see FUP_GROUP), you can
190
+ use these variables in the result.
191
+ Currently only %fup_name% and %fup_group% are reproduced in the resulting
192
+ introductory string.</p>
193
+ <p>CONTENT: A newsgroup or regexp per line, followed by a colon, a space and a String</p>
194
+ <p>DEFAULT: As configured in FLNews</p>
195
+ <p class="last">EXAMPLE: alt.test: &quot;Thus spoke %fup_name% on that baleful %fup_date%:&quot;</p>
196
+ </dd>
197
+ <dt><strong>GROUP_SIGS</strong></dt>
198
+ <dd><p class="first">A signature line per Newsgroup or a file path. The file should contain signatures,
199
+ already formatted and separated by 1 empty line. The program will randomly pick
200
+ one signature from the list.</p>
201
+ <p>ATTN! In multi line signatures, you have to use \r\n for line breaks.</p>
202
+ <p>CONTENT: A newsgroup or regexp per line, followed by a colon, a space and a String.</p>
203
+ <p>DEFAULT: As configured in flnews</p>
204
+ <p>EXAMPLE: alt.test: &quot;Signature for alt.test\r\nsecond line&quot;</p>
205
+ <p class="last">EXAMPLE: comp.*: /home/[user]/.my_sigs</p>
206
+ </dd>
207
+ <dt><strong>CUSTOM_HEADERS</strong></dt>
208
+ <dd><p class="first">Additional headers for the outgoing article</p>
209
+ <p>CONTENT: 1 line per header : a dash and space, then a String, comprising the
210
+ name of the header, ending in a colon and the value of the header.</p>
211
+ <p>DEFAULT: undefined</p>
212
+ <div class="last line-block">
213
+ <div class="line">EXAMPLE (2 headers):</div>
214
+ <div class="line">- 'X-My-Header: nothing fancy'</div>
215
+ <div class="line">- 'X-Another-Header: care not!'</div>
216
+ </div>
217
+ </dd>
218
+ <dt><strong>NO_ARCHIVE_GROUPS</strong></dt>
219
+ <dd><p class="first">The newsgroups, where the headers “Archive: no” and “X-No-Archive: YES” shall
220
+ be set.</p>
221
+ <p>CONTENT: a dash and space, then a String, containing the name of the group or a regexp.</p>
222
+ <p>DEFAULT: empty</p>
223
+ <div class="last line-block">
224
+ <div class="line">EXAMPLE (1 group, 1 hierarchy):</div>
225
+ <div class="line">- &quot;alt.test&quot;</div>
226
+ <div class="line">- &quot;^news.*&quot;</div>
227
+ </div>
228
+ </dd>
229
+ <dt><strong>DEBUG_LOG</strong></dt>
230
+ <dd><p class="first">The name of a file, where debug messages are written. Setting this
231
+ variable will enable the log. Leave empty to disable logging.</p>
232
+ <p>CONTENT: The name of a writable file, which will be created if inexistent
233
+ and overwritten if need be.</p>
234
+ <p>DEFAULT: empty</p>
235
+ <p class="last">EXAMPLE: '/tmp/a_log-file.txt'</p>
236
+ </dd>
237
+ <dt><strong>LOG LEVEL</strong></dt>
238
+ <dd>One of debug, fatal, error, info, warn</dd>
239
+ <dt><strong>REFERENCES_SEPARATOR</strong></dt>
240
+ <dd><p class="first">A symbol or sequence of symbols marking the end of the message-body and the
241
+ beginning of a list of “references” or “footnotes”. It will only appear, if
242
+ the original message-body contains text marked for use as such a footnote.
243
+ See <em>REFERENCES_DELIMITER</em>.</p>
244
+ <p>If the option is not defined or empty, the list of footnotes will appear
245
+ below the last line of the message body and no separator will be inserted.</p>
246
+ <p>CONTENT: A quoted symbol or sequence of symbols.</p>
247
+ <p>DEFAULT: empty</p>
248
+ <p class="last">EXAMPLE: '---------'</p>
249
+ </dd>
250
+ <dt><strong>REFERENCES_DELIMITER</strong></dt>
251
+ <dd><p class="first">A sequence of at least two symbols marking the beginning of a text which will
252
+ serve as footnote (or reference). The <strong>reversed sequence</strong> musst be used to
253
+ mark the end of the text. The presence of this sequence or symbol in the
254
+ original message body will cause the enclosed text to be moved below the
255
+ message body. The <em>REFERENCES_SEPARATOR</em>, if defined, will separate the
256
+ message from the list of footnotes.
257
+ If this option is not defined or empty, footnotes are not created.</p>
258
+ <p>CONTENT a quoted symbol or sequence of symbols.</p>
259
+ <p>DEFAULT: none/empty</p>
260
+ <p class="last">EXAMPLE: '%?'</p>
261
+ </dd>
262
+ <dt><strong>REFERENCE_FORMAT</strong></dt>
263
+ <dd><p class="first">A format-string, using %s for a number, replacing the reference-
264
+ text in the message body.</p>
265
+ <p>DEFAULT: &quot; %s)&quot; -&gt; becomes 1) ... 2) ... 3)</p>
266
+ <p class="last">EXAMPLE: &quot;(%s)&quot; -&gt; becomes (1) ... (2) ... (3)</p>
267
+ </dd>
268
+ <dt><strong>VFY_URLS</strong></dt>
269
+ <dd><p class="first">A Boolean constant. It determines if the program shall verify and possibly
270
+ try to correct URLs. Even if URLs are identified as such, only a few
271
+ manipulations are attempted :
272
+ * Angular brackets '&lt;' and '&gt;' are added, if missing
273
+ * Slashes are added, if they are found missing after &quot;http(s):&quot;</p>
274
+ <p>If the variable is not set, a value 'yes' is assumed.</p>
275
+ <p>CONTENT: One of YES, yes, NO, no, and other variations of case.</p>
276
+ <p>DEFAULT: yes</p>
277
+ <p class="last">Example: ... I let you guess.</p>
278
+ </dd>
279
+ <dt><strong>OVERRIDE_CONFIG</strong></dt>
280
+ <dd><p class="first">A Boolean constant. You can choose to override the following configuration
281
+ options before an article is posted: GROUP_SIGS, XNAY_GROUPS, CUSTOM_HEADERS,
282
+ DEBUG_LOG and VFY_URLS. A dialog may be displayed which allows you to disable
283
+ any of these five options, so that the defaults from flnews prevail.</p>
284
+ <p>ATTN! Canceling the dialog or pushing the Esc-key does interrupt the process.
285
+ Flnews will not post the article.</p>
286
+ <p>Set this option to no, NO or similar to disable the dialog.</p>
287
+ <p>DEFAULT: yes</p>
288
+ <p class="last">EXAMPLE: No</p>
289
+ </dd>
290
+ </dl>
291
+ </div>
292
+ <div class="section" id="other-information">
293
+ <h1>Other Information</h1>
294
+ <div class="section" id="testing">
295
+ <h2>Testing</h2>
296
+ <p>The effects that the execution of the program will have on a posting can be
297
+ verified in two ways:</p>
298
+ <ol class="arabic">
299
+ <li><p class="first">By piping-in a post that had previously been saved to a file:</p>
300
+ <p><strong>:~$ /usr/local/bin/[post-processor] &lt; [test-article]</strong></p>
301
+ <p>This will show the resulting new version of the article on screen, but you
302
+ can also pipe the output into another file. This is a great way to test a
303
+ program during development or to test your own configuration of the program.</p>
304
+ </li>
305
+ <li><p class="first">By posting directly into a test-newsgroup (like alt.test or similar). This
306
+ is mandatory before you really post to thematic newsgroups and when the
307
+ settings of the post-processor will affect the article.</p>
308
+ </li>
309
+ </ol>
310
+ </div>
311
+ <div class="section" id="source-code">
312
+ <h2>Source-Code</h2>
313
+ <p>The gem-file that you get with the gem-utility or from rubygems.org contains
314
+ all the code of the program and some documentation (this page notably). To read
315
+ its content, you must</p>
316
+ <ol class="arabic simple">
317
+ <li>untar the gem-file with tar -xf flnews_post_proc-0.1.gem</li>
318
+ <li>uncompress the data.gz archive: gunzip data.gz</li>
319
+ <li>untar the resultig data.tar archive: tar -xf data.tar</li>
320
+ </ol>
321
+ <p>This creates the directories bin, doc and lib.</p>
322
+ </div>
323
+ <div class="section" id="license">
324
+ <h2>License</h2>
325
+ <p>flnews_post_proc is distributed under the conditions of the WTFPL-2.0 or later
326
+ License (see <a class="reference external" href="http://www.wtfpl.net/txt/copying/">http://www.wtfpl.net/txt/copying/</a> or license-text in the doc
327
+ directory of the gem-file).</p>
328
+ </div>
329
+ <div class="section" id="author">
330
+ <h2>Author</h2>
331
+ <div class="line-block">
332
+ <div class="line">flnews_post_proc has been developed by</div>
333
+ <div class="line">Michael Uplawski &lt;<a class="reference external" href="mailto:michael.uplawski&#64;uplawski.eu">michael.uplawski&#64;uplawski.eu</a>&gt;</div>
334
+ </div>
335
+ </div>
336
+ </div>
337
+ <div class="section" id="section-1">
338
+ <h1>Ω</h1>
339
+ </div>
340
+ </div>
341
+ </body>
342
+ </html>
data/doc/license.txt ADDED
@@ -0,0 +1,13 @@
1
+ DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
2
+ Version 2, December 2004
3
+
4
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
5
+
6
+ Everyone is permitted to copy and distribute verbatim or modified
7
+ copies of this license document, and changing it is allowed as long
8
+ as the name is changed.
9
+
10
+ DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
11
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
12
+
13
+ 0. You just DO WHAT THE FUCK YOU WANT TO.
Binary file
Binary file