Category:
I’ve been playing with my new Linux-powered Sharp Zaurus SL-5500 PDA since last Thursday and I wanted to pass along my impressions so far. First off, I have to say this is the coolest little gadget since sliced bread. I have lived with a Palm IIIx for almost three years as my steadfast companion, but this device just blows my mind with its potential.
Secondly, I have to say that the Zaurus is far from perfect. There are
“gotchas” a-plenty that I will elaborate on later.
Hardware
The best description of this PDA is that it’s a Linux laptop that
fits in one hand. With its hardware, it’s pretty well set:
Software
This thing covers all the software basics. Navigation is very easy,
and everything is clear and uncluttered. There are five major groups:
apps, games, jeode (java apps), settings, and documents, for all files that
aren’t applications. You can navigate to each easily with the
buttons on the front of the Zaurus, or using the touch screen. The menu
bar at the bottom of the screen gives you easy access to time, volume
control, battery status, external card status, network status,
application switching, and a start button. Again, it’s all laid out to
make it pretty easy to get around and do stuff; there’s no confusion.
The sync software, the good
The Zaurus comes with two kinds of sync software: Qtopia Desktop and
Intellisync. The Intellisync is for syncing with MS Outlook, and because
I don’t run Outlook, I can’t tell you anything about that. The
Qtopia Desktop I do run; it’s basically the same thing as Palm’s Desktop
software. I had no trouble setting it up with Windows 2k. I followed
the directions, and it hooked up no problem. Setting up the Linux
version was a little more difficult. The Windows version comes with the
Zaurus on CD, the Linux version I had to download from Trolltech. They
screwed up and put the Win32 install instructions in the .tgz file
instead of the Linux instructions, so I had to go download an older
version to get the correct install instructions.
Mandrake 8.2 almost
recognized the Zaurus from scratch. When you plug in the Zaurus, it is recognized
as a USB device, and Mandrake tries to load the driver for it.
Unfortunately, it loads the wrong driver. Messing around with
modules.usbmap I changed a couple of values for the usbdnet driver and
now Mandrake loads up the correct driver. I added an ifcfg-usb0 file in
the network-scripts directory, and now I have a hot-plugable
interface. The Qtopia Desktop hooked up, no problem, and I was able to
sync from the Zaurus to my Linux desktop without any trouble.
The sync software, the bad
The Qtopia Desktop software is flaky. I would not recommend this setup
to a novice PDA user. It is possible that my impression is influenced by my coming out of a Palm-based world, but the software doesn’t seem to work the way I would
expect it too when syncing. I have twice lost significant amounts of
address entries or calendar entries do to syncing issues. I have found
that the only way I can reliably enter stuff is to leave the sync
software on “PDA overrides desktop.” When entering lots of data in
the desktop side, I then manually switch it to “desktop overrides PDA,” do
a sync, then back to “PDA overrides desktop.”
The issues mostly come up
when you enter stuff on the desktop or change things on the
desktop while there are already similar entries on the PDA. It
doesn’t handle this well. For this reason, I would say this setup is not
for the general consumer. Only people who know how to be careful should
use it. The Intellisync software may be better, but again, I haven’t
tested it. The Linux version I have was just
released this weekend (it’s listed as a beta version).
Miscellaneous issues
There is one major security issue: The version of Linux the
Zaurus runs does not come with support for IPtables or IPchains. This
wouldn’t be horrible (it actually disables a lot of the normal daemons
that are problems) except for one screw-up. Someone decided to use FTP
as the syncing software’s conduit, and even better, it logs in as root
with no password! So the qpe daemon (which is the Zaurus GUI interface)
also has an ftp daemon running on port 4242 with root login and no
password, and it is bound to all ports, all IP addresses! The Zaurus
comes with tcpwrappers, but qpe doesn’t run through that, so if you
hook the Zaurus up to a network, root file read/write access is
available to all. You can set a root password, which at least puts a
password into the mix, but reports are that it kills the sync ability (I
haven’t investigated this yet).
At the moment, this isn’t a terrible
issue for me, because I’m using my Zaurus as a PDA without an Internet/external
network connection for now. But because I plan on purchasing a network
card for it, I also plan on figuring out some way to firewall this thing
off from the outside world.
Summary
The Zaurus is a great hardware device with some minor and major software
issues. I would recommend this device to Linux and computer-savvy
people who want a very flexible PDA, with warnings about the
potential issues. Most of these issues can be avoided with some care.
This is a new product, and like many new products it has bugs. I hope
these bugs will be fixed quickly, and given the Open Source nature of
the device, this should be possible. It would be a shame for a couple of
stupid mistakes to ruin the Zaurus potential. I’m happy with my
purchase, and look forward to putting this little beast to some hardcore
sysadmin/programming work!
NOTE on Broadcast: tonight we wil be bringing you some of the stories we would have covered last week. The rumor that we were forced off the air because of our announcement of the formation of GeekPac is 100% not true, but happened because of loosing one of our major network connections, and so we were unable to broadcast.
In Segment One – Hot News: We will be covering the hot Linux news of the last few weeks. In particular we will talk about the best of this years April 1st Internet Hoax’s. There were lots this year.
In Segment Two- Introducing The Open Technology Consortium (GeekPAC) or A more aggressive step at securing our future.
Tonight we ask the listeners indulge us a bit as we introduce our New Political Action Committee The Open Technology Consortium. We will have a URL available for users to review our initial Position Statement by ShowTime. The need for such a PAC should be obvious.
It has become apparent. Regardless of the efforts the founding members of the PAC have attempted to use to influence the outcome of political events that impact the mixed communities of; the Open Source development community, the Internet and ISP communities, the Linux community and the “non-Microsoft centric” portion of the general IT community; that those efforts have failed.
It is now time to take a more aggressive, attack direct to the seat of power in Washington DC. The creation of this PAC is to effect a sense of UNITY between several technology communities, and allow a common reference to carry a diverse message.
Please join us on the show, and check our IRC Chat(irc.thelinuxshow.com
#linuxshow).
Remember tune in at 6pm pt, 7pm mt, 8pm ct, and 9pm et.
Catch the Linux show at
www.thelinuxshow.com
Category:
Attorneys for Elcomsoft asked U.S. District Court Judge Ronald Whyte to dismiss U.S. v. Elcomsoft, the case that began last July with the arrest of the Russian programmer Dmitri Sklyarov. The attorneys claim the company’s software enables “fair use” rights of copyrighted materials — rights that the Constitution protects.”
Many programmers don’t know what to write in code documentation, and the lack of documentation remains a frequent complaint about Open Source or Free Software programs. Common advice is “write what you’d want to see if you were reading the code,” but that’s vague and not entirely helpful. Programmers need specifics: clear guidelines, in categories and with reasons they can understand.
A mnemonic is also useful. I’m going to use the “how, when, where and why; what, which and who?” list of question starters.
What does it do?
This is the most important question. What does the program do? If I’m trying to fix a bug report that says “it doesn’t foo the bar,” I need to know if the bar is supposed to be fooed.
Write at least a sentence for each function, a paragraph or more for each module or group of functions, and at least a paragraph for the program itself. In these, explain what the code is supposed to do.
Add a comment after every few lines of code stating what those lines are intended to do, put these in every time you move to a new step of the algorithm.
How does it work
This is only slightly less important than “what does it do?” Admittedly, it’s often possible to answer this one by reading the code — but only if the code isn’t buggy.
If you have a loop counting from 1 to 20, I can’t tell if you’re accidentally or deliberately ignoring element zero. The only way I can know for sure is if you commented the code.
Any code where you can expect an error should have a comment stating your intention. I suggest commenting places where an off-by-one error is possible, anywhere that uses pointers; and anywhere that you have complicated logic, regular expressions, or elegant code that another person might not understand.
Why was it written this way?
Why a stack, not a list? Why in C not in Python? Why repeat-until not while? Good coding, like good gaming, is a series of interesting choices.
Record your choices, and record the reasons for them. Later maintainers (or you!) can then make informed decisions about updating and modifying the code. Circumstances change, and people forget why decisions were made the way they were. The only certain way to remember your reasons is to document them.
Also record bugfixes. Later on, someone will (not might!) be tempted to pull out an apparently useless bit of code that you put in to prevent baz problems in quux machines. And it took you a week to get it right.
“Why this way” comments are essential anywhere you choose to break programming guidelines, lest someone try to “fix” the code to fit the guideline. Besides, you might teach someone something.
Which part does what?
Back to our fooed bar. We have determined that fooing is, in fact, a feature of our program, and that the bug reporter is correct and fooing is failing. How do we fix it? Where do we find the foo module?
The most effective way from the maintainer’s point of view is to have some sort of document with the source code which describes the overall structure of the code and explains which code modules support which user-view features.
This doesn’t have to be a long document, and can be a simple list like:
Use the same terminology in the features list as the users see, and include at least the main module for that feature in the code list.
Where do I find each part?
You’ve been thorough documenting your code, and carefully written an index of features and modules. Your maintainer knows he’s after foo.c. So where is it?
Include your installation guide, your “make install,” or some similar guide in your technical document. Include the location of your makefile — once the maintainer has fixed your code, she will need to build it!
If your feature index lists functions rather than files, you will need to list which file each function is in. You can list the functions as “foo() in foo.c” in the feature index.
Who wrote it?
Always add this. You never know when you’ll get a call from a headhunter offering you a lucrative contract because of a piece of code they saw. Or for more mundane reasons — someone might need to ask you about the code.
When was it written?
Add this, too. It might be useful to the headhunter — and it also gives a guideline for what sort of machine you wrote it for. And it may give a clue as to why you put in that apparently useless delay loop.
Final words
This is only one approach to documentation — most professional technical writers use much more structured and detailed approaches.
If you clearly answer each of these questions, the people who maintain your code will be much, much happier. And technical writers will be able to go through your code for their material, rather than making you explain it all.
Example program
/*
* greet.cc
*
* A 'Hello World' program written to demonstrate code commenting.
*
* Written by Jenn Vesperman
* March 2002
*/
/*
* 'Hello World' was chosen because almost everyone is familiar with it
* in some form or other, so the reader can almost ignore the code
* and concentrate on the commenting.
*
* C++ is chosen partly because it has two styles of comment. Where a language
* offers two comment styles, one can be used for extensive blocks of comment
* like this, for function and program descriptions, and for important
* 'pay attention to this' comments.
* This lets the other style be used for small, embedded comments that are
* used simply to clarify code.
*/
/*
* This program, having only one function, is too small for supplementary
* documentation. It should just compile and run.
* Compile with: g++ -ogreet greet.cc
*/
#include <iostream>
#include <cstring>
#include <string>
/*
* This function finds out who to greet, greets them, and exits if
* the input is the string "quit".
*/
int main()
{
std::string name;
start: // label to use with goto
// Finding out who to greet
std::cout << "Enter a name (one word only), or 'quit' to exit" << std::endl;
std::cout << "> "; // prompt
/*
* Warning: While buffer overflow isn't a problem here, there's
* not actually any protection against, say, getting a gigabyte of
* input with no whitespace in sight. That alone could DoS
* a machine.
*/
std::cin >> name;
/*
* strcmp returns 0 (false) if the two strings are the same.
* Therefore we use a comparison with 0, rather than simply
* using 'if !strcmp'.
* We're using strcmp() for a reason, here: As an example.
* As such, we're making a point of mentioning the choice, for those readers
* who are wondering 'why?'
*/
// is it quit? If not, greet then return to start
if (!(std::strcmp(name.c_str(),"quit")==0)) {
std::cout << "Hello " << name << std::endl;
/*
* We use the 'goto' construct rather than a while or do-while
* because we need to demonstrate commenting when we break the
* rules. There's no other reason for it.
*/
goto start;
// if it is quit, exit with the return value 'true'.
} else {
return 1;
}
// Should never get here. Return false if we do.
return 0;
}
Jenn Vesperman is an Open Source coder and coordinator of Linuxchix.
Category: