Tag Archives: apache

mod_rewrite

After setting up Rewrite.drbacchus.com as a sandbox for the mod_rewrite documentation rewrite, I essentially did nothing with it for a few months.

This evening I started working on the section about the RewriteRule flags. They are all documented in the RewriteRule docs, but in the absense of examples, a few of them are slightly hard to understand. N, for example, is extremely hard for most people to grasp the first read through. And P really needs a bunch of examples.

So, hopefully this can develop into a little more than merely a disorganized wiki.

ApacheCon Europe 2005

The call for papers for ApacheCon Europe 2005 is still open, and we really need some good high-quality submissions before the March 4 deadline. If you’re waiting until the last minute, for some reason, please don’t. And if you think that maybe you don’t have much chance, well, go ahead and submit something. Perhaps the sparsity if submissions will work to your advantage! And, if you missed the announcement entirely, well, great, there’s still time. Get those submissions in!

Good students

There’s a certain frustration, ironically, that comes from having really good students. Most times when I teach my classes, there’s a certain percentage of the class who either aren’t particularly good students, or lack any background in command-line-computing, or simply don’t want to be there. Thus, my class outlines are built around the notion that I will spend a sizeable percentage of my time assisting them while everyone else waits. This time around, the whole class is composed of people who either have considerable Unix experience (in one case, at least a decade more than myself) or, while lacking the Unix experience, have sufficient passion to learn, to overcome that shortcoming.

Consequently, with one exception, every day this week has run short on material before it has run short on time. Subjects that traditionally have taken a hour, they absorb in a half hour, and are ready to move on to the next thing. Hands-on exercises like typing in a 10-line CGI program, which usually takes a half hour to get everyone working, are done in 15 minutes.

Nobody has complained, but it leaves me feeling like somehow I’m short-changing them. I try to throw in additional stuff and examples, but after so much of that, it becomes obvious that you’re just stalling and fluff-filling time. So that’s no good. So last night I completely gutted my class outline for today, and rewrote it. Hopefully it’s got more substance now.

Listen at me, complaining that I have good students. Sheesh. Anyways, it’s been a good week. I hope my students feel the same. I’m looking forward to the weekend, and having a day off, then I start the new job on Tuesday. Woohoo!

What’s the documentation for?

There are, it seems to me, two purposes to which documentation is put.

Most people consulting the documentation are attempting to fix something that’s broken, or otherwise get something to work. This is the “tell me how to do it” variety.

A smaller number of people consult documentation in order to gain a deeper understanding of how things work, and why. The motivation for this is varied, of course, but it’s a different goal than simply getting something working.

The former way of looking at docs is very short term, immediate, crisis. The latter is more long-term. Generally, if one reads the docs and understands how things work, and why, they tend to have fewer of the crisis situations in which they need to get something working.

There’s a documentation bug about the Order directive which is grounded in this very difference. The Order syntax is annoying and unintuitive, if you don’t understand how it works, and why. Most people don’t want, or need, to understand why. And, in this case, the “why” is not particularly simple. Folks just want to know how to get their allow and deny directives working. And the docs currently don’t really help them do that. At least, not right now. Hopefully they will in a few days.

My goal in documentation is generally to first address the “how do I fix it” question, because that’s the most frequent use of the docs. I don’t necessarily think that folks *should* have to understand the inner workings of the configuration directory-scope merging mechanism in order to keep the nasty spammer out of their content.

However, most of the technical documentation that I encounter is of the “how does it work” variety, and a great deal of it doesn’t even do a good job of that.

I’m just rambling, and observing. I don’t know what the solution is. There’s certainly a lot of “howto”‘s out there, and so many of them are either very specific to a particular scenario, or just plain wrong. These are a well-meaning approach to the problem, but often go astray.

Helpful translation

For those of you who don’t have a 6-year-old, you may like to know that “Do you want to sleep in” is 6-year-old code for “Get up, Daddy, now, now, now, now!”

