Xnews

Behold, I send thee forth as newbies in the midst of wolves, so RTFM! (read the fine manual)

Copyright © Luu Tran 1998-2002. All rights reserved.
http://xnews.newsguy.com

Note: changes.txt contains the latest changes and is updated more often than the manual, so be sure to read it too. Lots of good stuff in there!

This is freeware. It may be freely distributed provided the copyright and the contents of all files, including xnews.zip itself, are unmodified. Needless to say, you can't charge money for it. The usual caveats apply, i.e., use at your own risk, etc. etc. :-)

Now that I've released Xnews to the net, I'm getting lots of email. So, if you have a question or problem, please:

  1. read this manual.
  2. read it again.
  3. try to figure it out yourself.
  4. try harder.
  5. ... and if you're still stuck, post your question to news:news.software.readers. If you do not have access to a news server, or if you have not set up a newsreader, you can try reading through Dejanews.

Note: Due to past bad experiences, I've regrettably decided to stop answering technical support questions via email. Please direct your questions to the newsgroup.


Note: read at least the first 5 sections for starter. Also, look at changes.txt to see what's new.

Contents

  1. Is this program for you?
  2. QuickStart Guide
  3. Basic things you need to know about Xnews.
  4. How do I...
  5. Hidden keyboard shortcuts / Keyboard tips
  6. Troubleshooting / FAQs
  7. What is _____
  8. Hidden Tips and Tricks
  9. Filters, filters everywhere
  10. Organizing subscribed groups into categories
  11. Header and article storage
  12. Folders
  13. Xnews.ini: Global settings
  14. Groups.ini: Group-based settings
  15. Plonk file
  16. Score file
  17. Regular expression
  18. Acknowledgements

Is this program for you?

This program is in perpetual beta cycle. It's my hobby project and I favor frequent updates over stability. There is no help file, just this manual.

Xnews is a general-purpose reader. Although it handles binaries (quite nicely for my purpose), it's not a binary grabber or picture viewer. Also, Xnews is an on-line reader. It has pseudo offline features such as header storage, but if you need true off-line capabilities, use Agent, Gravity, or something else.

I'm a fan of NewsXpress so I liberally stole ideas from that program. NX users should find Xnews familiar. That said, Xnews is not NewsXpress. I didn't try to clone it. I have my own weird ideas of doing things. Although Xnews may bear some resemblance to NX, it has some features the latter doesn't while lacking others.

About this document: I know it's rather minimal but please read it. I assume you have used other newsreaders before and basically know how usenet works, so I will only go over things that are different about/specific to Xnews.

I wrote Xnews for me to use. The program heavily reflects my preferences, habits, and sensibility. Yes, extensive end-user research went into the making of this software, albeit of only one user. The interface is a bit quirky and the program has that freeware feel to it. If you think Microsoft represents the apotheosis of good software design, this program is probably not for you. If not, you may learn to like it -- or not. It's free, so what the hey.

That said, if there's something you want to see added/changed, it doesn't hurt to ask. Provided that the change will result in the greatest happiness to the greatest number of people while causing the least amount of pain to me, I may just do it.

Cheers.

Back to top


QuickStart Guide

If you are using Windows95 and have not installed Internet Explorer, you may need to download the new comctl32.dll from Microsoft. (If you run Xnews and don't see any icon, or if the list appears to be empty even though the program seems to be retrieving data, then you probably need to get the dll.)

There's no install program. Just unzip to some directory then run Xnews.exe. If you are upgrading, just unzip into the same directory and overwrite everything.

The first time you run Xnews, it will bring up the Setup dialog. Enter your name, etc. I'll only describe the unfamiliar items here.

Public Email
This is the email you want to put in your From: header when posting to usenet. In contrast. Email is the email you want to to use when replying via private email.
Why use separate emails for usenet and mail? I do it to help deal with spam.
IDToken
This is a string Xnews embeds in Message-ID in order to track your posts and alert you to replies to your articles. You can use any string of letters and numbers. I use my email without the @ and . luutrangeocitiescom. The idea is to use a string that noone else is likely to use.

Once you've done that, click Okay. Xnews will ask you to create a server profile. (The program can deal with multiple servers.) Enter the server name, e.g., news.mindspring.com. Then enter an alias or title for the server, e.g., Mindspring. The alias is what will appear on the menu.

That's it. You should now say yes when it asks if you want to retrieve the newsgroup list. Kick back and enjoy.

Back to top


Basic things you need to know about Xnews.

First, a bit of terminology: when I say "groups window", I mean the window that lists all the groups in a server. "articles window" refers to the window that lists all articles in a group and also displays the selected article.

The groups window:

The articles window:

General:

Back to top


How do I...

Q: ... retrieve the last n headers from a newsgroup.

A: Instead of pressing Return to open the group, press Ctrl+Return. This will bring up a dialog that lets you select how many headers to retrieve. This is useful for sampling a group with a huge number of headers. When in the article window, you can bring up this dialog by selecting Article | Refresh Headers Special (Ctrl+F5). For example: press Ctrl+Return open a group and specify 100 headers to retrieve. Xnews will retrieve the newest 100 headers. Then you decide you want to read the older articles. Hit Ctrl+F5, then move the slider back to the left until you get the number of headers you want, or all the way to the left to get everything.

Q: ... decode/save/transfer several articles at once?

A: Xnews uses a queuing system. To put an article into the queue, press Space. Pressing space again removes it from the queue. When you queue an article, you will see a number indicating its queue order in the Q column. Now, select Article | Decode/Save as... or Transfer | (folder). You can also queue/dequeue an entire thread at a time.

Q: ... decode multipart binaries?

A: By default, Xnews performs multipart threading in groups that have "binaries" in the name (much like NewsXpress does). Multipart threading means it will put all the parts of a file and roll it under a thread. If a file has all the parts, you will see a 4-block cube icon next to it; if it has one or more missing parts, the cube will have a missing block. Also, if you look at the lines column, it will tell you exactly how many parts there are and how many are present.

To queue a multipart file, just select the thread (with the block icon), and hit space. Xnews will tag all the individual parts for you. Then hit decode.

Hint: with certain file types, it's possible to "sample" the file this way: expand the multipart thread, then individually queue a few parts, e.g., 1/10, 4/10, 8/10 You must queue the first part. This works well for, say, mp3 files but obviously not zip files as they will be corrupted and unreadable. (Caveat: I think "sampling" doesn't work for MIME-encoded files.)

A few words on smart decoding

Starting with version Y2K-SE, Xnews can resume an interrupted multi-part decode from the last successfully decoded part (as opposed to doing the whole thing over). It does this by saving some state information about the decoded file in *.ini files in the temp\ folder. If you're decoding a multipart file and it gets interrupted, you'll see the name of the decoded file changed into

filename__error_part_X.ext

Don't delete or rename this file. You'll also see some *.ini files in the temp\ folder. Don't delete those either. Go back and queue the file you were decoding, starting from part X. Example: if the file is in 20 parts and X is 14, you should queue parts 14-20. Click decode and Xnews should pick up where it left off. (Actually, you don't need to queue just parts 14-20; you can queue the whole thing normally and Xnews should figure it out, but the first way may be safer.)

