Tag Archives: tech

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.

Server down

Today, once again, my WRT54G just quit working for most of the day. No apparent reason. Worked fine on restart. So my email (among other things) was inaccessible all day long.

I know, I really need to obtain and install one of the many replacement OSes for this router. I just haven’t had the time to install it and test it. Maybe next weekend. Certainly not this weekend.

IRC Sabatical

This evening, when I *really* needed to get some writing done, I instead spent the entire evening helping some folks on #apache. Now, the time I spend on #apache, I consider to be one of my important contributions to the Apache HTTPd community, and I don’t grudge anyone that time. But I appear to have trouble tearing myself away when I actually need to get some work done.

Additionally, when I start losing patience with folks for their questions, it’s probably time for me to take a little time off. It doesn’t do anyone any good to be the one yelling at them to RTFM.

So, I’ll be taking a week or two off from #apache. I’ll likely be on some of the other channels I frequent, although that will likely be a little less frequent, too, since I tend to wind up doing Apache (and, particularly in the last few months, mod_rewrite) support on whatever channel I’m on. Granted, it gives me good article ideas, but then I don’t get my real work done.

Wooga

After listening to one too many debates on the relative merits of having, or not having the “www” prefix to all hostnames, I’ve decided that, henceforth, I will refer to my website as wooga.drbacchus.com. You are encouraged to use this new nomenclature, and update all of your bookmarks accordingly. Soon, I’ll start using mod_rewrite to force this usage.

Thank you for your attention.

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.

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.

Digital natives

There were many memorable things about the conference I just attended. If I had to pick just one, it would be the “Aha!” moment when Wednesday’s keynote speaker referenced Marc Prensky’s paper about digital immigrants and digital natives. To grossly oversimplify, he equates the new generation – perhaps those of college age and younger – to native speakers, while the rest of us are immigrants – in the digital world. (See also Part II.)

Those that are immigrants “speak with an accent”, consisting of things like the “Did you get my email” phone call, or even printing out email messages and responding to them in writing before typing the response back. (Interestingly, when our of our colleagues emailed us the URL for this document, one of us immediately loaded it on his palm, while another printed it out. I’ll leave it to your imagination who’s who.)

The natives, on the other hand, are going to spend their entire lives wondering why the rest of us are so stupid.

My daughter goes to Google when she has a question about something. The notion of going to the library to do research has never crossed her mind, and likely never will. The library is for story books. When she wants to find out what the weather will be like, she asks me to look for the weather on the computer, not on the TV. And she is as comfortable with a mouse as with a pencil.

Now, most of my readers consider themselves natives, I’m sure. But most of you remember when you didn’t have a computer. You remember your first computer, and it was probably a Vic20 or a TRS80 or perhaps an Apple IIe. In the same way that our parents remember not having televisions. However, I think that this is a somewhat arbitrary border-line. Those of us who were aware of the internet, and certainly the WWW, from the very first days, probably have a headstart over many of our colleagues. But certainly many people my age find websites perplexing, attend classes on how to use Google, and print out their email messages.

I’ve found myself using this terminology since that keynote, when thinking about the ways in which I need to explain certain things to certain people, and the frustration I get when they don’t grasp why it matters. Of course it’s obvious to me, but it’s just as important to grasp why it’s not obvious to them.

Self-writing code in PHP?

I’ve been writing a lot of php lately, and mostly I’ve been struck by how much it looks like Perl, despite the average php-fan’s assertions to the contrary. Granted, this likely has a lot to do with who’s writing it, rather than being intrinsic to the language itself, but, still, it looks and feels an awful lot like Perl.

Which makes it all the more irritating when I try to do something that I figure it ought to be able to do, and it flatly refuses to do it.

Today, for example, I tried to persuade it to auto-generate some code for me, so that I wouldn’t have to.

