[ZooLib-dev] Let's talk about sample code & documentation

[Michael D. C. <cra...@go...>]

Many of you know that I'm supposed to be writing the documentation for ZooLib.
 

I'd like to write more sample code, and then I want to write tutorials on each
piece of sample code.  I'd like you all to discuss ideas for sample programs
with me, and I'll save up my email and use it when I write the sample code and tutorials.

It would help a lot of any of you folks would contribute sample code too.  It
doesn't have to be big, complex or take a long time to write; in fact the
simpler the better.  ButtonMessage is just a few source files.  One should
take care to write clean, proper code and do things right rather than in a
hurry or using skanky techniques.  I've seen some really bad, buggy sample
code on the Apple Developer Technical Support CDs.

We want to write the documentation in DocBook (http://www.docbook.org) - there
are many advantages to it; among them it can be readily rendered into
different formats such as Postscript, PDF and HTML for printed or online
viewing.  The Linux Documentation Project has standardized on DocBook.

On thing that's held me up is that it's complicated to get it working, but I
seem to have found good instructions for building and using a DocBook
toolchain on Linux.  Another good thing is that I've finally got my laptop
repaired and, while it boots Windows and BeOS also, I've decided to leave it
running in Linux most of the day so I can use it as a Samba and netatalk
fileserver (!) for my Mac and Desktop PC.  This means I won't have to go tear
my wife away from Windows 98 and reboot the PC to use Linux.

Writing a proper programmer's reference manual for the whole of ZooLib will be
a massive job.  It will also be of somewhat limited use in telling new users
_how_ to accomplish something in ZooLib.  

Andy's done some work with generating Doxygen files from ZooLib, and we can
provide tar or zip files of the generated HTML that people can download and
also have it on the web for people to casually browse, for example when they
want to just check something out quick.

Doxygen is like Javadoc for C++, but does a little more than javadoc.  For an
example, see the Doxygen output for Whisper, another fine cross-platform
application framework:

http://magnes.augsburg.edu/Whisper/html/

Doxygen's at http://www.doxygen.org

Andy's starting to put in the doxygen comment metacharacters so it will
extract a C++ comment and use it for the API reference in a Doxygen file.

What I think will get the most results for a moderate amount of effort is if
we write more sample code and then I write articles about each one.  

We should try to cover a wide range of ZooLib's functionality in, say, a dozen
programs but try to have each sample program focus on one component of ZooLib
so that a novice programmer can read and comprehend just a few source files in
one sitting.  Once enough sample programs have been written, a programmer
could work through each sample program one at a time and have a good overall
grasp of ZooLib.

Ideas I have for sample code include:

- a TCP echo client and server

- a simple ZDatabase server and query client.  You can enter an integer and a
string into edit fields in the client.  The string is stored in the database
with the integer as the key.  If you just send the key it will send back the
stored string or a "not found" indicator, and if you try to store an item
whose key already exists then it is replaced.

- Examples of doing various kinds of pane layout, and how to handle resizable
windows and also properly updating things when the pane size could change
after its data is modified.

I found layout the hardest part of ZooLib to grasp, but also one of the most
powerful tools it provides.  Andy and I have lots of ideas for utility classes
to make layout much easier to handle, so that one can write up a new window or
dialog with a minimum of fiddling.

- Examples of ZDCPixmap processing, both using GetPixel and SetPixel, and also
by directly accessing the pixel data via pointers offset from the base
address.  I'm starting to think about writing some iterators that will allow
the efficiency of direct memory access with nearly the ease and portability of GetPixel/SetPixel.

- Using streams and doing filters by chaining them.  One can illustrate a lot
of things just streaming in and out of a memory block, you don't have to touch
a file or network connection.  Of course there should be examples of file and
network streaming too.

- Reading and writing files, and using file open and save panels.

For the most part all of the sample code should be fully functional on all the
platforms.  At this stage this means we shouldn't use menus unless we really
have to, because menus won't work on XWindows.  Separate example code should
be written that does various interesting things with menus, and the people on
Mac, Windows and BeOS can use that.  When we have XWindows menus then we can
update all the sample code for a more natural UI.

(You don't have to get it to build on all the platforms yourself if you write
some sample programs, if you just make a reasonable effort to keep your code
platform-independent I can complete the job as I run all the platforms ZooLib
presently supports - any three at one time and as soon as I can afford one
more PC I can run all simultaneously without having to reboot.)

- It would also be useful to have sample code that fully exploited some
platform-specific feature on each of the supported platforms, for example one
could write a ZooLib application that used the BeOS media kit.  

This would illustrate that while being cross-platform is generally an
advantage it doesn't cripple one by requiring lowest-common-denominator
programs like SOME cross-platform approaches, and that using ZooLib to write
platform-specific code may be a more pleasing alternative to the more popular
application frameworks and native APIs because of its quality architecture.

I will generate Doxygen HTML files for each sample program, and post them online.

Then I will write DocBook tutorials on each sample program.  I'll do this for
my samples as well as any you write, unless you'd like to learn how to write
DocBook XML yourself.  

Having Doxygen-formatted comments in the sample code will go a long ways in
itself, but having the DocBook would be a better format for discussing the
motivations for doing things a certain way at greater length and in a more
pleasing-to-read format than the Doxygen.

I started writing an article for ZHelloWorld last year and called it the first
chapter of "The ZooLib Cookbook" but then I ran into problems because I wasn't
using an editor that would keep my document valid to the docbook DTD.

One thing I did find in this early effort is that it's not actually very hard
to learn to write DocBook source files by hand.  There are only a few tags one
needs to use to write most of one's text.  DocBook can get tricky   

Probably the most annoying thing is that one needs to convert "<" and ">" into
"&lt;" and "&gt;" respectively - these are called "entities" and are needed so
C++ template code won't confuse the XML parser.  But there are text-to-HTML
conversion utilities that are readily available so that rather than
laboriously hand-correcting my code snippets for the doc I can just filter them.

So what ideas do you have about sample code?  Do you have any samples you
think you could write based on what you know, or could you tell me what
samples you either might find useful now or would have found useful when you
first started?  What would you see as the philosophically or practically best
way to approach any particular aspect of ZooLib programming?

Mike
-- 
Michael D. Crawford
GoingWare Inc. - Expert Software Development and Consulting
http://www.goingware.com/
cra...@go...

   Tilting at Windmills for a Better Tomorrow.