Opinion

What About Free Documentation?

Introduction

There’s a lot of free or open source software on the net, and much been written about both that software and the process that drives it. Eric Raymond, of course, is currently the main anthropologist although Steven Levy beat him to it and there are many others.

There is also a significant amount of free documentation. One only needs to take a look at the GNU web site (their definition of a free operating system includes free documentation) or the Linux Documentation Project to see that. However, there doesn’t seem to have been a “Cathedral and the Bazaar” for free documentation, or even anything similar.

That’s kind of what I want to do here, but I’m not going to go into as much detail. Instead, I’m going to write about my own experience writing free documentation (my Oracle 8i Installation Howto), the trial and tribulations, the ups and downs, the good times and the bad… You get the idea.

Starting off

I guess the first thing to note is that I didn’t write the HOWTO to ‘scratch an itch’ — I already knew how to install Oracle! Instead, I noticed that many people were having difficulties and that I was spending quite some time replying to the same questions on newsgroups and Oracle Technet. You could say that I wrote the document in order to be just as helpful but without being quite so intensive on my time! (So my itch could have been to save time.)

Another motivator was ‘to put something back into the community.’ Sounds a little pretentious, but it’s true. I’ve been using Linux since 1994 and, although an able developer, have never contributed any code to any free software. This was my chance! I suppose I naively thought that writing English would also take less time than C. As we’ll see later, that didn’t turn out to be the case.

I think that this is an important difference between free software and free documentation. No-one will ever write free documentation to “scratch an itch” (as Eric Raymond so eloquently put it). This takes away, quite possibly, the greatest incentive to create something and may explain why, generally speaking, text is very much a second class citizen to code.

Release early; release often

The first decision I really needed to make was tools to use. My first thought was to add a few new pages to the web site that you’re currently reading. And then I got lazy. I decided to base my new work on the then current Oracle HOWTO, which meant that I had to get to grips with SGML and the SGML-Tools programs. At this point I wasn’t thinking in terms of getting it into the Linux Documentation Project, I just wanted to get a head-start. Once I’d actually started, it didn’t take me long to figure out that the structure of the old document didn’t match what I needed and, more or less, started again from scratch. I did, however, keep the same tools.

Having just read the Cathedral and the Bazaar, I consciously decided to issue my document before it was complete. I quickly wrote the introduction, prerequisites and installation sections and added a number of place-holders for the remaining sections. I then announced it in a message to Oracle Technet and a couple of newgroups.

Very quickly I got some excellent feedback. People were asking for clarifications and new questions, and others were pointing out factual errors. As with software, I quickly added these fixes and thanked the contributers both by email and in the document itself.

I was very pleased that this approach worked. Normally I would have ‘finished’ my work before making any issue, but by releasing early I was able to help more people early on and elicit — I’m guessing here — more useful comments. (I figure that’s true because I think I’d be less inclined to contribute to a finished document than a work-in-progress.)

Maintenance

Around version 1.5, a couple of weeks after my initial release, it was more-or-less complete. All sections were filled in and I managed to complete a successful installation just by following the steps I’d written about.

The first issue was the people didn’t follow my advice — how dare they! Oracle is a big and complicated application and, even on Solaris, you just don’t change things unless you have to and you always use a ‘certified’ operating system. This is an alien mind-set to many Linux developers, who tend to thing “newer is better” and is not helped by all the weird and wonderful devices that you can connect to an Intel-based PC.

The first questions I received that deliberately weren’t answered in the HOWTO were problems with different distributions. People were trying to get Oracle running on just about anything with a Linux kernel!

I didn’t fancy wiping my PC clean and attempting the install with as many different distributions as I could find, I just didn’t have the time. Fortunately, the same community on the Internet that helped me complete my first version added to my knowledge base.

I started to add more and more detail to the HOWTO. If you’re using RH6 do this, with Debian do that… It seriously affected the “flow” of the document for everyone. Given my Oracle (conservative) background, this is just not a problem I originally considered.

When Oracle released 8.1.6 I made the decision that the HOWTO was for RH6 and Oracle 8i R1. It would make the occasional nod to later releases of both the database and the distribution, but fundamentally the focus would be on one version of Oracle and one version of Linux.

