Z-DOC / PalmPilot
ZDOC is a GPLised industry standard DOC file format viewer/editor with a few extras. It is released only under the terms of the GNU GPL. Please read the files GPL.TXT and ZDOC.TXT for a full description and terms of the GPL as well as an introduction to ZDOC.

You can download ZDOC from the ZDOC Programmers page by clicking .

You can read the ZDOC manual from the ZDOC Manual page by clicking .
 

PalmPilot WebRing

ZDOC FAQ :-

This is a list of frequently asked questions about ZDOC. It should cover most queries, but mail me if you have any others. RTFM before mailing me -- i dont have a lot of time to answer a billion queries. They arent in any specific order -- just dumped in when i recv queries.

[0.0] How fast do you release ZDOC versions ?

[0.0] Varies -- depending on my mood and how much time I have. It usually takes a week between version upgrades when I have access to a machine for a minimum of 8hrs/day and no other work. This will slow down or stop to one version every month or so when i cross a decent threshold of features.

[0.1] You dont have access to a machine ?

[0.1] I dont have any machine with the exception of my PalmPro. No PC/Unix machine. I get access thru public terminals where i've installed the GNU SDK. I dont have a great deal of cash to afford a decent laptop.

[0.2] How stable is ZDOC ?

[0.2] As stable as I could make it. It doesnt crash under the 2.0 debug ROM which is supposed to include lots of checks. As I spent a year programming on a Irix platform i've dealt with a lot x/motif memory leaks. As a result my memory handling routines should be stabler than most other ppls. I cant guarantee anything though. Its not as thoroughly tested as some of my other software and you use it at your own risk. As a general rule of thumb try to open files which are less than 250K and do not open them unless you have at least 2 times the file length in free RAM. i.e. if youre editing a 100K file make sure you have 200K free ram in your pilot. (Check it via the memory utility). This is normal for any DOC app, not just ZDOC. DOC apps consume RAM faster than any other apps. [[Note that
this does not apply to betas/alphas/test releases..theyre as buggy as hell.]]

[0.3] What about bugs ?

[0.3] What about them ? (heh.) I've weeded out most of em. If you find any try and fix it yourself (the code is GPLised) and mail the thing to me with all possible details of it -- i'll whack it up soon, or modify/improve it to fit in all versions of ZDOC. If i release a special test version then just mail me the bug and i'll try and fix it immediately. this applies for test versions only [ e.g. 5.x.x c ] all versions with a c extension are test releases.

[0.4] Is there a seperate programmers page for ZDOC ?

[0.4] Yup. Try this one.

[0.5] I've put a really groovy must have thingy into ZDOC. How do i release it ?

[0.5] Mail it to me with express instructions including where it fits and what it does. Mail me the version of ZDOC used (must be the most release version i.e. no alpha/beta) and i'll put it up with your name (if you would like your name there).

[0.6] Can i send you encrypted mail ? Your PGP key is on your site.

[0.6] NO. Not regarding ZDOC. I allow/use encryption for confidential mails only. Mailing me encrypted junk gets you onto my kill filter ASAP.

[0.7] I lost my data !! ZDOC wiped my system !! it crashed..etc..etc.

[0.7] Restore from hotsync. mail me OS version, what you did, what files you worked on, what files you had loaded and what versions they were, all file/database sizes. I'll try and work on it to remove the bug, but no guarantees are made. Youre using this program at your own risk. I *do* have *some* motivation to remove total loss bugs (if any occur -- ive not seen it happen yet) since i use ZDOC extensively myself. (and no.. i dont take the advice from [0.2] seriously either. i routinely use it in low memory situations, but ive never lost anything uptil now -- on the other hand i DO keep hotsyncing at every oppurtunity)

[0.8] Does ZDOC work with/compatible with any other DOC readers/writers ?

[0.8] I've always kept a freeware DOC reader on my system. Usually its Aportis DOC Mobile edition or the freeware DOC reader from Aportis. They cause no problems and ZDOC can handle bookmarks easily (i.e. right now it just ignores them).
 
