README file for NJN (v0.02i) - last updated on September 21, 2005 (See HISTORY.TXT for the latest program news/features/info. This README.TXT will not necessary be updated with every program build.) OVERVIEW: NJN (the Nehelenia Java newsreader) is Usenet news reader. It is still in the early stages of development. NJN is loosely modelled after the superb OS/2 newsreader, ProNews/2. I'm aiming for a somewhat simpler application which nonetheless contains most of ProNews's best (in my mind) features. These include fully-separated newsgroup windows (which sets NJN apart from that ubiquitous 3-pane layout, which I despise), support for multiple connections on multiple servers, and a simple and intuitive user interface. My other purposes in writing this program are: 1. To gain experience writing a full-scale application. 2. To experiment with networking protocols, and Java, and to see how well they relate to each other. 3. To end up with a newsreader which I can use, comfortably, no matter what OS I'm booted into at the moment. 4. To fill what I believe is a serious gap in the newsreader market (outside OS/2, at least) - a high-quality, multi-threaded, multi-window newsreader. 5. To have fun. I like networking, I like Java, I like Usenet, and I like user interface design. So it seemed like a good fit. What's working so far: At the moment, you can connect to news servers, download a list of newsgroups, open a newsgroup and download a list of articles, and read individual articles. You can subscribe to groups in the GUI, but this won't be remembered the next time you start NJN. However, if you edit the newsrc file(s) by hand, you can permanently subscribe groups that way, if you know the file format (the file is in standard UNIX newsrc format). You can also set a number of preferences by hand-editing the configuration file njn.cfg - see below for a brief description. As yet, there is no working configuration interface in the application. For the moment, I am still limiting NJN to a single active connection on a single news server. Authentication is not supported. There is no support for saving articles, or decoding binary attachments. You cannot post messages. There is no internationization support, and you cannot (yet) display non-Latin text. Messages in the article list cannot be sorted. And so on. In short, this is definitely not an end-user release! Consider it a developer-only version, although I'm not really ready to accept contributions from other developers. Still, you can play with it, or fork it and start writing extensions of your own. Or just check it out if you're curious... Most of the code is commented, and shouldn't be too hard to follow. I try to keep it neat and organized. See the file HISTORY.TXT for a summary of changes since the last release. RUNNING: I believe NJN will function under Java 1.1 and Swing 1.0, but those are the minimum requirements. I'm currently developing and testing using Java 1.4.1 under OS/2. NOTE: For some reason which I haven't yet pinned down, the program seems to hang under IBM's Java 1.3.1 runtime for OS/2. I suggest using either Java 1.1.8 or Java 1.4.1 and up. Using Java 1.2 or later, you can run NJN with the command: java -jar njn.jar Under Java 1.1, which doesn't support the -jar parameter, you will need to use the -classpath parameter to add the jar file to the classpath, and then invoke the class 'njn.Nehelenia'. For instance, on my OS/2 system the following generally works: java -classpath c:\java11\lib\classes.zip;c:\java11\swing\swingall.jar;njn.jar njn.Nehelenia or even just java -classpath %CLASSPATH%;njn.jar njn.Nehelenia but under OS/2 this only works from the command-line, not from a program object. Under Java 2 you can substitute 'javaw' as the name of the java executable if you don't want a console window popping up. (Under Java 1.1 for OS/2, you can use 'javapm' the same way.) USING: Hopefully, the interface is fairly straightforward. The first thing you probably want to do is connect to your news server using the 'connect' button (or menu item), and then download a list of available newsgroups (use the last item under the 'Group' menu). Initially, no groups will show under the 'subscribed' tab. You can change to the 'all groups' tab to see all available newsgroups. To open a newsgroup, highlight the group you want to open, and then select the 'open newsgroup' button (or menu item). The newsgroup window will open. (Double-clicking on a list entry has no effect at the moment, since I haven't written a suitable ListSelectionModel yet. So you have to use the button or menu item for now. Sorry.) The newsgroup window is initially empty. If you're connected, you can now download a list of articles in the group using the button in the middle of the toolbar. Once you have a list of articles, you can read one by selecting it, and then selecting the 'get' button on the left end of the toolbar. (Again, double- clicking on a list entry won't do anything yet.) And that's pretty much it, for now. COMPILING: To compile, extract the source zipfile into the 'njn' directory, which must lie off a directory in your CLASSPATH. For example, if your CLASSPATH variable is 'C:\JAVA11\LIB\CLASSES.ZIP;D:\PROGRAM\JAVA', then 'njn' can be located under D:\PROGRAM\JAVA. (If you don't have a classpath variable, set one.) If you'd rather not mess with your environment variables, you can set the classpath variable at runtime for both 'javac' and 'java', using the '-classpath' or '-cp' switch. See your Java documentation for details. You can also use this method to run Nehelenia if you just have the raw .class files (and not the JAR). In that case, 'java njn.Nehelenia' should run the program. The javac program handles dependencies automatically, so there's no Makefile. Just 'javac Nehelenia.java', and the application should build properly. Obviously, you do need a Java compiler for this. CONFIGURATION FILE The configuration file is in Java 'properties' format. It should be called 'njn.cfg' and located in NJN's working directory. A sample file is included. The currently-defined variables are listed below. Note that several of these don't actually do anything as of yet. Colours.Main Background colour of most windows. Colours.Text Background colour of text components. Colours.Button Background colour of button controls. Fonts.Main Font used for miscellaneous window text. Fonts.Menu Font used in the menus. Fonts.List Font used in list and table controls. Fonts.Controls Font used on buttons and other control-type widgets. Fonts.Subject Font used to display the subject heading on the message reader window. Fonts.Info Font used in the status display at the bottom. Fonts.Article Font used to display news article text. Fonts.Posting Not yet implemented. Window.Main Size/position coordinates of the main window (in the format x y w h). Window.Group Size/position coordinates of group windows (in the format x y w h). Window.Compose Not yet implemented. Personal.Name Your name (to appear on messages). Not yet implemented. Personal.Email Your email address (to appear on messages). Not yet implemented. Personal.Signature Your signature (a filename). Not yet implemented. Network.StartOnline Not yet implemented. Network.RefreshOnConnect Not yet implemented. Network.Smtp Not yet implemented. Network.Nntp News server definition(s). Any number of servers may be defined, separated by semicolons, in the format: hostname,ip_port,newsrc_filename,title Misc.ListRowMargin Amount of vertical padding (in pixels) between entries in the newsgroup and article list. Misc.ArticleListRows Number of rows of the article list to display by default above the splitpane divider in group windows. Misc.ShowGroups Not yet implemented. Misc.TabPosition Not yet implemented. REMARKS Wondering about where the name 'Nehelenia' comes from? Keep on wondering. :) Seriously, I tend to choose semi-random codenames for my software projects for use during development. In this case, I liked it enough to adopt it into the 'official' name, at least for now. Nehelenia was a Scandinavian underworld goddess who also found her way into Norse mythology, where she was more commonly called 'Hela'. Ancient mythology is a hobby of mine... AUTHOR: Alex Taylor - alextaylor41[at]rogers[dot]com http://www.cs-club.org/~alex The current release of NJN should be at http://www.cs-club.org/~alex/programming/njn NJN is free software, licensed under the GNU General Public License. Refer to the file 'LICENSE', or the Nehelenia.java source code, for more details.