As a kind of half-way-house, I started to add extra pages to my website detailing some of the idiosyncrasies of different Linux distributions or newer versions of Oracle. I’m still not completely happy with this approach but I’ve not heard of a better solution yet.

Feedback

Having “completed” my document, what keeps me editing? If I’m writing software, my motivation is adding cool new features. Or maybe adding new stuff for other people and waiting for their praise?

As I mentioned earlier, things are very different for documentation writers.

I’ve got an awful lot of mail about Oracle and Linux since late 1999 when I first published the HOWTO. The email I get seems to have gone through a number of phases. When I first issued the document, I got an almost fifty-fifty split between “thank yous” and suggestions for improvement. Almost all was positive, constructive and friendly.

Without it I would almost certainly have stopped writing. At this point I suppose my motivation was to increase the ratio of thanks to suggestions. I turned a stream of emails into a challenge!

As the HOWTO started to get into wide circulation, the number of helpful suggestions started to drop and the number of questions started to rise dramatically. Some I saw as suggestions as I didn’t cover those details, but most were just from people who clearly couldn’t be bothered to read any further than the front page and my email address.

I can’t count the number of messages I’ve received saying “it didn’t work, what should I do?” (in as many words). How should I reply to that without being rude?! I’ve also received emails from people giving me their “root” password and other confidential details.

The next stage was when Oracle released a newer version and RedHat decided to go with a new version of GLIBC for version 7 of their distribution.

By this point, my motivation was mainly trying to reduce the number of messages I was receiving. Sure, I felt like being rude but I rarely was. I tried to answer all the most common questions in the document, but this point was definitely the low point. Although the updates were helpful, I was doing them for the “wrong” reasons, and the number of messages saying “thanks” had dropped to virtually zero.

More recently I’m only getting the occasional question. It’s difficult to know whether that’s because my HOWTO covers just about everything it needs to or because I’m just not promoting it as much as I used to or because the cutting edge in Oracle is now with 9i. Or maybe I was rude and people are too scared to talk to me..?

In conclusion…

If my original intention was to save time, it failed miserably. I’ve spend even more time replying to emails and maintaining the document than I would have done occasionally adding comments to discussion groups.

Towards the end of this piece I’m sounding very negative, but that’s a bad way to finish as generally speaking it has been very enjoyable. Getting a Linux distribution with your work on is quite a buzz and it’s always nice to get a friendly message or offers of free CDs and books from strangers.

Opinion

Oracle Builtin Packages

Introduction
Steven Feuerstein’s ‘Oracle PL/SQL Programming‘ book has, over the last couple of years, become my bible on the subject of writing sizable Oracle PL/SQL programs. As I said in my review, it’s useful because it covers just about everything, including the things that don’t work.

So if that book covers just about everything, why would anyone want to buy ‘Oracle Builtin Packages’?

Content

In fact, as the first chapter of the book explains, this entire book was origianlly chapter 15 of ‘PL/SQL Programming’ but Oracle complicated things by adding more to the PL/SQL programming language (all the pseudo-object oriented stuff in version 8 ) and many more new or enhanced packages. The result: either a single two thousand page monster, or two more reasonably sized tomes.

But like the first book, this is still a bit of a monster in its own right. It stands at 931 pages and there’s very little padding; if only all technical books had such a high signal-to-noise ratio!

It seems rather pointless to go into detail on the content of all the different sections…

The two chapters that I’ve used the most are those on DBMS_FILE, which allows you to manipulate operating system files, and DBMS_SQL. Just about everything I know about these modules I learned from this book. When I was originally writing the code, ‘Oracle Builtin Packages’ was by my side, open at the relevant page. When colleagues mistakenly thought I knew what I was talking about, this book was open beneath my desk giving me superiour bluffing ability.

The main critisism that I can think of is that some of the material is getting rather out of date. The DBMS_SQL package is no longer as necesary as it used to be — Oracle 8i introduced some new syntax to the PL/SQL language that largely replaces it.

Conclusion