[0.9] Why dyou keep a freeware reader on your system ?

[0.9] Just in case (heh). Acutally i prefer to work with readonly mode readers rather than a reader/writer such as ZDOC for browsing files. Its safer. For editing files I just use ZDOC. Note that ZDOC Ver2.x or below open files in ReadOnly mode and are as safe (or safer) than Aportis readers since Aportis readers add bookmarks which means they write to the file. ZDOC 2.x or below DO NOT write to the file. After Ver2.x it does...since i use Ver3.x and above this doesnt apply to me. Note that Ver4.0.5a and beyond now write to the file only when you press the save command...otherwise they open the file in readonly mode.

[1.0] How stable is the code ?

[1.0] Very. ive not seriously broken it til now. It uses PalmOS 2.x API calls only to allocate/deallocate memory and no funny stuff. It should be compatible with PalmOS 3.x too..although i dont have a palm iii so i guess i'll wait til i find someone who tries it on one.

[1.1] Are you registered with 3COM ?

[1.1] I'll try to get ZDOC PalmOS certified..no guarantees on this. I've registered ZDOC's AppId with 3COM -- it's ZURK. I've also Gremlin tested each version of ZDOC and ensured that it runs on both 2.0 and 3.0 debug ROMs. Note that the test versions of ZDOC are not gremlin tested fully..usually they are put through 1000 or so cycles and not the 1-2 million recommended.

[1.2] Im a newbie programmer...i wanna learn ! Cant find anything -- help !

[1.2] Mail me -- i usually help if im not too busy. it takes a while but i'll get around to replying. Note that i only help ppl who work on GPLed code and use GCC. If you use any other development engine/develop commercial/shareware code -- forget it. Mail me your website, the location of GPLised code that you have contributed to the general public and any apps (with code). If i like what i see and i think you have potential i'll reply. Very newbie newbies who havent done anything but are prepared to show intent to develop GPLised apps are also welcome. I must have your website tho, and you must be using GCC.

[1.3] How come you havent put your real name on your site ?

[1.3] I believe in my freedom to remain anonymous. That and it makes me a lot tougher to sue. As such i dont put any real names/addresses up. I guard my privacy VERY carefully. And no, i wont give it to you if you ask me either. You may email me of course. My email address is functional (zurk@geocities.com).

[1.4] Have you written/going to write any other pilot software besides ZDOC ?

[1.4] dunno. will see.

[1.5] I want ##spiffy feature #999## in ZDOC. How do i do that ?

[1.5] Mail me your specs for #999 and i'll include it if i think it interesting. otherwise i'll delete the mail. get off your lazy backside and do it yourself before mailiing me...unless youre a total newbie.

[1.6] Why does ZDOC work on only 4K at a time ?

[1.6] Until i feel a HELLUVA lot more comfortable working with big chunks of data on a palmpilot, thats the way it stays. 4K is nice neat and simple. And theres no problem about the OS suddenly freaking out due to too much RAM consumption. Anyone want to patch ZDOC to work with over 4K at a time ? mail me
and try it out..if i feel its stable ill put it into the full versions.

[1.7] Does it work with PalmOS 1.x ?

[1.7] NO. thats been confirmed. Check the mail below :-

Here's the scoop,  I just downloaded version 4.0.5a (which according to you is the
new version) and tried it in CoPilot (I've had to remove the RAM file everytime
following a crash anyway so I was already doing that).  It caused an application error
when I clicked on the open button and closed CoPilot.  I went ahead and
downloaded it to my pilot and it still hangs on the info window when the open button
is clicked.  However, this version does not generate the MemoryMgr.c invalid handle
error so I was able to remove it without the hard reset :)  (BTW when I mentioned
that in CoPilot it was locking up, I meant it was generating an application error and
closing out).

Jonathan Beach
CMHC Systems
Systems Support Engineer

[1.8] DOC files...what are they ? where can i get info for them from ?

