Preliminary cppnews documentation $Revision: 1.2 $ The significance of the cppnews.ini variables ============================================= File and directory names ~~~~~~~~~~~~~~~~~~~~~~~~ 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 - \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 - \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 - \.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 - \.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 - \*. Cppnews uses this mask to look for mail folders. If you create a new folder within cppnews, it will be created in the , 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 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 . Some mailers place a special marker between each message (e.g. a ^A character) - if yours does, use this as your (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 -\newsbase\* Group index - \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 - \ 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 - \sequence.seq Outgoing mail work files - \*.wrk Outgoing mail text files - \*.txt Cppnews places all outgoing mail messages into the 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 - and 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@" 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 . 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: .! From: @. () ReplyTo: @. 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: or as appropriate Bcc: or 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, and 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: Lines: The number of newlines in the message. Other cppnews.ini variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Your text 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 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 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 - When you quote an existing message, the characters are added at the start of every line. Most people use "> " (note the space). Tab setting - Tab characters in articles are expanded to tab stops every characters. Word wrap width - Long lines in articles are not usually wrapped by cppnews. If you set 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 - and 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.