Frequently Asked Questions about the Palmtop News Reader (PNR), Palmtop News
Reader Threader & Indexer (PNRTI), and other accompanying programs.

Written by Michael J. Leaver
Last updated: 17-SEP-96

If you have any additions for this FAQ please mail me the questions and
answers and I will included them in future releases.


Index
=====

0.   Latest release version numbers
1.   General
2.   Programs & scripts
3.   The configuration file
4.   File formats


=== 0. Latest releases version numbers

Program        Version
-------        -------
PNR            1.2
PNRTI          1.01
SUMSORT        1.0
Rot-13         1.0
SOUP2ZIP       1.0

=== 1. General

Q. Is PNR and its accompanying programs and source code freeware, shareware,
   or what?
A. PNR and everything that comes with it are freeware, but I hold the
   copyright on the programs, their soure code, and their accompanying
   documentation. The fonts are not mine, they are copied from the PAL
   distribution. PNR and its accompanying programs may be distributed freely
   without charge as long as they a distributed as an entire package, with
   no files missing.

Q. Will PNR work on my PC?
Q. Will PNR work on my HP-95LX?
A. PNR.EXM only works on HP100LX and HP200LX palmtops. PNR.EXE will work
   on a HPx00LX and a desktop (using CGAGRAPH.COM supplied with the PAL
   distribution, see below).