I’ll be brutal: in marked contrast to Feuerstein’s first book, if you regularly write PL/SQL code you can get by without reading this book.

But you will be more productive if you get it. You won’t be spending days writing code to do things that Oracle have kindly supplied a routine to do and you won’t give up on PL/SQL and write a program in Pro*C because you don’t realise, for example, that you can manipulate files.

No, this book is less vital than ‘Oracle PL/SQL Programming’ but it is still a thorough, well organised and useful book. It’ll quickly pay for itself many times over, and that’s a very high recommendation.

The facts

Author: Steven Feuerstein, Charles Dye, John Beresniewicz

Cost: US$46.95

ISBN: 1-56592-375-8

Opinion

Accidental Empires: How the boys in Silicon Valley…

Introduction

This is neither a new book nor a new purchase for me, so why am I reviewing it? Bottom line: it’s a book that I’ve enjoyed a lot over the years and one that I feel the need to recommend to as many people as possible.

What’s in it?

The obvious format for a book on the personal computer industry would be chronological, but as he points out early on in the book, things just aren’t that simple. Instead he uses what, on paper, might look to be a random arrangment of anecdotes, jumping from Apple to Xerox Parc to Microsoft and IBM in the matter of a few pages. But that’s just the nature of the beast.

What’s good

Cringelys writing is easy and engaging to read. It would be very tempting to just sit down and read the entire book from beginning to end. It’s friendly, chatty and full of interesting little anecdotes about all the main characters, from Bill Gates to Steve Jobs.

He freely admits that he’s not been a true historian. He’s missed out some arguably important stuff, but it would take a long, dull book to get all that information in. The charm of Accidental Empires is the fact that it’s easy to read.

Conclusion

When I do reviews, I normally have a section on the bad stuff. I don’t have one here. That’s not because the book is flawless, but because it achieves perfectly what it set out to do.

If you’re at all interested in how the PC industry came to be, this is the book for you.

The facts

Author: Robert X. Cringely

Cost: ?6.99

ISBN: 0887308554

The Penguin Says

WWWThreads 2.7

2 Comments

Introduction

While Linux cannot currently compete with Windows NT on the desktop (for a number of reasons that I’m not going to get into here), it has already made inroads into the server market. Many large companies use it as the OS for their web server (like this machine), and many more use it on their intranet for sharing files and hosting web pages.

WWWThreads capitalizes on this framework, adding CGI programs to generate threaded discussion groups, just like Usenet but with a more appealing web front-end.

Installation

Installation should be fairly simple. All that’s involved is copying the files into a CGI directory on your server, alter a few parameters in one of the files and type ‘./wwwthread_startup.cgi'.

Unfortunately it’s not quite that simple. The blame has to lie with the documentation which could best be described as minimal — a single 85 line README. The description of some of the variables that need changing is rather poor. I managed to change them to the wrong thing and only found out when I brought WWWThreads up in Netscape.

Of course, that’s when I finally managed to get it working at all! Apache‘s first reaction was to complain about a ‘premature end of script.’ I’ve done a small amount of CGI programming, and realized that this meant that the web server wasn’t receiving a header describing the format of the data.

But why? Isn’t this supposed to be a finished program? I shouldn’t be getting run-time errors and the like? Then I remembered, my email address has an ‘@’ in it. ‘@’ is Perl‘s way of saying ‘here’s an array’ and needs to be quoted to mean ‘at.’ This edited, the start screen appeared.

You could argue that it is a server side program, designed for knowledgeable people, and that I did manage to get it working in the end. However, all that’s needed is a little extra effort on the documentation and, maybe, a Makefile. Something like an Installation FAQ would be invaluable.

From a user…

Looking at the system from a web browser, things look much better.

WWWThreads has a very neat front screen. The colours have been well chosen; they look smart and well designed, but are very readable. In the top left is a logo, the top right has a menu. Below this is a list of the discussion groups that the administrator has set up. Clicking the title of the group brings up a list of the threads in that group. Clicking a thread bring up a list of posts. Clicking a post brings up that post. All very simple, standard stuff.