If this feature gives you problems, you can disable it by setting Xnews.ini [Misc] UseSmartDecode=0

Q: ... cancel a message?

A: To cancel a message, you have to find it and retrieve it first. You can do this by opening the group as usual, or by using XPAT search (see next section).

Q: ... use XPAT search?

A: Most servers have a function called XPAT search, which performs server-side search for articles (in other words, search what's on the server, as opposed to what you have on your computer). To do a search, select which field, or header, you want to search on. Most of the time, you probably want to search by subject or author. The search string is a Unix wildmat, which means unless you want to search for an exact string, you need to surround the string with wild cards (asterisks). For example, if you enter help, you won't turn up anything unless there's an article with the exact subject help. Instead, type *help* On the other hand, there's no need to type *[Hh][Ee][Ll][Pp]* (case insensitive search) because Xnews will do that for you (thank goodness).

Q: ... add custom headers to postings?

Select SetUp | Compose. Enter the custom headers you want on separate lines. If you want a header to be "on" by default, precede it with an asterisk. You can enter a blank header and fill in the value at compose time. Here's an example:

*X-No-Bananas: yes
Approved: luutran@geocities.com
*Keyword:

The first header will be on by default (you can turn it off at compose time). The second header, Approved, already has the value filled in but not turned on by default. You can switch it on on-the-fly and change the email address too if you want. The third header is on by default, but has nothing filled in yet. At compose time, you can enter something or just leave it blank. If you leave it blank, Xnews will simply ignore it (therefore, it's a good idea to switch all blank headers on by default). Note that even with a blank header, you still need to put in the colon (:)

You will find these custom headers in the Custom tab in the editor window. You can also add a header not in the Custom tab by switching to the Manual headers tab and type it in.

Q: ... use ROT-13?

ROT-13 is a very simple scheme to scramble text so it is not immediately readable. What it does is transpose every letter by 13 alphabet position, so A - M become N - Z and vice versa. People use ROT-13 to scramble messages that may be offensive or messages that contain spoilers (ending of movies, punch lines, etc.). The idea is that the reader must first unscramble the message before reading it, so s/he cannot read it by accident. Some people also scramble their email addresses to spur spammers.

Anyway, to unscramble a ROT-13 message, just select View|ROT-13. In the editor, you can scramble/unscramble a) the article text; b) the To: address; and c) your own Public Email. First place the caret on the text you want to scramble/unscramble then click ROT-13.

In all cases, you can also apply ROT-13 to just a portion of the text by first selecting it with the mouse or keyboard.

Q: ... hide a column in the list?

You can't hide a column, but you can just resize the width to nothing. Does more or less the same.

Q: ...save an attachment?

By default, Xnews does not automatically save attachments in articles when you open them. You can change this in Setup|Files. You can also specify which types of files you want to be automatically saved. To manually save an attachment, click the attachment icon (it looks like a pin) and select the attachment from the list. Selecting an attachment that's already saved will open it.

Q: ...post attachments / binaries?

To attach a file, click the Attachments tab then click Add... You can select multiple files at once. Alternatively, you can drag and drop files from the Windows Explorer.

The options:

  1. [post attachments] together under one subject: this posts all attachments in one big message, which may or may not be multipart. Say your message is titled "My cats (with pictures)" and you attach 2 files, it'll appear like this in Xnews

    My cat (with pictures) - 2 attachments (~/4)
    

    If you uncheck "Show file count in subject" it will not display - 2 attachments.

    This option is most appropriate for posting a few (<3) smallish files in a discussion group (assuming its members condone the practice). Your text (the part you wrote in the editor) will be embedded inside the message. Using MIME in conjunction with this option would be fine. Do NOT use this option when posting large files or a series of small or large files.

  2. separately: each attachment as well as your text is posted in a separate (possibly multipart) message. This is how files are typically posted in binaries groups. Your text should be a descriptions of the files to follow. Assuming your message subject is "Pictures of my cats", this option will produce:

    Some pictures of my cats - File 0 of 2
    Some pictures of my cats - File 1 of 2 - socks.jpg (~/2)
    Some pictures of my cats - File 2 of 2 - socks2.jpg (~/4)
    

    If you uncheck "Show file count in subject" it will not display - File X of Y.

    File 0 will contain your text message. If you leave the text body blank (which you are allowed to when posting attachments), there'll be no file 0.

  3. separately; text in 0 part of first file: same as above, except the text part becomes the 0 part of the first attachment. In Xnews, it looks like this with the first file expanded.

    Some pictures of my cats - File 1 of 2 - socks.jpg (~/2)
      Some pictures of my cats - File 1 of 2 - socks.jpg (0/2)
      Some pictures of my cats - File 1 of 2 - socks.jpg (1/2)
      Some pictures of my cats - File 1 of 2 - socks.jpg (2/2)
    Some pictures of my cats - File 2 of 2 - socks2.jpg (~/4)
    

  4. separately; text in 0 part of each file: same as above, except the text part becomes the 0 part of every attachment. In Xnews, it looks like this with all files expanded
    Some pictures of my cats - File 1 of 2 - socks.jpg (~/2)
      Some pictures of my cats - File 1 of 2 - socks.jpg (0/2)
      Some pictures of my cats - File 1 of 2 - socks.jpg (1/2)
      Some pictures of my cats - File 1 of 2 - socks.jpg (2/2)
    Some pictures of my cats - File 2 of 2 - socks2.jpg (~/4)
      Some pictures of my cats - File 1 of 2 - socks2.jpg (0/4)
      Some pictures of my cats - File 1 of 2 - socks2.jpg (1/4)
      Some pictures of my cats - File 1 of 2 - socks2.jpg (2/4)
      Some pictures of my cats - File 1 of 2 - socks2.jpg (3/4)
      Some pictures of my cats - File 1 of 2 - socks2.jpg (4/4)
    

    Some people seem to like option 3 or 4. I prefer option 2. In any event, avoid option 1 if you are posting large files or get ready to be flamed.

In general, avoid using MIME since some newsreaders can't handle it. (IIRC, NewsXpress can't decode multipart MIME messages.) As you probably know, usenet messages exceeding a certain sizes tend to be dropped by servers, so large messages have to be cut into smaller parts. Xnews uses a default cut size of 8000 lines.

Observe the rules and conventions for the group you are posting to. For starter, make sure binaries are allowed. Follow as much as possible the predominant posting patterns (i.e., cut size, whether to use MIME, etc.). Above all, post in a test group first to make sure you're getting the expected result.

A couple more points: 1) the options above only apply to usenet posting. When mailing, I always use MIME and send all attachments as only large message; 2) When posting a series of files, it is highly recommended that you save to the outbox and send from there. This way, if something goes wrong or if you need to stop the posting process, you can select which file to repost.

Q: ...cut/copy/paste text when there's no Edit menu?

Believe it or not, you use the keyboard. Shift+Del=cut, Ctrl+Ins=copy, Shift+Ins=paste.

Q: ...cross post to several groups?

