textfiles/internet/cppnews.txt

Preliminary cppnews documentation $Revision: 1.2 $

The significance of the cppnews.ini variables
=============================================

File and directory names
~~~~~~~~~~~~~~~~~~~~~~~~
<news_dir> is set from your CPPNEWS environment variable. If there is no
CPPNEWS environment variable, the SNEWS environment variable is tried
instead. If there is no SNEWS environment variable either, the current
directory is used. 

Filenames for the various files used by the system, and the use of each
of these files, is given below ...

cppnews.ini - <news_dir>\cppnews.ini

This is where the cppnews.ini file is expected. If none exists, the 
default values of the variables are taken from any existing SNEWS.RC file.
The file is re-written to this directory on normal program exit.
To change most of the other variables, the normal method is to edit this 
file. It is not normally necessary to edit any of the other files used by 
the system (except the signature file), and in many cases an incorrect 
edit can prevent the proper function of the news reading system.

Newsgroups index - <newsdir>\active

This is created by the snews unbatch, addgroup and rmgroup programs. It 
contains a list of all active groups, with a line for each group giving 
the group name, the filename and the first and last message numbers.

DO NOT attempt to edit this file yourself, unless you REALLY know what you
are doing.

To add or remove groups, use the snews addgroup and rmgroup programs, 
respectively.

Articles read list - <news_dir>\<userid>.nrc

This is a list of all the newsgroup articles that have been read. It 
contains records, one per logical line, of a newsgroup name followed by a 
space-separated list of article numbers. A logical line is split over 
multiple physical lines by including a backslash character (\) at the end 
of each physical line.

DO NOT attempt to edit this file yourself, unless you know what you are
doing. 

The file is automatically maintained by cppnews. You can mark articles, 
threads and whole groups as read or unread using cppnews menu options.

Kill file - <news_dir>\<userid>.kil

This is a list of hash codes of subject lines that have been "killed". 
Hash codes are used for speedy lookup, and to allow some "fuzzy matching" 
in subject lines. 

I can't see any purpose behind editing this file - it is just a list of 
apparently meaningless numbers !

This file is automatically maintained by cppnews on normal exit from the
program. Thread/Kill and Thread/Revive menu options are provided to add
and remove subject lines from the kill list. 

Incoming mail folders - <maildir>\*.<mailext>

Cppnews uses this mask to look for mail folders. If you create a new folder
within cppnews, it will be created in the <maildir>, so it can be found 
next time.


The contents of this file are mail messages. The start of a new message is
recognised by the <startofheader> string at the beginning of a line.
My mailer justs throws the messages onto the end of the file, so I use
"From " (note the space) as my <startofheader>. Some mailers place a 
special marker between each message (e.g. a ^A character) - if yours does,
use this as your <startofheader> (you will need a good editor to place a 
^A character in your cppnews.ini).

Once cppnews has read the mailbox, it reformats it to place its own 
markers between each message. This header includes the size of the 
message, and offsets to various important header lines, so subsequent 
reading of the file is much faster. New messages added to the end by your 
mailer are recognised as such the next time you run cppnews.

DO NOT attempt to edit this file yourself, unless you know what you are
doing - you could lose mail messages altogether if you change the number
of characters of text in a message that has been reformatted by cppnews.
You can add new messages to the end of the file, though, but beware of 
text editors that invisibly change the text (e.g. removing trailing 
spaces, expanding tabs, changing line feed delimiters).

Group file -<news_dir>\newsbase\*
Group index - <news_dir>\newsbase\*.idx

The snews unbatch and expire programs create and maintain these files.
There is one text file and one index file per group. The filename is 
obtained from the Newsgroups Index. The text file contains all the news 
postings, separated by a line containing "@@@@END" (although this latter 
is not essential). The index file contains one line per posting, with the 
offset of the article in the file, the article number, the date the 
article was added to the file by unbatch, and the article subject.

DO NOT attempt to edit these files yourself, unless you REALLY know what
you are doing. The index file contains pointers into the text file, so 
they must be kept in step (e.g. when doing backup/restore).

Signature - <home>\<signature>

You can edit this file to place any signature text you want to follow all 
your mail messages and news postings. It is automatically read in to the 
editor buffer ready for you to compose your message. Please bear in mind 
that your signature uses up net bandwith, so don't go overboard !

Outgoing mail sequence number file - <mailqueue>\sequence.seq
Outgoing mail work files - <mailqueue>\*.wrk
Outgoing mail text files - <mailqueue>\*.txt