The radio show last night was at 7pm, Left Coast time, which means that it started at 10pm Real World time. I was already exhausted, since I’ve been trying not to be sick all week, but it was kinda fun to do the show. The idea of an AM radio station having a show with intelligent discussion of Open Source software is very foreign to me. Anyways, it won’t happen here in Lexington for a while.

Hmm. Which gives me an idea. …

Anyways, the show was over at 10:30, and then Tina, our fearless producer from ApacheCon, who had been instrumental in setting this up, called me back, and we talked about ApacheCon-related things until nearly midnight.

The question as to whether I wanted to sleep in came at 6:30. And at 6:40, and 6:50 and 6:52 and 7:10 and 7:15 and 7:17. I’m a little slow, but I eventually got the point that “yes” was not really one of the acceptable answers to the question.

So I’m just draggin’ a little bit today, but at least I think that my cold/flu/lurgy/creeping-crud has gone away, which is an improvement.

Anyways, the radio show got me thinking about the purpose of documentation. I have long thought of a division in audience, but I think maybe it’s simpler than that. Documentation serves two distinct purposes. “Help me fix it” (or get it working) and “Help me understand it.” These things are not mutually exclusive, but they have different emphases.

So, more on this later. I need to go make an origami star box.

The Usual Suspects

I was just dropping off to sleep (hey, it’s been a long week, and I’ve got a case of the Creeping Crud) when Cliff called and, to make a longer story shorter, I’m going to be on The Usual Suspects in about an hour, talking about Apache, The Apache Cookbook, ApacheCon, and why the documentation team is just as important as the “real developers” in an Open Source project.

mod_watch

I decided to finally take a look at mod_watch, and, like so many add-on Apache modules, it was so easy to install and get useful results from, that I can’t figure why I didn’t do this years ago.

So, in addition to a little rearrangement, I’ve added the mod_watch stats to my stats page. I suppose, one of these days, I should put some of the configs on there so that people can see that what I’m doing really isn’t particularly hard.

Rewrite rewrite

mod_rewrite is one of the most amazing modules that comes with the Apache web server. Written by Ralf Engelschall, and granted to the ASF in 1997, it allows for arbitrarily complex URL manipulation which are not possible with the other URL mapping modules.

Unfortunately, the documentation that came along with it has been almost entirely untouched since then. And, commonly held beliefs notwithstanding, bits do rot. The documentation contains examples that are incorrect, mostly due to changes in the abilities of the module, and of the web server itself. It contains examples that are irrelevant, such as the rules for mapping NCSA server-side imagemaps to mod_imap imagemaps. I suspect that most web users today have not heard of either one of those things, nor would they know why they’d want to convert one to the other.

Also, the once enormously useful Rewrite Guide, rather than being maintained and updated, has just been added to over the years, until it is impossible to find anything in it. And, once having found it, you’re never quite sure if it’s accurate, as evidenced by my struggles of a few days ago.

However, this is far more than just a rant. I’ve actually been working on this, and should have something to show for my work in the next day or two. I’ve rearranged a bunch of the documentation, splitting it into introductory material, recipe-type material, and advanced technical stuff that nobody will ever actually read. And then there’s the standard module reference manual, like every other manual has. We’ve been discussing doing this, on the docs mailing list, for at least 2 years, but nobody ever really wanted to actually start doing it. Because it’s a bit of a daunting task. But I’m hoping that my caffeine-induced initial attempts over the last couple nights will result in some folks working on small parts of it until it’s genuinely useful.

I started working on the Rewrite Cookbook a few months ago, but that never really got off the ground. I still like the idea, but it didn’t have enough starter material to really draw an editing audience. I’ll probably do some more on that once I’ve finishes this work. We’ll see. I also am not interested in the Rewrite Guide growing into a 100-entry monstrosity that’s impossible to use, so perhaps the Rewrite Cookbook will be a helpful supplement.