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.3dnews.net

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...
   • retrieve the last n headers from a newsgroup.
   • decode/save/transfer several articles at once
   • decode multipart binaries
   • cancel a message
   • use XPAT search
   • add custom headers to postings
   • use ROT-13 (and what the heck does it do?)
   • hide a column in the list
   • save an attachment
   • post attachments / binaries
   • cut/copy/paste text (there's no Edit menu)
   • cross post to several groups
5. Hidden keyboard shortcuts / Keyboard tips
6. Troubleshooting / FAQs
7. What is _____
   • mark keep/unkeep
   • mark high score/0 score
   • catchup, etc.
   • Reformat (in editor window)
   • the meaning of different icons in the article listing
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:

• You can select multiple items in the group and article listing the same way you do in Windows Explorer, with Ctrl and Shift.
• While the All tab is selected, enter a filter string in the edit box at the bottom to see only groups whose name contain that string. Mark the checkbox to the left of the edit box if you want to match at the start of string rather than anywhere in the string. You can do the same in the articles window, except there, the filter string is assumed to be a regular expression.
• You can resize the columns in both groups and articles windows. Drag and drop the column header to reorder the columns,

The articles window:

• The article listing and viewer share the same window (unlike in NewsXpress). You can switch between full / split view by hitting F12. When in full view, hit return to move back and forth between the viewer and list. You can do the same by selecting View | Switch List <-> Viewer or by clicking on the second panel at the bottom.
• When you're in split view, single click on the subject to read the article. (Click on any other column to avoid opening the article.) When you're in full view, you need to double click. In either case, pressing Return will do the same.
• When the focus (cursor) is in the list, if you click Goto next(/prev/...), it will move to the next(/prev/etc) article relative to where the selection bar (cursor) is. If the cursor is in the viewer, it will move to the next(/prev/etc) article relative to the article you're reading, regardless of where the selection bar in the list may be. That makes sense, I hope. To move the selection bar to the article you're reading, press 'c' or click on the progress bar (gauge) at the bottom.
• In order to reply/followup/forward a message, you must first open (read) it. Furthermore, the focus (cursor) has to be in the viewer.

General:

• You can customize the keyboard (Alt+K). This is also a good way to look at the list of current shortcuts, not all of which are visible on the menus.
• There is no connect/disconnect button. The program just connects when it needs to and disconnects when you close the server or shut down the program. Try to avoid opening too many simultaneous connections since this puts a strain on the news server and slows down your own connections to boot. (If the program is busy doing something and you open another group or read an article or update message count, etc., it will have to open another connection.) Per GNKSA requirement, Xnews limits you to 4 simultaneous connections to the same news server. Be advised, however, that some servers may set an even lower limit, such as 2 or 3.
• Xnews supports multiple servers. You can even open several servers at once, in the same window. Note: avoid running multiple copies of Xnews simultaneously. Not only does this waste memory, it can lead to newsrc and folder conflict and cause all sorts of weirdness.
• You can define multiple identities with different names, email, and sig (signature) file via the Setup dialog. When posting an article, you can then select which identity to use. You can also specify which identity to use with certain servers/newsgroups (read on).
• You can customize certain settings for individual server. For example, in server A, you can use identity X; in server B, you can use identity Y. It should be obvious in the Setup dialog how this is done.
• Similarly, you can customize certain settings for individual group or groups. You may have noticed that when you are in a group with "binaries" in the name, the display looks a bit different. For example, all the threads are not automatically expanded. This is the result of certain settings in groups.ini. Unfortunately, you do have to edit the groups.ini file for group-based customizations. See the section titled "Group-based settings".
• Xnews stores most settings in ini files which you can edit directly. The main ones are:

  xnews.ini - global settings
  servers.ini - server info and per-server custom settings.
  groups.ini - per-group custom settings
  
  You really only need to edit groups.ini manually. Use the setup dialog for the others.

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:

In article viewer:

In groups window:

In groups window, article listing and viewer

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

In article listing and viewer

A few words on remapping the keyboard.

• You have to be in the groups window or articles window to change their respective shortcuts. Since these two windows are never active at the same time, it's okay to assign the same key to two functions not in the same window. for example, you can assign Ctrl+P to "Post" in the groups window and "Print" in the articles window.
• Don't assign an unshifted letter key [0..9,a-z] in the groups window, as this will interfere with the feature that lets you jump to a line in the list by typing the first few letter.
• The program is pretty liberal about letting you assign any key you want to any function, but be careful about assigning keys that have certain functions in normal Windows programs such as the cursor keys or Ctrl+F6 (switch to next window). Feel free to experiment, though.
• You can't assign to the Del key; the Windows hotkey control won't let you. If you really want to do this, edit the keys.ini file manually.

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):

