Tag Archives: books

Free docs, conflicts of interest

This weekend, I spent about 4 hours trying to get a RewriteRule working. I did that because it’s somewhat cryptic, in the docs, why it’s so hard to do what I wanted to do. Or, more specifically, why it is impossible, and what the workaround is. Granted, the information is there, if you know that’s what you’re looking for.

I did this as part of the book that I’m writing. Now, of course, I want to add the example to the documentation.

I’ve been having this internal debate for quite some time. When I enhance (or someone else enhances) the Apache documentation, this has a direct negative impact on my ability to sell books and/or training classes. When writing Apache Administrators Handbook, I spent almost as much time working on the docs as I did working on the book itself. As a consequence, there was rather less need to buy the book. It also led to at least one reviewer saying that the book read like it was copied from the docs. And, in a very real way, it was. Or the other way around, depending on your perspective.

So I have to wonder whether it really affects book sales when we make the docs so good. I have to assume that it does, I suppose. I’ve more than once joked that we should make the docs worse, so that I can make more money. I suppose there’s a reason that books on Java stuff are available in such numbers. 😉 From the docs for some Java software projects (I’ll avoid naming any names, since I don’t feel like getting flamed just now) it’s relatively hard to figure out what the software even does, let alone how to use it.

Ta ta for now

Paul Winchell has died at the age of 82. Winchell was the voice of Tigger, although before that gig he was already a very successful ventriliquist on radio and TV. I remember hearing somewhere that when he was cast as Tigger, folks said it wouldn’t work, because he would always be associated with Jerry Mahoney (his dummy). Now, decades later, whenever you hear his voice, you immediately know it’s Tigger.

Tigger has been my favorite for as long as I can remember. Thanks, Paul. As you said once, Tiggers *don’t* like saying goodbye. Ta ta for now, good friend.

RewriteMap

This evening I finished writing Chapter 5, which is about RewriteMap. In the process, I puzzled over some things in the docs, fixed a small number of them, and planned to fix a larger number of them. Hopefully I’ll spend the two days of the Hackathon at ApacheCon working 0n that.

Anyways, for some time, I’ve admired the fact that you can go to a URL like http://php.net/echo and get the docs for the echo command. It appears simple enough, but actually involves some work to make it happen like that. Kudos to them, however, it’s being done.

I want the same thing for the Apache docs, and, of course, I wanted to accomplish it with features that are built into the Apache web server product. Part of that is just hubris, but there’s slightly more to it than that. In particular, I’d like to have the feature available to anyone who’s running a mirror of the website, without their having to install and configure anything extra.

Well, I’m almost there, using mod_rewrite and RewriteMap, with dbm map files. There’s a few steps here. Eventually, one hopes, we’ll have this enabled on httpd.apache,org, but, for now, it’s at fajita.drbacchus.com/DirectiveGoesHere

So, for example, if you want the docs for RewriteMap, you go to fajita.drbacchus.com/RewriteMap.

Strangely, the bit that caused me the most work was getting it to be case insensitive. Turns out that the first thing I tried was correct, but that I had another directive that was overriding it, and hiding the fact that it was correct. Bah.

For more details on exactly how it worked, buy my book and read chapter 5. 😉 (Seriously, though, I’ll write it up somewhere if anyone cares.)

Response to comments (Re: word processors and publishing)

This started as a response to comments to an earlier posting, but grew rather too long to be just a comment.

No. I can’t use Pages. It must be MS Word. It’s not about exporting to MS Word format. That’s not sufficient. You have to be able to use all of the MS Word templating and revision tracking stuff in order to work with most of these publishers. Their process is completely embedded in Word, and attempting to use a different word processor makes the process break. I’ve tried everything from Pages to OO.o to LaTeX and vim, and there are always small problems that break the process. (Yes, one kind publisher permitted me to write in LaTeX, and afterwards swore that they would never, ever, ever let another writer use LaTeX.)

Anyways, in defence of APress, I should mention that my frustration and ranting was almost immediately answered by a response from my editor telling me how to get around the problem that I was having, thus showing that I really should have just sent her a note when it started happening, rather than wasting 2 hours on it.

Regarding the Docbook comments — we wrote Apache Cookbook in Docbook, and that went ok until it got to the editing process, and they converted it to Word docs, and then sent us back revisions in Word, making it completely impossible to produce any kind of intelligible diff. Once again, the process lives in Word.

What strikes me as ironic is that all of my books have been about Open Source software, And one of these publishers has made their entire fortune on F/L/OSS.

At OSCon 2004, Tim O’Reilly asked me what part of working with O’Reilly had been the most negative aspect. I unhesitatingly answered that it was being forced to work with MS Word. He chuckled and said that he’d see what he could do about it. But I doubt that there’s much that can be done, because of how closely tied the entire editorial process is to particular features of Word – features that are sufficiently different in other software to make it incompatible with the process.

