This is a documentation. I am a programmer. You are a user. There are two facts about documentations, users and programmers:
In fact, I study computer science so this will only make the situation even worse. And as I know from my work at a support hotline: Users don´t read documentations at all.
These observations are the reason why I don´t maintain this documentation with great effort. I included all new information neccessary to use Yanoff but some of the images are old or missing. I hope you will find the corresponding forms in Yanoff without any problems, though.
Yanoff is a free UseNet newsreader project. It is released under the terms of the GNU public license that comes along with this documentation. That means that you receive the source code of the application with the application itself.
Let´s begin with a warning: Only devices bigger than and including a PalmIII are supported at this time. If you want to change this, see project.
First of all, Yanoff is both an online and an offline newsreader. It supports NNTP to receive and send network news articles.
Yanoff supports crosspostings and stores the message IDs of received articles to keep track what data is useful to download and what not (an article that is or was already in Yanoff´s database is considered to be not useful...).
Yanoff supports the download of article headers, bodies and complete articles. Dependent on where the download command is issued (inside a newsgroup or in the newsgroup list) either the current newsgroup´s articles or all newsgroups´ articles are downloaded.
Yanoff memorizes the number of the last article received in a newsgroup. This way additional traffic is avoided because only articles are requested that have not yet been in Yanoff´s database.
No special installation procedure is required for Yanoff. Simply follow the instructions of the Palm Pilot manual or try "man pilot-xfer" on Linux workstations.
After the start Yanoff shows the list of active newsgroups.
When first starting Yanoff, the list is empty except for an internal group used to store outgoing articles. In the menu line Yanoff shows a rough estimation of the amount of free memory. The estimation is a bit optimistic and I´ll work on that issue in the near future.
New newsgroups can be added by "Subscribe" in the menu "Management". They are listed in a row along with the number of articles that are in the respective group. You can change the layout slightly: By tapping in the title row next to the left side of the word "Newsgroup" and drawin the stylus you can draw the column separation around. If you move the Newsgroup column to the left border of the screen the number of articles in each group is no longer shown and the redraw is a little bit faster.
When some newsgroups are created it is time to adjust the preferences. Since version 1.1 there are three preferences forms. One for the server preferences, one for the posting preferences and one for miscellaneous things. If you tap on "Server Prefs" in the "Prefs" menu, the following form will pop up.
To get UseNet news you have to have access to a news server. This is a computer that stores articles for other people. The address of the server has to be entered in the field "Newsserver". The field "Port" denotes the TCP/IP-Port of the news server. This is usually 119 but may be a different one on your server so if you fail to connect on port 119 you can change it to the one needed. Your administrator will be able to tell you the right port number. You should not change the default value unless you encounter problems when establishing the connection.
Yanoff is a networking program and networks are cool but not without faults. Sometimes it happens that an expected result is not achieved. Say, Yanoff issued a command to the server and waits for the answer. Unfortunately somebody stumbled over the network cable that connects the server to the internet. Or the news server program dies. Yanoff would wait very long for the answer to come. To prevent this, you can enter a timeout value in "Timeout".
Since version 1.02 Yanoff supports authenticating news servers. These are servers that can be accessed by the internet but only if you have to have an account on them. To use these servers Yanoff has to log into them by entering a username and a password. These pieces of information can be entered in the fields in the lower half of the Server Prefs form. To use authentication you have to check "Use Auth".
When everything is fine, you can leave the form with "OK" and save the changes made or with "Cancel" and forget what you´ve done.
There is another Prefs menu: Misc Prefs.
Yanoff stores the Message IDs of all articles it received in a separate database. A Message ID is a string that identifies a usenet article worldwide. There are by definition no two articles with the same ID unless a software malfunctions. Whenever Yanoff is about to download an article it first gets its MsgID and looks it up the its own Message ID database. If Yanoff doesn´t find the ID, the article has probably never been in Yanoffs database and it will download the header and, depending on the command the user issued, the body. Suppose you are polling several newsgroups (that means, you are retrieving articles from them) and a guy posted a 70 KB FAQ in two different groups but the articles arrived with a delay and you have already downloaded it from the first newsgroup it arrived in. Now without the MsgID database the same article (that may be extremly boring) would be transferred a second time. But with the MsgID mechanism Yanoff recognizes that the article has already been on the device and does not download it. (Unfortunately Yanoff can not recognize if an article is boring...) The only disadvantage with this method is, that all MsgIDs have to be stored in a separate database. This costs about 50 byte per downloaded article. After a few weeks the database would get very large. So Yanoff can delete old MsgIDs of articles that are not expected to arrive anymore. You should try several values but 5 days should be enough. So this is the default value. You have to push the "Purge" button next to the field "ID Purge" to get rid of old MsgIDs.
All articles are stored locally on the Pilot and reside there until they are deleted. There are several methods to delete articles. One of them is to delete all articles that are older than a certain amount of days. This amount of days is what you can enter in the field "Art Purge".
Whenever Yanoff downloads new articles in a newly subscribed group it will download only the last few articles. Some newsgroups have a very high throughput of articles and who knows how many articles are in your new newsgroup and would have to be downloaded? The exact number of articles downloaded in this case is entered in "Sample arts".
Palm Pilots are very cool but they lack one thing very much: memory. I am the lucky owner of an upgraded Professional and have 2 MB but this is not much, either. Unfortunately again, some people have plenty of time and generate very large articles that would not fit into the memory of a Pilot or prevent other articles from getting saved. To prevent this, Yanoff stores only the first couple of KBytes of an article on the Pilot. Yanoff can store articles to a size of about 60 KB but there will be currently unhandled problems with articles that are as large as these. So currently the absolute maximum of an article to be stored is 31 KB. Simply enter a value in "Article max" to set the maximum size of an article in memory (including header data).
A third preferences form can be used to configure the posting facility of Yanoff.
The From field of your postings is made of the username and the hostname you entered in the respective fields. That is, if you want to use the return address "john_doe@somewhere.com" you should enter "john_doe" in the field "Username" and "somewhere.com" in the field "Hostname". Your Realname will be appended to the From field of your article as comment:
From: john_doe@somewhere.com (John B. Doe)
Zone should be set to something like "GMT+/-n" where "n" is the number of hours your timezone differs from Greenwich Mean Time.
In the field "Signature" you can enter a text that will be appended to every new article you write. You can include a greeting like "Bye - John Doe" or just begin with some quote. The signature itself (that means everything after the "Bye") should not exceed four lines. This is a UseNet rule. I don´t know of any other reason that would make sense, but some of the more fanatic UseNetizens will simply PLONK you of start flame wars if your signature is too long. Oh. And there is another thing about the signature. It should be separated from the rest of the article with a line that only contains two dashes and a space ("-- "). Some newsreaders will skip the rest after this line and save HUGE amounts of space. This is the other thing fanatic righteous UseNetizens will not tolerate if it is violated. (I hope they won´t hang me for the header lines Yanoff generates...)
No field´s data will be checked for correctness. If the fields contain invalid data the newsserver will reject the article and an error message is displayed after the attempt to post the article. The best thing is: enter a valid string (haha) and try it with a test article in a test newsgroup.
Before we start downloading articles in online mode we should establish a connection. There are exactly to connections involved in this game: The connection between the Pilot and the PPP server and the connection between Yanoff and the news server. By issuing the command "Go online" Yanoff builds up the latter one. In the case that the PPP connection is not up yet, Yanoff will bring it up. The Pilot will show the network dialog. It may be (see above) that something will go wrong. In this case simply repeat the command. If this doesn´t help, select "Go offline" in the same menu and "Go online" again.
If you have already built up a connection with another application (the network panel for example), you have to "Go online", too, because Yanoff has to connect to the news server.
The command "Go offline" completely teminates the connection both on protocol layer (the connection to the news server) and on hardware layer (modem connection to ISP). If you leave Yanoff to another app it will close the Netlibrary and set a timeout. Within the timeout you can start another app and use the same PPP link Yanoff used. If you don´t do that and the timeout ends, the Netlib will close the modem connection.
After we have finished the setup and went online we can now try to download some articles from the net.
To download new articles from all newsgroups, stay in the newsgroups list and select one of the "Get" commands from the Menu "Comm". The "Get" commands come in three flavours:
If no network connection is established when selecting one of the above commands, Yanoff establishes a connection, executes the command and terminates the connection again.
Sometimes it happens that Yanoff has an active connection, transfers some articles and then the autooff strikes again. When the Palm Pilot switches itself off, the active network connection is terminated. Unfortunately, Yanoff doesn´t notice this and tries to do some stuff with a network currently not open. The best thing to do (after you recovered from the error messages) is: "Go offline" - "Go online".
This image shows how Yanoff displays the download progress. There are some characters printed behind the article numbers. An "h" means that a header was received. If there is a dash ("-") instead of the "h" the header was skipped because the article has already been on our device.
A "b" means, that a body was received. A dash instead of the "b" means, no body was downloaded because the appropriate article already had a body.
You can abort the download of articles by tapping on the "Abort" button.
Just tap on the newsgroup to enter. You can leave the newsgroup view (and the article view) to the next higher level by entering a backspace - a stroke to the left on the graffiti area. Alternatively you can use the icon in the upper left corner that shows an arrow pointing upwards.
Also in the newsgroups list you can change the layout a little bit. Tap in the title row next to the left side of the word "Subject" to drag the subject column to either direction. If you drag it completely to the left only the subject line is shown.
 List with From: and Subject: |
 Only subjects are listed |