You can just type in their names manually, separated by commas. Or multi-select the groups you want in the groups window then press ctrl+P. You do know how to multi-select, don't you? Just hold down the ctrl key and click, click, click.

Back to top


Hidden keyboard shortcuts / Keyboard tips

Most shortcut keys are either shown on the menus or listed in the keyboard mapping dialogs. These are shortcuts that are NOT.

In articles window:

Space Queue/Dequeue article/thread (place in queue)
Shift+Space Queue/Dequeue article/thread, but put in head (instead of tail) of the queue
Ctrl+Space Queue everything in sight (WARNING: does NOT tag multipart binaries intelligently)
Ctrl+Shift+Space Clear queue
Ctrl+Up/Down Resize the split window.

In article viewer:

Space page down
Shift+Space skip to next non-quote paragraph
Backspace page up
Return switch to article listing
Num1..Num9 (number1 through 9 on the keypad). If using split screen, scroll the list while the cursor is in the viewer.

In groups window:

Ins manually add a group
Del permanently delete selected group(s) from the newsrc
F4 Switch between subscribed/all groups

In groups window, article listing and viewer

Ctrl+Del clear out all items in combo boxes

These shortcuts are in the keyboard map dialog but I'll list them here just in case.

In article listing and viewer

? / previous / next unread
> . previous / next article (read or unread)
< , previous / next queued article
; ' previous / next thread
\ next article with >0 score (see scoring.txt)
` (backquote) next new article since last stored header retrieval
(see the section on storage)
Alt+Left Go back in history
Alt+Right Go forward in history

A few words on remapping the keyboard.

Back to top


Troubleshooting / FAQs

Q: When I try to post something, I get "bad message ID" error from the server.

A: Try using a shorter IDToken (Setup | Identity). If that doesn't work, remove the IDToken.

Q: Why is it that the get parent article command, when successful, sometimes inserts the found article in the listing and sometimes does not?

A: Xnews relies on the message number to insert articles into the list. If it doesn't show the found parent article in the list, it means that the server did not return the message number (the server assigns a number to every article in a group). I don't know enough about server software to explain why, but that's how it is.

Q: How come when I close an articles window, sometimes the program update the message count and sometimes it doesn't?

A: Xnews considers automatically updating the message count a low priority task, so if there's no available connection, it doesn't do it. Of course you can force it by pressing F5.

Q: When a download starts, the window caption shows the elapsed time and approximate remaining time. But this goes away after a few seconds. How do I get it back?

A: Just click on the gauge, aka progress bar.

Q: Why doesn't crosspost killing seem to be working?

A: In order for crosspost killing to work, all of the following conditions must be satisfied:

  1. The poster must have truly crossposted to the groups and not merely posting the same article separately to each group. In the latter case, even though you can tell that it's the same article, there's no (efficient) way for the program to do the same.
  2. Xnews relies on the Xref header to do crosspost killing. Xref is a site specific header that tells a) what group(s) the article has been posted to; and b) its article number in each respective group. Xnews requires that your news server is configured to carry this header in its news overview (NOV) database and that the news server returns this information in response to a XOVER command. Not all servers do this.
  3. For efficiency's sake, I only check subscribed groups when killing crossposts. This makes it much faster to do a "Mark all read" command and also helps keep down the size of the newsrc file.

Q: I use a foreign (non-English) keyboard, but I keep getting the English keyboard in the editor window

A: Open Control Panel -> Keyboard. Select the Languages tab. Now UNINSTALL all keyboards except the one for your language.

Back to top


What is ________

Q: Mark keep/unkeep?

A: If you do not have storage on, when you do a catchup, the next time, you will not see the headers you've retrieved. If you mark an article or thread as keep, the program will retrieve it again the next time, even if you did a catchup. When you keep something, it automatically gets assigned a high score so it'll stand out next time.

One example where this is useful is when you have a multipart binary with some parts missing. If you do a catchup, next time you may retrieve the missing parts, but then the parts you had before will now be gone. In this case, you want to keep those parts you have and hopefully get the rest next time.

If you are storing headers, kept articles are never deleted except when they expire on the server. That is, they are protected against deletion and local expiration (the expiration you set in the Storage Options dialog). If you want to delete a kept article, you must first unkeep it.

You can specify what score to automatically assign to kept articles in Setup | Misc. If you set this to zero, no score will be assigned to kept articles.

Q: Mark High score/0 score?

A: This is equivalent to marking something as important/not important. It simply assigns a score of 9999 or zero to selected threads/articles. You can then right click on the Score column (or select View | Filter Scores) and select a score filter to view only high scored articles.

Q: What's with all the catchup options?

A: Traditionally, "catchup" in newsreaders means to update the read count to the last article seen. If you look at the newsrc, you'll see a bunch of number like

1-50,55,65-80.

Each article is assigned a number by the server, and these numbers in the newsrc indicate which articles you have read. When you do a catchup, the program sets this to

1-<highest-numbered article retrieved>

"Catchup" basically means "okay, I've seen all I care to. Don't show me these articles next time." Note that you may not have actually read all these articles; you just want to treat it as if you did.

In the articles window, there are 3 catchup options (all of which will close the window):

Whew! Was that confusing enough?

In the groups window, there are separate catchup and clear keep commands. Note that in order to do a catchup, you must have updated the message count once. The "Clear read and keep" command simply clears out the newsrc entry for the selected group(s), letting you essentially start anew.

Q:Reformat (in the editor window)?

Often, when you reply to an article and insert the quote character > in front of a line, it becomes too long and gets wrapped by the editor. You may end up with something like this:

Before quoted:

>this is a very very very very very long long line,
>isn't it?

After quoted:

>>this is a very very very very very long long
line,
>>isn't it?

You can fix this by 1) enlarging the window so the text will fit on one line; or 2) clicking Reformat. In the latter case, Xnews will rewrap the text as

>>this is a very very very very very long long
>>line, isn't it?

Much nicer, right?

When you click Save or Send, Xnews will try to detect whether there is any badly wrapped text like the above example and ask if you want it fixed. If you say yes, it will fix it and return you to the editor. You should go over the text and make sure everything looks okay.

Btw, you can fix just a portion of text by selecting it before clicking Reformat.

I decided to leave it up to the user to do this rather than doing it automatically. I give you the mean, but it's up to you to help keep usenet beautiful (you'll also keep me from being flamed for making crappy software).

Q:the meaning of different icons in the article listing

I thought this was obvious, but then, I wrote the program :) Ok, here's the 411:

green dot   = read article.
blue border with line across = kept article.
white note with lines = regular article (default icon)
white note, no lines  = (only if you are storing headers) the article is old
                        i.e., it is in storage.  The ones with lines are the
                        headers that are new since last time you 
                        read this group.
green note  = article body is in the cache. If you re-read it, 
              the article will be read off the disk (very fast)
!           = article has 9999+ score
3 blue cube = incomplete binary (at least 1 or more missing parts)
4 blue cube = complete binary (all parts present)

Back to top


Hidden tips and tricks:

Back to top


Filters, filters everywhere

First, I need to clear up a potential confusion. In many news (and mail) programs, "filters" are used to eliminate unwanted messages (e.g., spam) while flagging desirable messages as important. In Xnews, you do this using the score file. You use filters to pare down the list of visible messages in the articles listing. For example, use the "Show complete multiparts only" filter to see only complete binaries. The other messages are temporarily removed from your view so you'll have a shorter listing to look at. When you remove the filter, you get the entire listing back.

You've already seen the filter box in the groups and articles window, where you can type in a string to show only groups or articles whose names or subjects contain the string. In the articles window, the filter box at the bottom is pretty nifty. (I'll call this the B filter for want of a better name.) You can use a regex (regular expression) in the B filter. In addition, if you want to filter on the author (from) column instead of the subject, right click to the right of the filter box (or press Ctrl+F). The letter should change from S (subject) to F (from). When you are in a folder, you can also switch to G (group) and view only articles from certain groups.

There are some subtleties which I should point out. As you type in a regex, you'll see the result immediately. The list is not yet threaded. To thread it, press Return. Doing this sort of "locks" the filter in place. If you select another filter (see below), or type in another regex, the filter will be applied on top of the current list, i.e., what you see on the screen. On the other hand, you can undo the current filter by selecting View | Undo last filter or by pressing Backspace or Delete to clear the B filter before typing anything else.

There are also predefined filters you can apply. They are

To remove the filter and view all articles, select View | Remove All Filters or left click to the right of the edit box (where the letter S/F/G is). You can also undo the last filter and invert the filter.

Wait, there's more.

In the article list, click anywhere on the score column to bring up a menu that lets you do a filter based on score. The choices are:

There's also a filter dialog (f9) that lets you set a filter based on one or more criteria. First check one or more fields you want to filter on, then enter the appropriate condition.

Note that all the filters are cumulative, i.e., they're applied to what's currently in visible in the list, which may be the result of previous filters and may not be the full set of available articles. The exception is the filter dialog, where you can choose whether to apply the filter on top of the current filters by checking the box "Add to existing". Otherwise, if you want to apply a filter to the original set of articles, you must first remove the filter.

Finally, the last filter you applied will affect incoming articles when you refresh headers. For example, if you click B (hide incomplete binaries), then F5 (refresh), after the headers are loaded and the articles get threaded, any NEW binaries that are incomplete will be filtered out as well and you won't see them until you remove filter.

Here's an example of how you can use filters: assuming you have header stored, after you open alt.tv.x-files, press N. This shows just the new headers. then type in dream.*land (match "dream land" or "dreamland") in the B filter and press return to view articles about the "Dreamland" episode. Then browse through the list and mark the threads/articles you like with the '9' key. This sets their score to 9999. Now click on the score column and select >0 or >=9999 to see the articles you just tagged and any others scored by your score file.

Back to top


Organizing subscribed groups into categories

You can organize your subscribed groups into categories, such as "binaries", "computers", "TV and movies", etc. (Sorry, you can't have sub-categories.) Click on the "New Category" icon or press Alt+Insert then move groups into it. A category is shown with an icon that looks like a folder. You can rearrange categories and groups by drag and drop. A few things to note:

Experiment a little. You'll get the hang of it.

You can collapse and expand all subscription folders by pressing -/+ on the numeric keypad (look at Special | Keyboard Mapping). You can collapse/expand a single folder by pressing Return or clicking on the icon.

You can delete a folder by pressing Del. Deleting a folder only removes the category, not the groups inside it.

When you sort the subscribed list, only the folders and the top level groups (those not inside folders) are sorted. If you want to sort the groups inside the folders as well, hold down the Ctrl key as you click on the column.

The subscription folders are saved separately from the newsrc in a file with extension .Xnewsrc (so newsrc remains backward compatible). If you click on the refresh icon on the toolbar, the program reloads the Xnewsrc file and discards any change made to the subscription folders. This is useful, for example, after you've sorted the folders and want to revert to what you had the last time they were saved.

Back to top


Header and article storage

As I mentioned earlier, Xnews is an on-line newsreader. It does cache articles within a session so that when you re-read an article, it just reloads the article from the cache instead of getting it from the server again. When you close the window, the cache is purged by default.

Once in a while, though, when you quit in the middle of reading a busy group, you don't want to do a catchup since you're not done yet, but you don't want to have to retrieve a lot of headers next time. This is what the Storage feature is for. Storage is basically just a more permanent cache.

Press F7 in the articles window. You'll have the option to store the headers only or both headers and article bodies. You can also specify an expiration so that articles older than X days are automatically purged. If you select never expire, than the articles are removed when they expire on the server.

For efficiency reasons, when an article is removed from storage, it's not actually deleted but only marked as deleted. Thus, the size of the file remains the same. To reclaim disk space, hit F7 then click the "Compact" button.

Note #1: with storage, you can tell the new headers from the stored ones by black lines through their icons (stored headers have blank icons). Hit the ` (backquote) key to jump to the next unread, new article. Also, if the article itself (not just the header) has been stored, then the icon is yellow.

Note #2: on the toolbar, there's an icon indicating the current storage option. Click it for a quick way to change the storage option.

Back to top


Folders

Storage is only semi-permanent. Articles will be purged when they expire on the server, or when they're older than the expiration date you set. For permanent storage of articles, use folders, a.k.a. mailboxes.

To organize folders, open the folders window by selecting Window|Folders (or Shift+F12). Once you've set up a folder, you can transfer articles into it for permanent storage. I already setup a folder called "Archive" for you.

As with NewsXpress, you can define a default folder where articles should be transferred when you click the archive button. Edit Xnews.ini. Under the [Misc] section, set Archive= to the name of the desired folder.

Advanced tricks:

Queue folders

Version Y2K-SE introduces a new type of folders called Queue folders. Unlike the regular (archive) folder, a queue folder stores only the headers when you transfer articles into it. Then when you read or decode the articles, Xnews gets the articles from the server, just as if you're in a newsgroup.

What can you do with such an animal? You can use it as a global queue. You can use it to collect multipart binaries from different servers. Because you can switch what server you want to pull articles from in queue folders, you can pull down headers from one server then retrieve from a different server. If you're one of the lucky dogs with a broadband connection and your server is throttling your speed, you can split your download into two separate queue folders and download simultaneously.

Just as there's a default archive folder, there's a default queue folder. You can set this in Xnews [Misc]. If none is specified, Xnews creates a default queue folder called _Queue (you may also want to name your queue folders with a _ prefix to distinguish them from archive folders). Similarly, there's a counterpart to the Archive command called QArchive, which transfers articles (more accurately, headers) into the default queue folder.

Back to top


Xnews.ini: Global settings

The majority of settings in Xnews.ini can be changed via the Setup dialog. However, there are several that are left out either because they're too obscure or (more likely) because I'm too lazy to add them to the Setup dialog. You have to edit Xnews.ini yourself to change these settings (description follows below). I assume you know how to do this.

A few notes

[Display] section:

Key Type Default Description
AutoSizePctA {0..100} 85 When AutoSize is on, the percentage of available screen area the article list should take up when it has the focus.
AutoSizePctB {0..100} 25 When AutoSize is on, the percentage of available screen area the article list should take up when the article viewer has the focus.
ColumnLayOut integer 1 Number to save the default column layout under. Can be overridden in groups.ini so that you can have different column layouts for different groups.
DateFmtDay Date format hh:nn used for dates within 1 day of today
DateFmtWeek see below ddd dd within 1 week of today
DateFmtYear see below mmm dd within 1 year of today
DateFmtShort see below dd mmm yyyy more than 1 year old; also, %d variable
DateFmtLong see below dd mmm yyyy hh:nn:ss used in popup hints; also, %D variable
DrawTree boolean 1 Thread tree drawing. This option is automatically switched on when you have drawgrids enabled.
FixFlashing boolean 1 Whether to prevent flashing in list windows during pageup/pagedn. Set this to zero only if it causes problems on your system (e.g, if you see garbage on the screen).
FixWrapOpt {-1,0,1} 0 Fix badly wrapped text in the message viewer (-1 = manual: you have to explicitly invoke the command each time; 0 = automatic but not enabled by default; 1 = automatic and enabled by default ).
GaugeUpdateDelay integer 500 Number of milliseconds that must elapse before the progress gauge is updated. Set this value higher if you think the gauge display is slowing down your download.
HideHorzScrollBar boolean 0 Whether to hide the horizontal scroll bar in the article viewer, even if the text is too wide to fit in the window. Set to 1 to maximize screen space. You can still scroll left and right with the keyboard regardless.
HighLightColor color system color color for the highlight bar in list display. Change this if the default high light bar is hard to see.
HighLightTextColor color system color same as above, except it's for the highlight text.
Jpeg boolean 1 Inline display of JPEG graphics
MaxThreadDepth integer 20 Maximum thread depth to indent.
MoveHighlight boolean 1 Whether to move the highlight to the first high score, new, or unread article after a header refresh.
Panel1Width integer 140 Width in pixel of bottom left panel in articles window.
Panel2Width integer 190 Width in pixel of bottom middle panel in articles window.
ShowTabs boolean 1 Whether to show the windows tabs (the little task bar that lets you switch between windows).
SkipHeaders boolean 1 When loading articles, whether to place the cursor past all headers at the start. (Does not apply if showing all headers.
SwitchViewAtThreadEnd boolean 0 When in full screen mode, whether to automatically return to the list when you are reading the last article in a thread and hit next. If 0, then it'll just go to the next thread.
TitleBarLayOut {-1,0,1,2} 0 Controls the appearance of the article-viewer title bar:  -1 = hide title bar;  0 = 2 rows (tool bar and title bar on separate rows) when there's an X-Face, 1 row otherwise;  1 = same as 0, except that when in full screen, use 2 rows;  2 = use 2 rows at all times.
TreeColor color grid color The color that is used for drawing the thread tree. Specify it with =$bbggrr (similar to html hexadecimal color code, only with a $ instead of # and red and blue switched).
Use24hrClock boolean 0 Display time using 24 hour clock instead of am/pm.
ViewerLeftMargin integer 3 Left margin (in pixels) for the viewer. Set to 0 if you want no margin, or a higher number if you want a bigger margin.
ViewerWordWrap boolean 0 Whether to wrap text in viewer by default.
XFace boolean 1 Displays the X-Face header as the intended 48x48 b/w graphic

For Date format, use these values:

d   Displays the day as a number without a leading zero (1-31).
dd  Displays the day as a number with a leading zero (01-31).
ddd Displays the day as an abbreviation (Sun-Sat or equivalent)
dddd    Displays the day as a full name (Sunday-Saturday or equiv.).
m   Displays the month as a number without a leading zero (1-12).
mm  Displays the month as a number with a leading zero (01-12).
mmm Displays the month as an abbreviation (Jan-Dec or equiv.).
mmmm    Displays the month as a full name (January-December or equiv.).
yy  Displays the year as a two-digit number (00-99).
yyyy    Displays the year as a four-digit number (0000-9999).
h   Displays the hour without a leading zero (0-23).
hh  Displays the hour with a leading zero (00-23).
n   Displays the minute without a leading zero (0-59).
nn  Displays the minute with a leading zero (00-59).
s   Displays the second without a leading zero (0-59).
ss  Displays the second with a leading zero (00-59).
am/pm   Uses the 12-hour clock and displays 'am' or 'pm'
a/p Uses the 12-hour clock and displays 'a' or 'p'
ampm    Uses the 12-hour clock and displays the local language's equivalent of am/pm.
/   Displays the date separator character (varies depending on locale).
:   Displays the time separator character (varies depending on locale).
'xx'    Characters in single or double quotes are displayed as-is.

[Misc] section:

Key Type Default Description
AltServers string   | separated list of alternate servers to try when a given article cannot be found on the current server for whatever reason. Can be set per group in groups.ini.
Archive string Archive Name of default folder to transfer articles into when you click on the "archive" button. Can be overidden in groups.ini.
AutoCollapse boolean 0 In article listing, whether to automatically collapse the previous thread when you expand another thread (does not apply when all threads are expanded).
AutoResume boolean 1 Whether to try to automatically resume a batch operation after being disconnected. If you are using dial-up, this works only if you set your dialer to autodial on network activity.
AutoResumeDelay {5..1800} 20 Number of seconds to wait before auto-resuming.
AutoSaveInterval {5..2000} 0 Automatically saves the newsrc the specified interval of minutes. The default zero disables autosave.
BackUpNewsRC boolean 1 Whether to create a backup file (.bak) when saving newsrc.
CatchUpButton {0,1,2,3} 0 Desginate what kind of catchup to assign to the catchup button (0=Catchup; 1=CatchUp and clear keep; 2=Catchup and kill xpost; 3=Catchup and purge)
CompactPercent {0..100} 30 Percent of wasted space that deleted messages can take up in a folder before Xnews should automatically compact the folder upon closing.
DecodeOpt {1,2} 2 when saving decoded file: 1 = overwrite existing file; 2 = save under different name.
DejaPage string http://groups.google.com/
advanced_group_search
URL to launch when you select Special|Goto Google News Search
DejaQuery string http://groups.google.com/
groups?as_umsgid=%m
URL to search the Google Usenet Search (formerly Deja) for an article given Message-ID %m
(If you don't want to be prompted to search Google for a missing article set this parameter with no content: "DejaQuery=" (yes, /nothing/ following the = sign))
ExpiredScoreOpt {0,1} 0 what to do with expired scores. 0=remove automatically; 1=notify user.
HardKill boolean 1 Whether hard kill should be on by default. (Hard kill means articles with score <= -9999 will not be shown at all).
LaunchAfterDecode boolean 0 Whether "Launch file" checkbox in save dialog should be checked by default.
MaxConnPerServer 1..4 4 Maximum number of simultaneous connections allowed to one server.
OnLoaded string   Comma separated list of commands to execute after headers are loaded or refreshed. If the list includes a ! (exclamation point), the first invocation will execute all commands up to the ! and subsequent invocations will execute the commands following the !
OnOpen string   Comma separated list of commands to execute when you first open an articles window.
OpenNextGroup boolean 0 Whether to automatically open the next group after you catchup the current group.
PromptDecodeDir boolean 1 Whether to prompt for a directory when you hit 'decode'. 0 means don't prompt; just use the default decode directory (see Setup|Files).
Queue string _Queue Name of default queue folder to transfer articles into when you select the "QArchive" command. Can be overidden in groups.ini.
QuoteChars string >:|]» List of characters you want Xnews to consider as quote characters. It works in conjunction with QuoteRegex, which determines whether a given line is a quote line.
QuoteRegex string ^\s?\s?\s?[>:|\]»] In viewer, lines matching this regex are treated as quoted text.
ReplyNotify {-1,0,1,2,...} 4 Xnews can flag followups of your posts. This setting lets you have more control over how deep into the thread Xnews should continue to flag followups. The idea is that discussion tends to diverge and you probably aren't interested after a while. 0=disable (don't flag at all); -1=flag all followups; 1=flag immediate followups; 2=flag immediate followups, plus followups to those; etc. Default is 4.
ScoreFileEditor string   Full path name to text editor to use when you select Special|Edit score file.
ScoreStoredHeaders boolean 0 Whether to score headers that are loaded from storage (as opposed to just scoring headers that are newly downloaded).
ThreadScoreOpt {0,1,2} 0 Determines how threads are scored. 0=highest score in thread; 1=highest score in thread, disregarding 0-scored articles; 2=sum of all scores in thread.
TZ integer system timezone Time zone offset from GMT in minutes*100/60. For ex, PST=-0800; Adelaide=+0950. Set this only if Xnews appears to be getting the wrong value from Windows.
UseSmartDecode boolean 1 Whether to attempt resuming interrupted multi-part decodes, starting from the last successfully decoded part rather than starting the whole file over.
XferTimeOut integer 30 Transfer time out in seconds.