This is, of course, a topic that comes up with regularity whenever tech authors are complaining about their writing experiences. The tools are there to make the editor’s job easy, not the writer’s. Ideally, I’d like to just write plain text, with minimal markup or comments saying “this is example code” or “put wooga.gif here”, and then have a layout person do the actual page layout. Of course, that introduces more expense into the process, and tech books are already absurdly expensive.

Word processing

While I recognize that there are people who need word processors like Microsoft Word and its ilk, I really hate these tools, and wish daily for a writing tool that will just get out of my way and let me write. As I have mentioned, I am writing a book. And, like every other publisher, this one has their own MS Word Template File to which I must slavishly adhere. So, if I want something to appear in monospace black courier, like source code, I make it green times new roman to indicate that desire. Somehow, in the typesetting process, they then magically convert that to the wrong style so that it will look funny in the finished product.

At least, this has been my experience numerous times in the past.

Over the last 2 days, while I am way way behind schedule, but seeing a chance of catching up, I have spent far more time attempting to make things the right format/style/whatever than actually writing content. In fact, as I look at these meagre three paragraphs, I realize that I have written more in the last 2 minutes than in the 2 hours leading up to that. This is profoundly depressing.

I really truly don’t care one whit about page layout. That’s not my job. My job is to write. I think I’m pretty good at it. Design and layout, however, are not my forté. And I just don’t care. So, rather than spending 2 minutes writing a page of prose, I spend a hour trying to get one little phrase to show up as inline code, monospaced, and green, without turning the entire page to flashing blue text underlined with red squigglies.

I really hate MS Word. Can I please find a publisher that will just let me write in POD, or LaTeX, or plain text, or something at least remotely sensible? It seems not, since this is the third publisher I’ve worked with.

I’m *really* excited about this book. It’s going to be a great book. Unfortunately, the process is robbing me of most of the enjoyment. 🙁

Snowflakes in a matchbox

One of the great things about re-reading a well-loved book is that you discover things each time, depending on your frame of mind. I’m reading Dandelion Wine again, as I do almost every summer. This time, I discovered this little gem.

“Got a snowflake in a matchbox,” said Tom …

“Last February,” said Tom, and chuckled. “Held a matchbox up in a snowstorm, let one old snowflake fall in, ran inside the house, stashed it in the icebox!”

…

“Yes, sir,” mused Tom, picking grapes, “I’m the only guy in Illinois who’s got a snowflake in summer. Precious as diamonds by gosh. Tomorrow I’ll open it. Doug, you can look too.”

It’s perhaps the best metaphor for memories that I’ve ever encountered. My memories are snowflakes in matchboxes. When I go back for them, so often they’re not there, or they have melted a little.

Some folks, like Mrs. Bentley, hang on to those memories, and when they melt, they have nothing left. Others, like Colonel Freeleigh, share their snowflakes with everyone, and make the world a better place by doing so.

My snowflakes seem to surprise me in the middle of the summer. I don’t remember putting them in the ice box, and, some day, when I’m looking for something else, I come across them.

Written any good books lately?

I realized/discovered/was told yesterday that I need to write 8 chapters in the next 7 weeks. Two of those weeks, I’m travelling, so it’s really 8 chapters in 5 weeks. And this week is almost over, in terms of days that I will actually have time to work on this. So it’s more like 8 chapters in 4 weeks.

As Douglas Adams observed,

I love deadlines. I like the whooshing sound they make as they fly by.

DeliciWeb

Now that I spent an inordinate amount of time last night writing code, of course I find an existing app that does what I’m doing, only far far better. DeliciWeb allows you to export your Delicious Library to your website. Very cool.

My library.

Delicious library on your website, sort of

I’ve hacked together a few dozen lines of Perl that transform your Delicious Library XML file to HTML pages. It is by no means complete, but if you care, then it will give you a starting point. It uses XML::Simple, which has prerequisites of XML::SAX and XML::NameSpaceSupport.

Put this in “/Users/username/Library/Application Support/Delicious Library”, mkdir HTML, and then run it. It will generate files in that HTML directory, one called index.html, and then one per book.

Patches welcome. I’ll be doing more useful things with it when I have more time to hack on it. Apparently I just spent 2 hours on this. Sheesh.

delicious2www.pl

HJTI license. Will eventually have templates, so that I don’t have to listen to people complaining about how ugly my HTML is. It doesn’t handle the case where you don’t have cover images. And it currently only does books. No particular reason for that.

Example output

—————————————

Update: Version 1.4 does movies and music, orders the output by title, and has at least a nod at documentation.