Q. What is PAL? Where can I get it?
A. PAL is a suite of programs, utilities, and a library which helps you write
   applications for HP palmtops. PNR uses the PAL library. See eddie.mit.edu
   for a copy (at time of writing it's in the directory /pub/hp95lx/NEW).

Q. I cannot read the PNR.DOC file. What format is it?
A. Load it into MEMO on your HP palmtop.

Q. Doesn't the QWK format mess up the headers?
A. Yes, but PNR does *not* use the QWK format. It uses the ZipNews format
   which does not corrupt any part of a message. The ZipNews format is an
   extremely simple format which does not alter any part of a message (nor
   does the SOUP format).

Q. I only have a SLIP/PPP connection so I cannot use UQWK. What can I do?
A. If you use Windows-95 then you can now use PNR. There is a version of UQWK
   available for Windows-95 that produces SOUP format files only. As from
   version 1.1 of PNR an extra program callled SOUP2ZIP.EXE is provided to
   convert these files into ZipNews format, which PNRTI understands. The
   source for SOUP2ZIP is also provided. See the documentation for more
   information.

Q. Where is the Windows-95 version of UQWK?
A. ftp://ftp.itribe.net/pub/virtunix/uqwk_04.zip
   http://www.itribe.net/virtunix

   As of writing the program is still undergoing improvements/modifications
   but the current version is stable & works.

Q. I have a shell account but I cannot install UQWK. What can I do?
A. If you also have SLIP/PPP access and Windows-95 then use UQWK for Win95
   instead.

   If that is not possible then insist that your service provider installs
   UQWK. It may already be installed on your system.

   If thats out of the question then there are a number of options, see the
   documentation for PNR. Basically, if you have the 'tin' newsreader then
   you're safe. If not, then it is still possible to read your mail offline,
   but not news. Even so, you may find another solution.

=== 2. Programs & scripts

Q. Do you have any examples of how to retrieve news and mail from a UNIX
   host?
Q. Do you have any examples of how to send replies from a UNIX host?
A. Yes, see the shell script files GIVEME and SENDME. Edit them for your
   own use.

Q. Do you have any examples of how to retrieve news and mail from Windows-95?
A. Yes, see the batch file GIVEME.BAT. Edit it for your own use.

Q. What is the difference between PNR.EXE and PNR.EXM?
A. PNR.EXM is the System Manager compliant version for use on HPx00LX
   palmtops. PNR.EXE is an MS-DOS version that can be used on a HPx00LX and
   a desktop PC via use of CGAGRAPH.COM (supplied by PAL, see above). If
   you have a HPx00LX then use PNR.EXM.

   There are four main differences between PNR.EXM and PNR.EXE:

        o PNR.EXE has no access to the System Manager and HPx00LX hardware
          and as such cannot call the MEMO editor etc. and so must have
          the 'editor' setting defined in the config file.
        o PNR.EXM cannot import files as from version 1.1, but PNR.EXE
          can import files.
        o Only one file can be attached to a message (wildcards cannot be
          used) in PNR.EXE
        o The Alt key cannot be used to get the menu on PNR.EXE. Instead press
          the MENU key or 'm'.

   PNR.EXE is supplied just in case PNR.EXM proves to not be System Manager
   compliant and is not provided as a replacement for your desktop offline
   newsreader (as if).

Q. What is a summary file?
A. A summary file is produced by UQWK by typing 'uqwk -Usumfile'. This
   will produce a text file called 'sumfile'. This file lists the subjects of
   all articles that you haven't read.

Q. Uqwk sometimes crashes when it produces a summary file?
A. There seems to be a bug in the UNIX version of uqwk - it can't produce
   summary files greater than 64K (65535 bytes).

Q. What do I do with a summary file?
A. First, you can use SUMSORT to sort the subject lines within the summary
   file simply by typing 'sumsort sumfile'. Next, edit the summary file and
   remove all subject lines that you do not wish to read. You can then give
   this file back to uqwk and ask it to retrieve those subjects. This is
   done via 'uqwk +z -Esumfile' (or 'uqwk -Esumfile' on Win95 UQWK).

Q. When I try to read my news & mail PNR complains about being out of
   memory before the group index is even displayed!?
Q. When I view articles PNR complains about being out of memory or not all of
   the article can be viewed!?
Q. When I use PNRTI to index my news & mail it warns me about there being
   too many articles for PNR!?
A. As PNR is a System Manager compliant program it has been compiled under
   the small memory model, as rules dictate. This means PNR has a paltry
   64K of data space available to it. As you can understand, storing all
   the details about the articles & groups can take a lot of memory. Every
   effort has been made to reduce memory usage.

   As a rule of thumb, having more than 400 articles will use up all the
   memory available. PNRTI will give a warning message if more than 350
   articles are in the news & mail. If PNR runs out of memory you'll just
   have to re-adjust your commands to uqwk (the -B option allows you to
   specify the maximum number of blocks, but not the maximum number of
   articles).

   If you have a lot of news to read then execute uqwk more than once, so
   a number of news packets are produced. Telling uqwk not to produce more
   than 4000 blocks is the average (uqwk -B4000 ...)

   Another option is to reduce the memory usage within PNR. One way is not to
   use external fonts. Another way is to change the 'reserve' setting in the
   configuration file. This defines how much memory is reserved when an article
   is displayed, which is 10,000 bytes by default. If this value is reduced too
   low you will always get out of memory messages, as the PAL library used by
   PNR requires memory (actually the reserved memory is pretty much entirely
   for PAL's use). If its too high then you won't be able to view an article,
   or maybe only part of it. Experiment.

Q. When I move up one line when viewing a message it sometimes jumps up more
   than one line. Why?
A. When the end of a message is reached a filled box appears in the bottom
   left of the display. If you're at the end of a message and the entire 
   display is not taken up then when moving up a line PNR will actually move up
   enough lines to fill the rest of the display. It's a feature, not a bug...

Q. My folders index file has become corrupted. How can I repair it?
Q. My folders news file has become corrupted. How can I repait it?
A. Currently this is not possible. A future version may correct this.

Q. I want to create my own fonts for use with PNR. How?
A. Get the PAL library (available from edie.mit.edu). It contains utilities
   for creating & converting fonts (and also the fonts distributed with PNR).

Q. How can I attach more than one file to an outgoing message?
A. When entering the filename to attach in the dialog box simply use wildcards.
   For example:

	Attach file(s): c:\*.txt

   You cannot enter a list of files (e.g. a.txt,b.txt).

Q. How can I import a group of files into a folder?
A. You can use the same technique as attaching more than one file. When asked
   for the filename of the file to import use wildcards.

Q. Where are the index files for replies?
A. They do not have one. A group & article index is created on the fly in
   memory each time the reply group/articles are accessed.

Q. When I upload my reply files from my palmtop to my host Unix system all my
   filenames are in uppercase. How do I stop this happening?
A. Its how the file transfer protocol is implemented on your terminal program
   that's at fault. On Telix they are transfered in lower case, but the built
   in DataComm program on the palmtop transfers them as upper case. To get
   around this compress all your files (e.g. using Pkzip) then upload that
   file and uncompress it on your host. They will be uncompressed and extracted
   to lowercase filenames.

Q. My signature file does not get appended to my messages. Why?
Q. When I post news I get two signatures appended to my articles. Why?
A. Your signature file must be called [user].SIG, e.g. if your username is
   mickyj then your signature file must be called MICKYJ.SIG. This file must
   be in your news directory (specified in your configuration file by newsdir).

   When uqwk actually posts your messages to newsgroups it will append the
   contents of your $HOME/.signature file to the messages. This applies only
   to postings, not mail messages as uqwk will not append your signature file
   to mail messages. So if you have a signature file for PNR and one on your
   host system you will get two signatures attached to postings. Delete one of
   the files to avoid this.

Q. How can subscribe/unsubscribe to newsgroups using PNR?
Q. How can I send commands to Uqwk?
A. If you don't use uqwk then this answer doesn't apply to you. You can send
   commands to the uqwk program via mail messages. Simply send a mail message
   to the user UQWK (capital letters) with the subject UQWK and just put
   HELP in the message. Simply send this mail message as per normal using
   uqwk. After uqwk has sent your mail, posts, etc. check your mailbox. You
   should have a reply from yourself which was generated by uqwk.

   If you want to subscribe to a newsgroup, for example:

     SUBSCRIBE comp.sys.palmtops

   If you want to unsubscribe to a newsgroup, for example:

     UNSUBSCRIBE alt.test

   You can put more than one command into the mail message. Note that PNR
   will *not* add your signature to any mail send to UQWK as it would only
   confuse UQWK.

Q. When I import an external file into a folder and I try to view it, it says
   the article is corrupted. Why?
A. When PNR loads an article into memory for you to view it checks to make
   sure the article has a header. For an article to have a header it must have
   one or more lines followed by a blank line followed by one or more lines.

=== 3. The configuration file (C:\_DAT\PNR.CFG)

Q. I don't want PNR.CFG to be in C:\_DAT. How do I move it to another
   directory?
A. You can't.

Q. PNR complains about the configuration file having to contain settings for
   user, host and newsdir. What do I do?
Q. PNR is not loading my configuration file even though I created it!?
Q. PNR is not loading the settings I've put into my configuration file!?
A. The configuration file must be called PNR.CFG and must be in the directory
   C:\_DAT

   All comment lines start with a semi-colon (;). The settings must go
   underneath the section name [PNR], for example:

   ; This is a comment line
   ; The following line IS ABSOLUTELY NECESSARY!
   [PNR]
   user=mickyj
   host=hk.net
   newsdir=c:\news

Q. When replying to messages I want all the quoted text prefixed by something
   else other than '> '. How?
A. Change the setting for 'prefix' in the config file, e.g.:

     prefix='You Said> '

   (Note the single quotes so as to make sure the final space is included).

Q. My fonts are not all in the same directory, so the 'fontdir' setting is
   no use. What can I do?
A. Comment out the 'fontdir' setting in the config file and specify the full
   pathname for each external font required, e.g.:

   smallfont=c:\fonts\myfont.hnf
   largefont=f:\vr\otherfont.hnf

Q. I want to see the message header when viewing a message. How?
A. If you want to see the header for a message press '-' or Home.
   If you always want to see the header put the following line in your
   c:\_dat\pnr.cfg file:

     header=1

Q. I want to use a SysMgr compliant (.EXM) editor as my editor. How?
A. This *may* be possible, but it depends upon your editor. First of all,
   comment out the editor setting in the configuration file. This setting is
   for DOS executables only. When the editor is not specified MEMO is used
   by default. PNR starts MEMO by feeding key scan codes into the keyboard
   buffer and storing the complete filename of the file to edit in the
   palmtops Clipboard. The scan codes put into the keyboard buffer can be
   changed.

   scancodes defines the list of scan codes, seperated by commas, e.g.:

    scancodes=118,67,111,68

   These are the scan codes for: MEMO, F9, PASTE, F10

   Remember that the complete filename of the file to edit is stored in
   the cut & paste buffer.

   Here is a list of scan codes:

    F1..F10 = 59..68
    0 = 11
    1...9 = 2...10
    q w e r...p = 16...25
    a s d f...l = 30...38
    z x c v...m = 44...50
    ESC = 1
    MENU = 200
    Zoom = 208
    DEL = 83
    BackSpace = 14
    - = 12
    + = 13
    Up, Down, Left, Right = 72,80,75,77
    ENTER = 28
    PageUp = 73
    PageDown = 81
    Space = 57
    Home = 71
    End = 79

   To apply shift add 128 to the scan code (e.g. for X and not x the scan
   code is 45 + 128 (173).

Q. How can I use aliases when sending mail and posting to newsgroups?
A. As an example, if you put the following in your configuration file:

        offline=alt.offline.news-readers, comp.msdos.readers, alt.dont.exist

   Then when posting an article just enter offline in the list of newsgroups
   to post the article to. You can use more than one alias in the list, and
   use non-aliases with aliases. Note that the newsgroups list (once expanded)
   cannot be more than 512 characters. Aliases cannot be nested. See the
   documentation for more information.

Q. I use an external editor and when PNR calls it the editor is still in
   graphics mode not text mode. How do I fix it?
A. This is a problem with some editors (e.g. vi for DOS). Instead of calling
   the editor directly, use an intermediate batch file, e.g.:

     @echo off
     mode co80
     vi %1%

Q. Why aren't my lines broken up correctly, i.e. left justified?
Q. Why do my messages contain long lines, i.e. each paragraph is just one
   long line?
A. PNR/PNRTI does not format any input or output messages. If use use Memo
   to write your messages you must press return at the end of the line, for
   example, or you end up with long lines. PNR has no problem displaying such
   lines, but other news readers may.

=== 4. File Formats

Q. What is the format of incoming ZipNews files?
A. The ZipNews format is actually proprietery and not open. As far as I am
   aware no documentation on the format is available.

   <user>.mai - The mail file (optional and may be empty)
   <user>.nws - The news file (optional and may be empty)
   <user>.jn  - Subscribed (joined) newsgroups (not used by PNRTI)
   <user>.idx - Index file

   .idx file
   ---------

   N 99999999 newsgroup_name

   .jn file (not used by PNRTI)
   ----------------------------

   newsgroup_name index_of_last_read_article

   .mai file & .nws file
   ---------------------

   [string of 20 ASCII 1's]
   [mail message/news article]
   [string of 20 ASCII 1's]
   [mail message/news article]
   [etc.]

Q. What is the format of outgoing ZipNews files?
A. The ZipNews format is actually proprietery and not open. As far as I am
   aware no documentation on the format is available.

   <user>.id  - ID (key) file (required by uqwk)
   <user>.a?? - Email address files (corresponds to equivalent mail file)
   <user>.m?? - Mail message
   <user>.n?? - News article

   For example, if mickyj.m01 exists then mickyj.a01 contains the destination
   email address(es) for that message.

Q. How is the <user>.ID file created?
A. Uqwk will not post & mail messages unless the ID file is correct. This is
   because the ZipNews format is proprietery and only registered users of the
   ZipNews offline news reader are allowed to send outgoing messages. The
   contents of the ID file is your encrypted username.

        /*
        ** Create the ID file required by UQWK. This crap is because the Zip
        ** News Reader sends this encrypted ID file with the postings. UQWK
        ** checks if the ID file is valid before it posts the files. To be
        ** able to post from the Zip News Reader (and hence have an ID file)
        ** you need to register the crap software first. Well bollocks to that.
        **
        ** ARGS:    user name (e.g. mickyj)
        **          real name (e.g. Michael J. Leaver)
        **
        ** RETURNS: 0 if ok, -1 on error (cannot open file)
        **
        ** P.S. you can copy and distribute this function.
        */
        #define MAX_ID_LEN      64
        int create_id(user_name, real_name)
        char *user_name, *real_name;
        {
            extern  char    *ZipDir;
            char    fname[MAXFNAME],
                    str1[32],
                    str2[MAX_ID_LEN],
                    *ptr,
                    str3[MAX_ID_LEN];
            FILE    *out;
            int     ch, i3;
            int     i2=0, z=0;

            /* Open output file */
            if ((out=fopen(GetFileName(fname, MODE_REPLIES, GFN_ID), "w"))==0) return -1;

            /* Base encryption string */
            strcpy(str1,"Vrth#glfp#YjsMftp-#Kllqbz-");
            i3=strlen(str1);
            for(ptr=(&str1[0]);*ptr;ptr++)
		*ptr^=3;

            /* Create unencrypted contents of ID file */
            sprintf(str3, "ZNR+UQWK 0\n%s\n%s", real_name, user_name);
            ch=strlen(str3);
            str3[ch]=10;
            str3[ch+1]=0;

            /* Encrypt it & output to file */
            ptr=(&str1[0]);
            while(z<strlen(str3)) {
		ch=str3[z];
		str2[z]=ch^*(ptr+i2)^(*ptr*i2);
		*(ptr+i2)+=(i2<(i3+1))?*(ptr+i2+1):*ptr;
                if(!*(ptr+i2)) (*(ptr+i2))++;
                if(++i2>=i3) i2=0;
		fputc(str2[z], out);
		z++;
            }

            /* Done */
            str2[z]=0;
            fclose(out);
            return 0;
        }

Q. What is the format of SOUP files?
A. Documents defining the format are freely available on the Internet.

Q. What is the format of the .PNG files?
A. PNG files are the group index files. News & mail share the same group
   index file, which is created by PNRTI. The group index file for folders
   is created by PNR. They are of the same format:

    Number_of_groups(%05d)
    Number_of_articles(%05d) Flags(%03d) Group_name(%s)
    Number_of_articles(%05d) Flags(%03d) Group_name(%s)
    Number_of_articles(%05d) Flags(%03d) Group_name(%s)
    etc.

   The Flags can be (may be or'd together, e.g. 9=read & filed):

    0   Unread, unkilled, not deleted, not filed (i.e. untouched)
    1   Read
    2   Killed (marked as killed)
    4   Deleted (marked for deletion)
    8   Filed

   Note that the order of the group index file must be correct for the articles
   index file, i.e. if the first group has 5 articles then the first 5 entries
   in the articles index file refer to that group and so on.

   The source code file PNRLIB.C that comes with PNRTI contains all the
   functions necessary for reading & writing group and article index files.
   See also PNRIDX.H

Q. What is the format of the .PNA files?
A. PNA files are the articles index files. News & mail share the same article
   index file, which is created by PNRTI. The article index file for folders
   is created by PNR. They are of the same format:

    Subject(%s)
    Author(%s)
    Article_size(%u) Flags(%d) Offset(%ld)
    Subject(%s)
    Author(%s)
    Article_size(%u) Flags(%d) Offset(%ld)
    Subject(%s)
    Author(%s)
    Article_size(%u) Flags(%d) Offset(%ld)
    etc.

   The flags can be (exclusive, cannot be or'd unlike article flags):

    1   News group
    2   Mail group

   The source code file PNRLIB.C that comes with PNRTI contains all the
   functions necessary for reading & writing group and article index files.
   See also PNRIDX.H