If you want to create a new post or reply to one that is already there, you will need to create a user for yourself. Here you’re invited to enter a user name, password, name, email, home page, occupation and hobbies. The first four are mandatory, the others optional. Clicking ‘Submit’ results in a screen (hopefully) saying that your details were added successfully. There are no other links or details on this screen, and you are forced to wait before your browser loads a new page. Annoying.

Replying to, or adding, a new post is similar. Fill in a few details, click submit and wait. There should at least be a link on this page to act as a short-cut for the impatient.

However, generally it is all well laid out, attractive and intuitive — there’s not much to write about.

From an administrator…

The administrative tools are good, and are web based just like the rest of the system. It allows the admin to change their password, add new discussion groups (‘Boards’), edit or delete posts, change details about the groups, archive a board, delete a board and edit users.

Most of these options are obvious, the one that might not be is the ‘archive’ option. This allows you to, in the words of the author, ‘…move all of the current posts on a board to an archive.’ This is a really good idea, and is implemented well, but does not go as far as I’d like. Some way of selecting posts by date or author, or individual posts would be useful. As would a method a more intuitive method of deleting archives (it appears as another board at the moment).

All the tools are password protected, which allows remote administration — a useful feature.

But the main thing missing is overall configuration options. What it I don’t like the look of the pages that WWWThreads produces? What if you want to fit it into your ‘house’ style? What if you don’t want to ask for hobbies or an occupation when a user registers?

The software is distributed with the GPL licence, so of course you can edit the HTML generated. But there is not documentation and much of the look-and-feel is hidden away in the Perl scripts. Perhaps some kind of template HTML file could be used?

Conclusion

WWWThreads is an odd program.

In some ways it is excellent. The design of the pages are good; the way that it remembers which posts you’ve read and those which you haven’t is useful; the archiving option is excellent, in fact most of the web based admin screens are very well done.

But then again, the installation is needlessly difficult, you can’t easily change the way that it looks, it seems not to perform particularly well (I am running the client and server on the same machine, so this might not be a fair comment) and the documentation is poor.

WWWThreads would be an ideal program to place on an Intranet server to allow people in the office to communicate more effectively. However, it’s lack of configuration options would probably make it unsuitable for an external site.

The Penguin Says

Corel WordPerfect 8

Introduction

Linux is capable of many things. It is an incredibly fast and stable platform, able to sustain months, if not years, of uptime and has many world-class applications such as Oracle8 and Apache. What it doesn’t have much of are decent word processors. I find that, these days, the one of the few reasons that I boot up Windows is for Microsoft Word (the other reason is Worms 2).

So the day when WordPerfect, one of the few word-processors that can compete with Word feature for feature, arrives on Linux is a momentous one. However, just being there isn’t enough. Is it really on par with Word? And does it do justice to Linux?

First things first

Corel WordPerfect comes in three versions: Personal Edition, Standard Edition and Server Edition. I’m reviewing the Personal Edition, the one you can download from the Internet for free. The Standard Edition adds more fonts and clip-art and the Server Edition adds a character mode version and more administration tools.

Installation barely warrants a mention. It’s not a ‘standard’ Linux package such as RPM or DEB, but is very straight-forward nevertheless. It’s very Windows-like: click here, enter this information there. Easy. It’s not as confusing as StarOffice either – you install it as ‘root’!

Running it for the first time

X doesn’t make it easy to make a decent application. It imposes no standards on an applications look and feel, but does impose a relatively high memory overhead. I guess this makes it difficult for a company used to writing Windows applications.

Corel, like StarDivision, have chosen to make WordPerfect look and feel like their Windows version. This is going to annoy some Linux users, claiming that it’s not ‘UNIX’ enough, but I think it’s a good thing. It makes anyone used to a Windows word processor (i.e., almost everyone) instantly at home. No one is going to have a problem with the Office 97-like tool bar, nor the simple and logical menu structure.

Perhaps more of an issue for people coming from Windows or a Macintosh is what the application is capable of. Word processors on those machines can, just about, do everything from letters to fairly advanced desktop publishing. Most free Linux equivalents just can’t compete with that. LyX is great for long, structured documents (with certain caveats that I noted when I reviewed it last year), and many of the others look good, allowing import of multimedia clips, but are disappointing when you want to do any real work.