In addition, the [Misc] section contains CopyHeadersTemplate, which lets you determine the format for the acaCopyHeaders command (copy selected headers to clipboard), using the following special codes:

%s  subject
%a  author's name
%e  author's email
%d  date, short format
%D  date, long format
%g  newsgroup name
%m  Message-ID
%R  References
%L  number of lines
%B  size in bytes
%int    where 0<int<256, ascii code
%t  tab (same as %9)
%r  CR (same as %13)
%n  LF (same as %10)
%%  the % sign itself

Everything else is treated as regular text. By default, CopyHeadersTemplate is set to %s%r%n (one subject per line).

[Compose] section:

Key Type Default Description
AlwaysXNoArchive boolean 0 Whether X-no-Archive is set by default
Autorewrap boolean 1 Whether quoted text should be automatically rewrapped.
FollowupPrompt {1..10} 3 Prompt to set followup when posting to more than this many groups.
GenerateDateHeader boolean 0 Whether Xnews should supply a Date: header. Note: the server may at its discretion drop the Date header and substitute its own.
KeepCopies boolean 1 Whether to keep copies of sent messages.
SetReplyToInPost boolean 0 Whether you want Xnews to automatically add a Reply-To header with your real (private) email address when posting to newsgroups. The idea is that spammers apparently only look at the XOVER data, which doesn't contain the Reply-To header, so it's safe to post your real email in Reply-To. This way, you can spam proof with a fake From: header but still allow people to email you without the hassle of having to correct your email.
WarnBadWrap boolean 1 Whether to warn that the article you are posting contains badly wrapped quoted text.
WarnExcessiveQuote {0..100} 60 ratio of quoted text to total allowed before you are warned that you have too much quoted text. Example: 60 means that if number of quoted lines exceeds 60% of number of total lines, Xnews will warn you. Set this to 0 if you do NOT want to be warned at all.

In addition, the [Compose] section contains MailAttrib, NewsAttrib, ForwAttrib which let you customize the attribution line when replying by mail, following up, or forwarding, respectively. These are just regular lines of text with the following special codes:

%a  author's name
%e  author's email
%f  the full From: header
%d  date, short format
%D  date, long format
%z  date and time, long format
%g  newsgroup name
%m  Message-ID
%r  CRLF
%%  the % sign itself

For example, if you set NewsAttrib to

%a <%e> wrote in %m thusly:

the followup attribution may look like

John Smith <jsmith@xyz.com> wrote in <72663.9374@news.xyz.com> thusly:

[PopUps] section:

Key Type Default Description
ArticleList string acaMarkAllRead,acaMarkAllUnread,acaSelectAll,- comma separated list of commands to add to the pop up menu of the article listing. See the keyboard mapping dialog for list of commands. Use a dash (-) to designate a separator line.
GroupList string acgSubs,acgUnSubs,acgPost,-,acgCatchUp,acgMsgCount,
acgAllMsgCount,acmSaveNewsRC,-
same as above, for the group listing.
Viewer string acaFollowup,acaMail,acaFollowupMail,acaSaveAs,- same as above, for the article viewer.


[XOVER] section:

Key Type Default Description
DefragGapSize integer 20 Get articles with a single XOVER unless there's a run of more than the specified number of consecutive read articles. (Read ones will be loaded and thrown out later).
May speed up the XOVER command by adapting it to your special needs: If you're on a slow connection or if your server limits your total download byte count, you want to set this value pretty low or disable the behavior altogether by setting DefragGapSize to zero. OTOH, if you're on a broadband connection and you're not concerned about byte count, you can set it to something higher, like 30. Don't set it too high because then you'll waste time downloading a lot of unnecessary headers. Experiment a bit to find the optimal value for you.
PromptThreshold integer 50000 Automatically pop up the XOVER dialog when you enter a group that have more than the specified amount of headers, so you have a chance to limit the number of headers to download. Set this to zero if you never want to be prompted.


[ToolBars] section:

Key Type Default Description
A1 string -,bShowAllHeaders,bFixedFont,bRaw,bWrap,-,
bAttach,bFollowUp,bMail,-,bBack,bForw,-,bRef,bNextQ,
bPrevTh,bNextTh,bPrevUnread,bNextUnread,bSkipQuote,-
Comma separated list of buttons to show on top toolbar in the articles window. The hyphen (-) is a button separator. Optionally, you can add a number after a hyphen to indicate how wide a space (in pixels) the separator should take up (Example: -25 instead of just -).
A2 string bCatchUp,bStop,bDecode,bRefresh,bArchive,bSend,
bEdit,bStorage,bPurge
same as above, for the bottom toolbar in the articles window
E1 string bEdit,bRewrap,bUndo,-,bSave,-,bSend,-,bStop for the main toolbar in the editor window

Set A1=
and A2=    to get rid of the toolbars altogether.


[UserButtons] section:

For extra fun, you can make your own buttons. In this section, define your buttons with

buttonname=command|iconfilename|hint

buttonname is whatever name you want to give it. Note: to avoid conflict with any button I may add in the future, DON'T name your button with a 'b' prefix.
command is just any Xnews command, a list of which you can get from the keyboard setup dialog. iconfilename points to a .bmp or .ico file to be used for the button. Use full file name and path.
hint is the popup help text for the button. Of the three, only hint is optional.