These images show article lists of a newsgroup. In the first column of the table there are some flags shown:
The second column contains the name of the poster and the third column the subject of the article.
You can change the width of the two columns. Tap in the line between form title and the first table entry near the gap between the columns. A vertical line that marks the column separation will appear if you hit the place. Now you can drag the line to the desired position and lift the pen. Voila! The new layout is saved in the preferences when you leave Yanoff.
"Offline" means that you have no server connection. Normally in this mode you already have the complete articles - that means headers and bodies - in your articles database. Thus you can read news in the bus or where ever. When reading an article you start reading the article automatically in the body if the current article has one in the database. If there is no body stored with the article (because you only downloaded the header) the header is displayed. If you read the body and want to take a look at the header data, just tap on header. The header gets displayed and the button that once displayed "Header" changes into "Body" - to switch back to the article body.
To the left there is a button called "Done" that closes the article view and gets you to the article list view. To the right there is a button labeled "K" and one labeled "S". When "K" is pushed, the current article is marked to keep and the button inverts. When pushed again, the articles gets unkeeped again. The "S" button does simliar things but selects/unselects the article. In the article list menu you can do some nice stuff with selected articles so this is a really useful button.
Since version 1.02 there are two arrow buttons to switch to the next and the previous article in a group. You can also enter a space (stroke to the right on the graffiti area) to switch to the next article.
 Header view |
 Body view with menu |
Also since version 1.02 there is a small menu in article view that lets you copy a selected portion of an article to the clipboard or select a complete article for copying. Remember that the clipboard of a Pilot is limited and it will probably not be able to contain the whole article at once. Workarounds are multiple select/copy cycles or clipboard expansion hacks.
And I am proud to present: Export to Memopad. Yanoff now supports the export of complete articles along with some header information to an unfiled Memopad entry.
If you want to answer to an article, tap on "F´up" to create a follow-up. See Writing an article for details.
"Online" means that you have a usable connection to a news server. Most of the things said for the offline mode apply here in the same way. The difference is: When you read an article that does not have a body in the database, Yanoff connects to the server, downloads the body that belongs to the header and switches to the body view.
To compose a completely new article use the menu command "/Comm/New Article". You have to enter a subject and the name of the newsgroup(s) you want to post the article to. Below the black line is the field that contains the body of the article.
If you use this command while being in article list view, the name of the active newsgroup is automagically inserted into the Newsgroups field.
When you are finished you can send the article immediately to the news server. This only works if you are in Online mode. If you are not, you can save the article. It is stored in the newsgroup "!!Outgoing" and can be sent by selecting the menu command "/Comm/Post saved". If you want to dispose of the article, you have to tap on "Cancel".
You can edit saved articles by entering the newsgroup "!!Outgoing" and selecting the very article you want to edit and then tap on the "Edit" button. You get to the same form that is used to create a new article.
Beware! If you tap on "Cancel" in edit mode, the article is deleted. If you want to leave the form without sending it immediately, tap on "Save".
The menu "Management" is full of useful maintainance commands that I do want to explain here.
The last menu is called "Misc" and contains miscellaneous items like some preferences forms and a reindexing facility. Sometimes it happens, that Yanoff hangs during a network download. This could be because your batteries run empty while downloading or because of other (unnormal) problems. Unnormal means, that Yanoff normally does not crash. Whenever this happens, though, Yanoff would have downloaded some articles but since they have not been installed into the newsgroups, they will never show up anywhere except in the database, consuming your RAM. In this case you can reindex the article database. All articles will be installed freshly into the newsgroups and you can continue downloading the rest of them.
There is a second utility in the "Misc" menu: "Reset newsgroup" that is only accessible when you are inside a newsgroup. Imagine you subscribed to comp.sys.palmtops.pilot and started downloading the last 50 articles. You read them, put your Pilot aside and three days later, you want to read some news on a bus tour. Normally you would have to download all traffic in the newsgroup of the past three days. This is a bit hefty and you probably read it on your desktop computer, anyway. So You can reset the newsgroup. It appears to Yanoff as if it has been subscribed to recently (the internal last-article-counter is set to 0). So at the next download Yanoff will only download the number of articles you entered in /Misc/Misc Prefs/Max articles. Resetting the newsgroup does not delete any article.
The goal of the project is to create a free, stable, functional and useful newsreader for the Palm Computing Platform. Because the source is distributed with the app all users can help to track down bugs or supply their own enhancements to make Yanoff better and more stable.
It would be very nice if you helped in one or another way. If you want to, please follow these rules:
Maybe you want to do some work in one of the following fields.
| Conduits | Useful would be conduits to sync with Forte (Free) Agent and Outlook (Express). Since I don´t know how to write a conduit help with this issue is very urgently needed. |
| Translations | In order to let as many people as possible benefit from this software I would appreciate translations of the software and the documentation into other languages (including asian ones). In particular, a translation into correct English would be nice. | Translation- tables |
If you don´t want to read ISO special characters in subject lines or even worse throughout the article, you should implement a translation function for Yanoff. | Compression | To save space in the article database a compressing routine would be fine. |
Author and maintainer of Yanoff is:
Matthias Jordan <mjordan@sensenet.wirepool.free.de>
The currently only available web space for Yanoff is located on free.de. Here you´ll be able to download the latest FAQ, the complete sources and the latest actual beta version.
Yanoff has been developed under Linux 2.0.36 using the fabulous free GNU c compiler and PilRC 2.4 from Wes Cherry. Thanks to the guys who wrote these fine pieces of software!
Version 1.1 has been built using multilink from David Williams. Thanks, David! This tool rocks!
As I already mentioned, Yanoff is free. Thas means: sell it, give it as a gift to your girlfriend (only if you want to be mean), change it, do what ever you want to do with it as long as my copyright notice is untouched. Whatever you do with Yanoff: you don´t have to pay for it.
If you do like this program and want to do something good, help the people in Nicaragua. After the severe catastrophy due to El Nino (not the handheld...) many people lost their houses and whole villages and acres have been destroyed. The health care is worse than bad in this small and poor country in Central America.
Many organizations accept donations. Even the smallest donations will be a help to support our friends in Nica. In Germany you can contact the SJD-Die Falken, a socialist youth organization that has a partner project in Leon, Nicaragua, and a direct contact to the people of the Juventud Sandinista (sandinist youth, youth organization of the FSLN). For contact information of other socialist organizations that could transfer your donations to Nicaragua you should visit the homepage of the IUSY. If the organization you contact has no link to Nicaragua, they will probably have a usage for your donation themselves.
Yes, it´s f****** political. (And: Yes, I also do other things than writing code.)