WordPerfect is more like a Windows word-processor in this respect.

Doing some real work

I thought a good test would be to write this review with WordPerfect. I suspect that documents of around a thousand words are not atypical and it would allow me to test out some of the nice new features, such as its Internet interoperability.

Unfortunately, half way though the review I found that there was very little to write about. This is not a criticism, in fact it should probably be taken as a compliment. In writing simple text, WordPerfect has all the tools you need exactly where you would expect them, doing exactly what you want. It has the basics, such as font and style selections, plus more recent innovations such as on-the-fly spelling- and grammar-checking. The latter is annoying and I usually switch it off, which is a useful feature that Microsoft Word doesn’t have!

So far, there is nothing that WordPerfect has that the Windows competition doesn’t already have. I guess it has two things. Firstly it has the ‘shadow cursor,’ something so obvious that I’m surprised that it’s not been done before. (People said that about the drag-and-drop cut-and-paste in Word for Windows 2.) If you switch it on, you can click anywhere on the screen and start typing. WP adds the necessary returns, tabs and spaces for you.

Secondly, it has what I can only describe as an on-the-fly thesaurus. It’s a drop-down list on the tool bar that gives a continuous list of alternatives to the word that you just typed. I’m not sure that it’s a great improvement over pressing Shift-F7 in Microsoft Word, but it’s there anyway.

Advanced stuff

Once I found that I could test more than a small amount of functionality while writing the review, I started playing round in other documents.

The first I opened was my CV, a Word 95 document complete with some of the dodgy advanced formatting that you can do there. The import was less than perfect, but was still quite impressive. It brought across all the text and most of the formatting, including most of the style information. Unsurprisingly it failed on the floating frames, but it did place the text at a suitable place in the document. Full marks for falling over gracefully. I was surprised that it didn’t manage to import the header and footer information, though.

I then tried to reapply the formatting that the import had managed to remove. Again, it gets boring to write about as it was so easy.

The second document I tried was rather longer, nearly seven thousand words. Again, conversion was impressive although imperfect. This time the main problem was the heading numbering, a fault that Word 97’s converter also has.

Having lost the table of contents, I tried to recreate it. I didn’t find this entirely straight-forward and never did get exactly what I was looking for. It looks like you have to define each paragraph that you need entering into the table of contents, rather like the way LyX insists. I much prefer the Word approach where it uses the list of styles to work out the document structure.

Not all good

It has to be said, there isn’t a lot wrong with WordPerfect 8.

The font handling – unique to WordPerfect – isn’t quite as good as that in Windows, but is probably better than that in most X applications, StarOffice included. Also, the version that’s free to download doesn’t have the on-line help. I can’t help but think that this is a very important thing to miss out.

The two worst things that I can think of are that the Microsoft Word filter doesn’t work with fast-saved documents (I’m not sure what MS has done with fast-saved documents, but no software other than Word itself seems to be able to deal with it!) – annoying as most of my Word documents are fast-saved!

And the finally, a question mark hangs over its stability. I had a couple of (unreproducable) crashes while wring this. However, it should be noted that WordPerfect managed to reinstate a recent backup each time meaning that I only lost a sentence or two.

Conclusion

This is exactly what we need. WordPerfect is a superb application, just as good as its Windows counterpart, but running under Linux. Due to its less-than-one-hundred-percent compatibility with Microsoft Word, I can’t guarantee to use it always (my work uses Word) but it is going to stay on my hard-disk.

The Penguin Says

WINE 980614

Introduction

This is the second time in as many reviews that I’ve started like this: I don’t want this to be the start of a trend. I did say in my ‘policy’ document that I didn’t want to look at very early releases of software and I stand by that.

However, sometimes you see something and, even though it doesn’t work fully, it show such great promise that you need to shout about it. WINE is such a piece of software.

What is it?