Example:

[ToolBars]
A1=bBack,bForw,-,bRaw,bFixedFont,-,u1,u2,-,bAttach,-,bSkipQuote
A2=bCatchUp,bStop,bDecode,bRefresh,bArchive,bSend,bEdit,bStorage,bPurge,u3

What are u1, u2, and u3? They're your own buttons, of course, which you define below. (You'll probably want to give a more descriptive name than u1, u2, etc, but you get the idea.)

[UserButtons]
u1=acvQuoted|d:\delphi\q.ico|Toggle quoted text
u2=acvFixWrap|d:\delphi\fixwrap.bmp
u3=acaFindMissingPartsEx|D:\delphi\findparts.ico|Click me, you won't be sorry

Hint: if a button's associated command doesn't apply to the current window, the button will not show up on the toolbar

Back to top


Group-based settings

The settings in xnews.ini (Name, Email, etc.) are essentially global settings. It's possible to override these settings for individual or group of groups. However, you need to manually edit the groups.ini file to do this.

The format of groups.ini is

[group-expression-1]
setting1=value1
setting2=value2
...

[group-expression-2]
setting1=value1
setting2=value2
...

where group-expression is a regular expression and any group whose name matches the expression will have those settings and values appied to it. Here's a simple example:

[binaries|mp3]
MultiPartThreading=1
FullScreen=1
ID=binuser

This says that in any group with binaries or mp3 in the name, you want to have multipart threading, full screen display, and use the ID 'binuser' ('binuser' is defined in IDs.ini).

If you precede group-expression with a ~ (tilde), then that section applies to any group whose name does NOT match that expression.

Setting in groups.ini override those in servers.ini, which in turn override those in xnews.ini. The following settings may be overridden in groups.ini:

Hint: open Xnews.ini and look at how these values are set. Read the comments.

For example, say you want to use the sig file mysig.txt most of the time; when in a comp group, you want to use worksig.txt, unless you are in a comp.lang.pascal.delphi.* group, in which case you want to use delphisig.txt.

In xnews.ini:

[ID]
Name=my name
; etc.
SigFile=mysig.txt

In groups.ini:

[comp.*delphi]
SigFile=delphisig.txt

[^comp]
SigFile=worksig.txt

Note that the program processes groups.ini in sequential order and stops once it finds a match. Also, there's no need to replicate the other settings such as name or email as they simply revert to the values set in Xnews.ini (unless of course you want to use a different name or email).

Often, you may want the program to continue on to the next section in groups.ini. To do this, add continue=1 to the current section. Take the example above. Suppose you want to use some set of email, name, etc. for all comp groups. In addition, you want to use a different sig file for delphi groups. This will do the trick:

[^comp]
SigFile=worksig.txt
Email=whatever
Name=whatever
; etc.
continue=1

[comp.*delphi]
SigFile=delphisig.txt
; inherit email, name, etc. from comp section

Note: the section name is indeed a regex. Because groups.ini is a windows ini file, you can't use [ ] in your regex. In this case, just use a dummy value then add a regex= line. For example, since you cannot write

[delphi[^a]]
...

(match delphi, but not philadelphia)

You have to write

[compdelphi]
regex=delphi[^a]
...

In addition, these settings are available only in groups.ini:

Group-based custom headers

You can define custom headers per group using the same format in Xnews.ini.

Example:

; applies to alt groups
[^alt\.]
CustomHeadersCount=3
CustomHeader1=X-No-Bananas: yes
CustomHeader2=X-Junk: blah blah
CustomHeader3=*Comments:

Note: custom headers are inherited from Xnews.ini and previous matching sections in groups.ini, with the current headers overriding previous headers. For example, if you have this in Xnews.ini:

[Compose]
CustomHeadersCount=2
CustomHeader1=X-No-Bananas: no
CustomHeader2=X-Test: abc

Then when you post to an alt group, you'll have these headers

X-No-Bananas: yes
X-Test: abc
X-Junk: blah blah
Comments:

Sometimes you want to clear out previously inherited headers (if any), in which case you need to add NewCustomHeaders=1 to the group's section. So if you have this

[somegroup]
NewCustomHeaders=1

then somegroup will have no custom headers since you cleared out all existing headers and did not define any new ones.

Hint: You can define duplicate custom headers (e.g., you can have several X-Face headers). When you compose your message, you can pick which of the duplicate headers to use.

Back to top


Plonk file

The plonk file is just a quick way to kill an annoying poster. It is not as powerful and flexible as the score file. You cannot use regular expressions, so the poster's name and email must match exactly (except for case). Also, it is global (you cannot filter by groups). On the other hand, it's simpler to use than the score file and is also more efficient.

Usage: when reading an article, press 'k' to add the poster to the plonk file. You'll be asked for an expiry period. By default, the expiry is set to 100, meaning after 100 days, the name will be automatically removed. The rationale is that it's usually pointless to have someone permanently in your plonk file. Either the bozo will go away by himself, or be driven off the newsgroup, or most likely, just change his name and/or email. So it's a good idea to specify an expiry period (remember, the more entries in the plonk file, the longer it takes the program to process it). If you really want the name to stay permanently, set expiry period to zero.

You can bring up the plonk file viewer with Ctrl+k. You can then add, remove, or edit entries. To delete, press the Del. To edit a name or email, right click on it.

Back to top


Score file

Xnews happily steals the scoring system concept from slrn. Basically, each article is assigned a score from -9999 to 9999. By default, an article has score 0 (no score, or neutral). Articles with score of -9999 or less are killed (you'll never see them, unless you turn off hard kill, in which case they show up with a red X icon). Articles with score of 9999 or more are considered "important" and flagged with a yellow ! icon. Read scoring.txt for all the hairy details.

Using Article|Add to score file

With version 2.02.20, I added a dialog box to facilitate adding entries to the score file. You can use it a couple of ways: a) let Xnews add the entry for you; or b) have Xnews generate the entry and copy the text to the clipboard.. You can then open the score file with your favorite text editor and paste it in, doing any additional editing you choose.

Regardless, you still need to know how the score file works, so read scoring.txt if you haven't done so. Also, you need to know what the relevant headers are. I suggest you open any usenet message, select View|Show all headers and examine the headers.

The Add to score file dialog should be more or less self-explanatory. First select a section to add the new score entry to. You can pick from an existing section (notice only those that are applicable to the current group are listed) or create a new section (by default, the new section applies solely to the current group; you can change the regex to broaden the scope).

Next, you choose whether to assign a score of 9999. -9999, or some other score. Then pick an expiration period

Now come the interesting part. Click on the push down button corresponding to the header you want to score from. Notice how the program has filled in the values from the current article. The text values are all regular expressions, which is why you see all the escape characters, e.g. jsmith@foo\.bar\.com. It also gives you a list of alternatives that may be useful to you (you can enter anything you want to, of course).

The references header deserves a bit of extra attention. You can select this article/top of thread/either, which corresponds to the message-id of the current article/the article at the top of the tread/either one (foo|bar). Or you can write a custom expression. The drop down list has two message-ids. The first is the message-id of the current article, the second of the top of thread. If the current article is the top of thread, there will only be one in the list.