The scenario is that I have N database tables, each with MN fields. I’m writing a class to encapsulate each of the N tables, and, for each of those, I’d then have to write the MN accessor methods. That’s clearly unacceptable, so after the first two or three, I attempted to automate the process. What I came up with was something like the following. In the table class, I might have:

foreach ($fields as $field) {
    gen_function($class, $field);
}

Then, gen_function will be in some parent class, and will look something like:

function gen_function($class,$field) {
    eval("
      function $class::$field() {
        $args = func_get_args();
        return getset($this, '$field', $args);
      }
      ");
}

Now, that doesn’t work, so don’t expect it to. But there’s got to be a way to do that, right? Oh, and function getset exists and works, so just pretend it does what you expect it to. That’s neither here nor there for the purpose of this conversation.

I asked on #php how (or if) one might go about creating a function in someone else’s namespace, and was met by a collective blank stare, so either I’m not asking the right question, or I’m using Perl-specific terms in my question.

I know that some of my readers are php wizards, so perhaps one or more of you can shed some light on the right way to do what I’m trying to do. Or perhaps tell me that PHP simple forbids this kind of monkeying around with namespaces. Or perhaps … dunno. Is there another way to get around this? The purpose of computers is to do things for me so that I don’t have to. Writing the same 4 lines of code repeatedly is a *bad* thing.

Intertwingly problems

Today has been enormously frustrating, fighting a laundry list of intertwingled, although sort of unrelated, problems. The goal, this morning, was to import some stuff into svn, and then get a checkout of it on a Windows server. Sounds simple, right?

Tortoise SVN would not install, due to a missing/outdated file on the Windows machine. So I ran Windows Update. It hung, consuming 100% of the CPU, for the entire morning. I’ve seen these updates take a long time, so I just left it. When I came back after lunch, and it was still running, I killed it, and tried to take another approach.

Plan B – Mount the drive via samba over to the Linux machine on which svn is hosted, and perform the svn checkout “locally” to that mounted drive. This should work just fine, right? Well, I kept getting Input/Output errors, dropped connections. Had to delete files, run svn cleanup, and then try to update again. This went on until about 5:30, when I finally opened a ssh tunnel home, so that I could come home and connect back out.

I got home, but when I connected back out, everything was painfully sluggish, and, eventually, all the connections locked up, and I could not open a new shell. I had almost decided to go back to the office, when I got a shell, and discovered that the load was at 24. Oy.

It seems, after much poking about, that I’m tickling a known, but unresolved, bug in Samba, discussed here, as well as possibly here, among other places. So, for once, it’s actually not Window’s fault at all. Well, not directly, at least. If they didn’t have such a broken network file system in the first place, this would likely not be an issue at all.

The symptoms also seemed to include, at least once, smbiod consuming all the CPU, as well as a huge amount of RAM. But that didn’t happen again, so that could have been a fluke.

iCal and ApacheCon

After much pain and suffering, I managed to wrench an iCalendar format out of the ApacheCon schedule database. Given that I haven’t touched iCalendar format in about 4 years, I’m actually quite pleased that I was able to get this to work.

So, if you have iCal, or any other calendaring application that understands the iCalendar format, you can subscribe to the ApacheCon schedule at http://apachecon.com/2005/EU/html/sessions-ical.php

Of course, if you just load that link in a browser, it will look like garbage, and that’s completely expected.

I’m also not entirely sure about the timezone stuff. Timezones are so irritating. Can I produce iCalendar in a timezone-neutral manner? The events in this calendar are timezone Europe/Berlin, and when I sync them with my Palm, it shows up with the correct offset. But when I arrive in Germany and change my timezone setting, will it display them appropriately? Experimentation suggests not. I really hate timezones.

If I just have it output US/Eastern as the timezone, everything works fine. For me. I expect it would be messed up for everyone else.

————————-

Ok, upon further investigation, it appears that I can make the events timezone-agnostic, so that they work for everyone. So it should be all good now.

I really hate timezones.