Wine allows you to run Windows applications on x86 Unix machines, Linux in this case. It should work on almost any PC based UNIX like NetBSD, UnixWare, etc. and it’s supposed to run 16- and 32-bit Windows applications, although the former are much better represented at the moment. There are some that will never work properly (the FAQ says something about VxD’s which I don’t understand).

At least, that’s what it will do. At the moment it is a developers release, not even stable enough to be called beta software. However, I’m not here to bash Wine because it’s in its early stages of development. I’m here to express how shocked I am that it’s so good!

Installation

I’ve tried a number of times in the past to make Wine, and they’ve all ended in tears. I rake around my hard disk trying to find enough space — around 50 Mb — spend ages while it compiles and then when I run it I find that there’s been a segmentation fault in 32-bit code. I don’t know what that means, only that it’s not mentioned in the FAQ and that I can’t run anything, not even Notepad.

Then the other day I decided to make one last attempt and, rather than get the source code, I got a precompiled RPM. It didn’t work at first. I had to customize it, changing the configuration file to match where my Windows 95 partition is, but nothing too arduous (or unexpected).

So, I fired it up trying to run calc.exe. I wasn’t hopeful, and the fact that it was taking 100% of CPU and seeming to get nowhere fast didn’t help. I left it chugging away and made some coffee and toast.

Success!

When I returned from the kitchen, the Windows Calculator was sat proud in the middle of my Trinitron. My jaw dropped, and the dog nearly got my toast.

Okay, the display wasn’t completely right. The text in the title bar is far too small, the buttons are in the extreme top left and right rather than in the middle of the bar, and the font on the menu bar is proportionally spaced meaning that it looks rather odd, but I suspect that this is all configurable — you can certainly tell Wine to use your window manager rather than X directly.

But it worked. I could do sums; I could change between normal and scientific mode; I could get the About box. I was stunned.

Moving onto Notepad, I found that the same was true: it worked. I trundled though a few other applets that Windows 95 comes with, many of which, at least partially, worked.

Getting arrogant

Having got the tiny programs working, I started hunting around my hard disk for new challenges. Why start small and build up, I though. ‘wine "`pwd`/winword.exe"‘ I typed. That’ll show it.

I started on my toast, figuring that it’d take a while before it gave up.

But it didn’t give up. After a worrying amount of disk activity, the Word 95 splash screen appeared. As did screens and screens full of errors in the console window. Despite the errors, Wine and Word battled on, eventually displaying the normal Word screen, tool bars, menus and all. Again, the fonts weren’t quite right and the toolbar was far too dark, but there it was. Linux running Microsoft Word 95.

Tentatively I entered some text. This worked fine — even the font rendering was spot on — until I mistyped something. Word underlined the suspect characters with a wavy red line and then crashed.

Next time I managed to get the About box (fairly simple, but with a big bitmap and a sound clip) to display, followed by the Options dialog (big with lots of tabs). A few others also worked without problem. The open dialog, however, causes Wine to exit. I guess this is because Microsoft didn’t use their own standard libraries for the task! (Let’s blame Microsoft.)

Excel works roughly as well as Word. It starts without any problems, you can enter data in the cells and auto-sum works. Many of the dialogs appear, full and correct, but save crashes the system. PowerPoint vanished shortly after completing loading and Access didn’t even get as far as the splash screen.

I was very surprised at the success that I’d had up to this point. Okay, nothing useful actually worked, but I was looking from more of a technical point of view. I did, however, find a program that worked incredibly well, something much larger than clac.exe or Notepad. The program? Maxis SimCity for Windows 1.1. (Saying that it’s useful is stretching the point, but I digress.) I play tested SimCity quite thoroughly and found that, although small parts of the screen occasionally became corrupted, everything worked. Since games are usually associated with some of the worst coding and low-level hacking around this was good. (I’m not sure whether the credit should go to the Wine team or Maxis!)

Overall

I’ll not mess around: Wine is not ready for the prime time yet and is still some way off. This is not news, the developers say this too.

What is news is that it is an incredible piece of software. A non technical user might not see this (unless they want to play SimCity), but anyone who has written a non-trivial program can see what an incredible achievement Wine is.

Photography, opinions and other random ramblings by Stephen Darlington