flnews_post_proc 1.7

Sign up to get free protection for your applications and to get access to all the features.
@@ -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