[1.8] Although Aportis has not formally released the DOC specification to the general public, heres a mail that might help :-
The database layout is pretty simple:

  - record 0 is a header which contains the following:
      - a short int (2 bytes) containing the file version
        (1 = uncompressed records, 2 = compressed records)
      - a short int containing something unknown and unimportant
      - a long int (4 bytes) giving the total *uncompressed* length of
        the text
      - a short int giving the count of text records
      - a short int giving the *uncompressed* size of each text record
        (default 4096)
      - a short int containing something unknown and unimportant

      readers may add a bit more to this record the first time they
      open the file, but only the above needs to be there when it is
      created.

  - records 1 - n (where n is the number of text records) each contain
    a block of text of a fixed size, normally 4096 bytes.  That is
    4096 bytes *before* compression -- the actual size of the record
    will be somewhat less, because it contains the compressed data.
    However, since the uncompressed size of each record is known, it
    is easy to seek to any particular point in the file and uncompress
    one record at a time using a fixed-size buffer.

  - records n+1 to the end are bookmarks.  Each one contains a 16-byte
    string (null terminated, but always takes the full 16 byte area)
    followed by a long int giving the seek position of the bookmark.

The compression algorithm is too complicated for me to describe here
(as such things go it's rather simple, but it is still easier to show
with code :) so your best bet is to look at the code.

> I managed to get some make doc samples for unix and could
> probably reverse engineer them, but its irritating when the DOC standard
> is supposed to be an "open industry wide standard" (according to the
> author of PilotDOC). I did find a few msgs which commented on the
> Micro$oft style takeover of pilotdoc by aportis but nothing else.
> Any help would be appreciated as i plan to create a few DOC apps over the
> next month or so (GPLised of course).

If you are working with Unix, I urge you to check out my package
called "PalmPython".  I don't know if you ever use Python, but even if
you don't you ought to give it a look because I did some pretty
extensive Doc-making stuff.  (I also have a simple XML-to-Doc
converter that uses it.)  Python is fairly easy to read even if you've
never used it before, provided you understand basic OOP etc.

In particular, PalmPython contains a snippet of C code to do Doc
compression and decompression, which you can probably use elsewhere.
(It's two functions and a Python-API wrapper.)  If you actually *use*
PalmPython, it contains code for reading and writing Docs as file-like
streams, complete with automatic compression and reader-style
bookmark-setting (the latter of which none of the other Doc-makers do,
even on other platforms).

PalmPython is GPLed, so do with it what you will.  (If you actually
use it for anything, please let me know, send patches and
compatibility reports, etc.)

PalmPython is available at
   http://www.io.com/~rob/cq/
along with its companion XMLDoc. As I said, even if you don't use
Python, you might want to read the source and copy bits of _Doc.c.
By the way, when you mention creating "a few Doc apps", do you
perchance mean a reader?  The world desperately needs an open-source
Doc reader on the Pilot -- I would do it myself, but I have made so
many failed attempts at decent Pilot programming it's not funny, and I
have thus decided to stick to the desktop side.  If you are
considering doing one, please take this as a hearty endorsement of the
idea :-)

--Rob

--
Rob Tillotson  N9MTB

[1.9] ZDOC crashed/machine reset ! It also left a database called ZRAM on my machine..what do i do ?

[1.9] Erase off the ZRAM database. Its a temporary database of no importance. Be aware that if ZDOC
crashes while saving, and you have a lot of important work that should be saved/you have no backup of
that work, ZRAM will contain the record which should have been saved. ZRAM contains just one record,
record 0, with a text version of the field that ZDOC is currently working on. It serves as a backup.

[2.0] Whats the tiny symbol displayed on the top right hand corner when i save to a compressed file ?

[2.0] Thatrs a replacement for the ugly status messages. A small arrow pointing downwards is displayed on
the top right hand corner when ZDOC is ready for user input. A small star symbol is displayed when it is
busy (usually compressing and saving text)..its equivalent to the arrow/hourglass figure in windoze.

Note: if anyone doesnt want their mails etc posted up i'll be glad to remove em. mail me.
         All copyrights are acknowledged.
<-EOF->