• Catchup: this does what's described above.
• Catchup and clear keep: this does the above and removes any kept articles as well. Keeping articles is an Xnews feature described above.
• Catchup and Kill XPost: this is equivalent to issuing a mark all as read command then closing window. Mark all as read is NOT the same as catchup since catchup only sets the read count (i.e., it sort of fakes it) whereas Mark all as read go through each article and mark it read, as if you have actually read it. This does 2 things: 1) Mark as read will perform crosspost killing in subscribed groups. That is, if the same article was crossposted to another group you subscribe to, then it'll be mark as read there too. and 2) If you have storage on, the next time you retrieve headers, the old articles will show up as read. This last option is slower than the first two. How much slower depends on the amount of crosspost and number of articles.
• Catchup and Purge: same as above but also deletes all headers and article bodies if you have storage on.

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:

• Pay attention to the pop up hints.
• In groups window, you can right click on the read column to edit. To retrieve a specified number of headers, press Ctrl+Enter instead of Enter to open a newsgroup.
• If you want to select an article without opening it, click on any column OTHER than the subject column.
• Use the filter box at the bottom (I'll call this the B filter for convenience). For example, type in news.*ex|nx and press Enter to see only articles about NX in news.software.readers. You can even type in a filter while it's retrieving headers.
• In the article viewer, double click on a URL or article reference to launch the URL or load the reference. (Or place the caret on the URL and press Ctrl+Enter.)
• Sometimes, you just want to jump to the next/prev read/unread/hi score/etc article without actually reading it (for example: it may be a huge binary you don't want to open). To do this, turn ON Scroll Lock. To return to normal operation, turn off Scroll Lock.
• If you hold down the Ctrl key while opening an article, the program will just retrieve the headers. This is useful when you want to see only the headers of a very long article, or if you want to post a followup to an article without retrieving the whole body.
• You can drag newsgroup names from the newsgroups window and drop them onto the Newsgroups or Followup-To fields in the message editor.
• If you hold down the shift key while clicking on a server (Server menu), you'll be placed in the Setup dialog to edit properties of that server.
• In split screen, you can scroll the list even when the cursor is in the viewer this way: turn on Num Lock and use the arrows, home / end, pgup / pgdn as usual. Use the Num 5 key to open the selected article. The Num 4 and 6 keys open prev / next article.
• You can set up xnews for multiple users by specifying a different start up directory with the command line switch /d:start-up-dir. (Note: you cannot have any space between the switch and the directory name.) For example,

  c:\bin\xnews.exe /d:c:\user\mary
  

  mary can then have her own .ini files, score file, etc.

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

• Hide incomplete binaries: hide binaries with missing parts.
• Show binaries only: only show single-part of complete multipart binaries.
• Show queued articles only: show only articles that are currently in the queue. Note: previously queued articles that have been processed will not be shown.
• Show cached articles only: show only articles whose bodies have been cached, i.e., they are available on your hard disk and don't have to be fetched from the server.
• Show new headers only: This is only meaningful with storage turned on. When you're storing headers, you will have a lot of headers and it may be hard to tell which are new. This filter will show you only headers that are new since the last session, or more precisely, since last time you opened the newsgroup.
• Show unread articles only: obvious.
• Show threads with (new headers/queued articles/unread): this is similar to the above filters, except that the filter is done at the thread level rather than on individual articles. To elaborate: when you select "Show unread articles only", Xnews removes all read articles from the current list then threads the result. With "Show threads with unread", it threads the current list (if it's not already threaded) and eliminates all threads that do not have at least one unread article in them. (Articles not part of a thread are considered threads unto themselves.) The advantage of filtering at the thread level is you get to see the articles in their context.

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:

• >=9999: show only "important" articles
• >0: show positive scores
• >=0: show non-negative scores.
• >-9999: show only those not killed (negative allowed)
• Clear: remove filter.

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:

• You can only drag and drop 1 item at a time.
• The item being moved is always inserted after the target item. If you want to insert in front instead of after, hold down the shift key as you drop the item.
• Sorry, you can't drop a category inside another category.
• If you drop a group on a category, it always goes into the category. If you want to put the group in front of the category instead, hold down the shift key as you drop the group. If you want to insert a group after the category, do the same thing then move the category up.

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:

• You can override the default folder on per-group (edit groups.ini) or per-server (Setup | Servers) basis.

• If you want the program to transfer articles into a folder of the same name, open xnews.ini and under [Misc] change

  Archive=xxx

  to

  Archive=*

  (That's an asterisk). Ditto in servers.ini and groups.ini.

• You can share folders with NewsXpress and Eudora. Open the folders window, add a folder, then select Folder|Change File and find the NewsXpress or Eudora folder file you wish to use. Note: because Xnews keeps an index file (with the extension .hdr), if what's in the .hdr file does not match what's in the folder (.mbx) file, Xnews will give you a warning saying that the index has to be rebuilt. This is normal.

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

• If something looks too confusing, just leave it alone.
• boolean type should be either 0 (no) or 1 (yes)
• integer type is any whole number (may be negative)
• color type is similar to html color values; it should be a hex triple of the form $bbggrr. Example: $FF000 is bright blue; $00FFFF is bright yellow.
• some keys have a set of allowable values, e.g. {0,1,2} or {0..100}
• string type is just letters and/or numbers. Do NOT put quotes around strings.
• Keys are not case sensitive.

[Display] section:

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:

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:

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:

[XOVER] section:

[ToolBars] section:

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

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:

• Name
• Email
• PublicEMail
• IDToken
• Organization
• SigFile
• MultipartThreading
• SortOn
• SortOrder
• ColumnLayout
• ExpandAllThreads
• FullScreen
• AttachDir
• DecodeDir
• Archive
• Queue
• NewsAttrib
• MailAttrib
• ForwAttrib
• OnOpen
• OnLoaded
• AltServers

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:

• PostTo: specifies which server to post to by default (you can change this on the fly by selecting from the Post > drop down list). For example, say you want to post to the "anonnews" server when reading a rec.* group.
  

    [^rec\.]
    PostTo=anonnews
    

• OverrideTo: specifies which server to override to by default. This is useful if you like to download headers from one server but get articles from another (for example).

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.

• From: this is obviously the identity of the poster. Typically, it looks like John Smith <jsmith@abc.com> or jsmith@abc.com (John Smith)
• Subject: no explanation needed.
• Message-ID: every usenet is assigned a unique message ID, either by the newsreader or the server. A message ID looks sort of like an email address, except the name part is a bunch of (seemingly) random letters/numbers, like so <736jdh658@news.abc.com>. The < and > are part of the message ID.
  Scoring by message-id is usually not very useful, except possibly to filter out post from a certain domain (in lieu of being able to score on NNTP-Posting-Host).
• References: a list of message IDs, separated by space, of parent messages. The first one in the list is (usually) the ID of the top article in the thread, while the last one is (usually) the ID of the immediate parent, i.e., the one the current article is a followup to. I say usually because the References header often get broken up or truncated, especially in long threads.
  Scoring on References is a good way to kill or select a thread. If you specify the message-id of the top article in a thread, you (usually) will catch all articles in that thread.
• Xref: not every server includes this header in the news overview database. In any event, it's a list of newsgroups the article is posted to, plus the respective index numbers of the article in those groups. Here's an example:
  mindspring borland.public.delphi.ide:17726 borland.public.delphi.misc:18720
  This shows the two groups the article was posted to. You don't really care about the numbers (Xnews uses them for crosspost killing). Xnews strips the server alias (mindspring in the example) from the Xref header to save a little bit of space, so keep this in mind when you score by Xref.
  Typically, you use Xref for scoring one of two ways: 1) score articles crossposted to certain groups, e.g., kill articles crossposted to an advocacy group to avoid the religious wars; or 2) count the number of groups crossposted to by counting the colons (:). The latter isn't as useful to you since Xnews has built-in support for killing article xposted to more than X number of groups.

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.3dnews.net

Last Updated: January 2, 2002.