Now select the boolean type (AND or OR). Click Apply to have Xnews add the entry for you, or Copy to clipboard if you want to edit the score file yourself.

Okay, let me give you a concrete example. Say you're reading an interesting thread and you want to "watch" it in the future. Bring up the add to score file dialog, select 9999 or specify some positive score, specify an expiry period (the thread won't last forever, and you probably won't care after a while). Select References / matches (actually, you could probably just as well use matches case). If you're interested in the entire thread, select top of thread or either. If you only care to followups to the current article, select this article.

As I said earlier, the References header occasionally gets broken, so as an additional safeguard, select Subject and boolean OR (if you use boolean AND, the score will no longer applies if someone changes the subject line, which may in fact be what you want).

Back to top


Regular expression

I've mentioned regular expression (abbrev. regex) throughout this doc. regex is used for the filters, folder search, and score file. You may wonder what regex syntax Xnews supports.

Xnews uses Philip Hazel's PCRE (Perl Compatible Regular Expression) package, adapted for Delphi by yours truly. What this means is that you have access to a very powerful regex engine, and if you're already familiar with Perl, all the better. PCRE supports most constructs in perl regex.

Here's a good introductory tutorial on perl regex:

http://virtual.park.uga.edu/humcomp/perl/regex2a.html

I strongly suggest you read it

I've added a feature to let you try out Xnews' regex engine and see how it works. Select Special | Test Regex.

For the full discussion on PCRE and differences between PCRE and perl regex, read pcre.html. This doc is aimed at programmers and will probably give you a headache. (It does me.) So here's a crib sheet, which may suffice:

1) Letters, numbers, and non-special characters just match themselves.

Example:

    color
        match anything with the word color in it

2) Special characters

   \    treat next character literally, i.e., as itself and not a special
        character.
   .    match any character
   ^    match begin of string
   $    match end of string
   |    alternative
   (..)  grouping
   [..]  match one of the characters in the set
   [^..] does NOT match one of the characters in the set.

(the .. are ellipses, not two literal periods.)

Example

    help\.
        matches help followed by a period
    ca.s
        matches "cats" "cars"
    ^test
        matches "testing", "tester", but not "the test"
    me$
        matches "see me" but not "meter" or "me and you"
    cat|mouse
        matches "cat" "mouse"
    dog(s|gie)
        matches "dogs" "doggie"
    [aeiou]
        matches a vowel
    [a-z0-9]
        matches a letter or digit.  Note how the - is used to specify a range.
        if you want to specify a dash as part of the set, put it at the 
        beginning or end, e.g. [a-f0-9-] matches a-f, 0-9, or dash.

Note: when I say help\. matches help followed by a period, what I really means is that the regex will successfully match with a string that contains help followed by a period. Thus please help. now will also match, although of course the matching part is only help. On the other hand, the regex ^help\.$ will only match the string help. since the ^ and $ must match the start and end of string.

3) Quantifiers (match how many times)

   *     Match 0 or more times
   +     Match 1 or more times
   ?     Match 1 or 0 time (i.e., optionally match)
   {n}   Match exactly n times
   {n,}  Match at least n times
   {n,m} Match at least n but not more than m times

Example

    ma+
        matches "ma" "maaa" "maaaaaaa"
    ma*
        matches "m" "maaa"
    (yada ){2,}
        matches "yada yada yada "
    foo(and)?bar
        matches "fooandbar" or "foobar" (the "and" is optional).

4) Shorthand for character set

   \w     Match a "word" character, letters, numbers, and "_"
   \W     Match a non-word character, opposite of \w
   \s     Match a white space character (space, tab, cr, lf)
   \S     Match a non-whitespace character, opposite of \s
   \d     Match a digit character
   \D     Match a non-digit character

Example

    \(\d\d\d\)\s*\d\d\d[- ]?\d\d\d\d
        match a U.S. phone number
        that is, 3 digits enclosed in literal parenthesis
        then zero or more spaces
        then 3 digits prefix
        then either a dash or a space or nothing at all
        then 4 digits.

5) Zero width assertion

A fancy way of saying a true condition that doesn't actually match or consume a character.

    \b   Match a word boundary
    \B   Match a non-(word boundary)

Example

    \bfoot
thematch "footer" "footing" "a foot" but not "afoot"
    foot\b
        match "afoot" and "foot." (period doesn't count as part of word)
        but not "footing"
    \bfoot\b
        match the whole word foot
    foot\B
        match "footer" but not "foot;"  i.e., there's got to be something
        after foot that is part of a word

6) Back references

If your regex contains one or more subexpression (..) you can refer to the <digit>th subexpression with \<digit>

Example

    (\b\w+\b) to \1
        match "man to man" "hand to hand" "100 to 10000"
        the \b\w+\b matches a whole word.  The ( ) saves the word
        in subexpression #1 (it's the first sub expression in the regex).
        The \1 refers back to it.  
        "man to child" would not match since child does not match man.
        Note: Xnews allows up to 19 sub expression in a regex.

7) Look ahead/behind

   (?=regexp) lookahead assertion.
   (?!regexp) negative lookahead assertion. 
   (?<=regexp) look behind assertion
   (?<!regexp) negative look behind assertion

Example

    \w+(?=\t)
        match a word followed by a tab; the tab isn't included in the match

    foo(?!bar)
        match any occurrence of "foo" that isn't followed by "bar"
   
    (?<!foo)bar
       match an occurrence of "bar" that is not preceded by foo

8) Case sensitivity

In Xnews, the filter regex is always case insensitive. In the score file, you can make regex case sensitive by specifying Keyword= expression rather than Keyword: expression. In the folder search dialog, you can toggle case sensitivity by checking the "Match case" box.

Back to top


Acknowledgements

I wish to credit and thank the authors of the following free components / code / resource I used in making Xnews.

  1. TAdvSplitter by Charles Bedard and TBufStream by Lucian Radulescu. Both components can be found at the Delphi Super Page.
  2. TAgOpenDialog by Deepak Shenoy (Agni Software).
  3. X-Face Delphi code by Matthijs Laan http://www.geocities.com/quazar_nl/winface/. Matthijs also has a program you can use to convert bmp files to X-Face.
  4. Philip Hazel's Perl-Compatible Regular Expression package.
  5. Text wrapping code from the gknsa library by John Moreno, et al.
  6. Free icons from windows95.com (various authors).
  7. I also ripped off the binaries icon and some fine ideas from NewsXpress. Hope Ken Ng doesn't mind :-)

I also wish to thank all users (read:testers) who've submitted bugs and suggestions. In particular, I thank Richard Merit for his extensive alpha testing, feedback, and from time to time, help with the Win32 API; John Moreno for pointing out various RFC and GKNSA violations; and Adam Bailey for doing the GKNSA eval.

That said, I'm solely responsible for all the bugs and shortcomings in Xnews, except where they can be blamed on Bill Gates and Co., of course :)

Back to top


Copyright © Luu Tran 1998-2002. All rights reserved.
http://xnews.newsguy.com

Last Updated: Apr 24, 2002.