Cppnews places all outgoing mail messages into the <mailqueue> directory.
The sequence.seq file contains the number of the last item posted to the
queue. This file is updated during each posting. This form of posting is 
known to be compatible with KA9Q. Support for other mail agents with 
different queue schemes will be considered. If your mailer is different,
let me know the details by mailing cppnews@trmphrst.demon.co.uk.

The .wrk and .txt file use this posting number as the filename. Each .txt 
file contains the complete message, and the .wrk file contains routing 
information - the destination machine, the fully qualified sender name, 
and the fully qualified recipient name.

Unused cppnews variables - <tempdir> and <newsdir>

These are not currently used in cppnews, but are maintained in case of
future enhancement. 

Posting messages
~~~~~~~~~~~~~~~~
Cppnews expects messages posted to newsgroups to be handled by a news/mail
server. Cppnews versions up to 1.18 only support one kind of newsserver - 
a dummy mail address "mail2news@<newsserver>" which accepts articles for 
posting, and despatches them to the newgroups in the header.

There is another kind of news/mail server, which accepts articles posted 
to a user name derived from the newsgroup name, and posts to that group. 
Some of these servers accept the newsgroup name unchanged, and some need 
the full stops (.) in the newsgroup name changed to some other character.

Cppnews 1.18 will introduce improved newsserver support using a new 
cppnews.ini variable <servername>. This can be set to ...
The name (like "mail2news") of the first kind of server above.
A single punctuation character (.,-% etc.) to indicate the second kind of 
server above. The newsgroup name will have any full stops (.) in the name
changed to the specified character. Specify a full stop (.) character for 
no translation.

Cppnews generates default headers for mail and news postings, as follows ...

Path: <nodename>.<domain>!<userid>
From: <userid>@<nodename>.<domain> (<name>)
ReplyTo: <userid>@<nodename>.<domain>
Subject: Re: The subject of the message/article to which this is a reply
References: The message ID of the message/article to which this is a reply
Cc: <mailcc> or <newscc> as appropriate
Bcc: <mailbcc> or <newsbcc> as appropriate
Distribution: world (news postings only)
Followup-To: The first group on the To list (news postings only)
Message-ID: A unique ID based on the time posted, <nodename> and <domain>
X-Mailer: cppnews revision number
Date: The date posted. Cppnews takes notice of your TZ environment 
      variable. U.K. users should set it to GMT0BST.
Organization: <organisation>
Lines: The number of newlines in the message.

Other cppnews.ini variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Your text editor - <editor>

This should be set to the command line to call your editor, with a "%s" 
sequence where the file name should be.
There are some strange and wonderful editors out there. A few pitfalls to 
look out for ...

Some editors are too big to fit in memory along with cppnews. You can 
change the amount of memory cppnews takes by adjusting the <maxarticlesize>
variable. This can take values from 1 to 63, and is the number of kbytes 
that cppnews can use to hold article text in memory. Some editors are just
too big even with <maxarticlesize> set quite small. I did consider 
swapping cppnews out of memory, but the delay in calling up the editor 
every time a message is posted would be unacceptable.

Some editors won't edit an empty file ! The solution to this problem is to
create a signature file, so that your blank message for posting is never 
empty.

Some editors don't output straight ASCII text files. Most wordprocessor
files contain control characters and information, and are unsuitable for
posting to the net. Some wordprocessors have a special ASCII file save 
option, but a simple, small text editor is the best thing to use. There 
are so many free text editors available it would be pointless to write an 
internal editor for cppnews.

Article quoting prefix - <quotemark>

When you quote an existing message, the <quotemark> characters are added 
at the start of every line. Most people use "> " (note the space).

Tab setting - <tabwidth>

Tab characters in articles are expanded to tab stops every <tabwidth> 
characters.

Word wrap width - <wordwrap>

Long lines in articles are not usually wrapped by cppnews. If you set 
<wordwrap> to a non-zero value, lines will be wrapped at a word break near
this column. This value can be changed using the cppnews Options/Wordwrap 
menu option.

Posting logs - <newslog> and <maillog>

If these variables are set to a mail folder name (up to 8 characters), 
all news and/or mail postings are copied to the folder.


Notes
~~~~~
It may appear that because some of the file names used contain a user 
name, that cppnews may be used by a number of different people. This is 
currently NOT the case - the user name comes from cppnews.ini, which must 
be in the newsbase directory, and the program makes ALL mailboxes publicly
available, no matter what the setting of "userid".

I do intend to rectify this situation some time in the future. If you have
a need for this (or any other) feature, feel free to mail the cppnews 
support mailbox - cppnews@trmphrst.demon.co.uk. I keep a list of all 
requests, with the number of (different users :-) requesting each one, and
this helps me decide development priorities.