I'm currently trying to draw a diagram for the Oddmuse manual, in which I want to explain how the various technical terms are related. Stuff I'm thinking of include the DocumentRoot, the DataDir, having a wrapper script, explaining that the default location for the pages are in a temporary directory, and so on.

Right now, I'm still in the pencil and paper phase.

CGI script

Originally I had planned for the castle guards to do redirecting and all that, but I didn't know where to put them. I'll have to reorder things. The explanation of the cgi-bin directory on the right should also move a bit up and left…

User DasSheep on #wiki also suggested I pick apart the URL when explaining rewriting. Instead of taking the metaphor too far, he suggested something like the following:

           |                   |                 |
    which server to contact    |                 |
                               |                 |
                     what program to use         |
                                    additional parameters
                                    to the program

And then explain that there are different forms for the third part (eg. action=browse;id=example), and then go on how to use rewriting to hide the second part, too.

The Wiki as a shop... Maybe make sure that the diagram also shows how only the wiki program can get data out of the DataDir. Very unlike the DocumentRoot, for example. DasSheep suggested that the "data dir is a closed box, htdocs is a glass box, and the cgi-bin is a window. The wiki script is a merchant who stands in the window, everyone can look freely at things in the glass box but to do anything with the closed box, they have to ask the merchant and he can show them the wares, or even do things with them. That will also explain why wikis are slow when there are many users and why serving attachments from the closed box is slower than from the glass box."

I'm personally more interested in explaining all the necessary terms so that a users knows more or less what is going on when they are installing a wiki.

I like the ASCII diagram of the URL.

How about, instead of a shop, a library – many university libraries have some books that you can't go get yourself, but that you have to ask a librarian to get for you. The librarian being the CGI script.

Web Server Setup I've started to work on an image in xfig. The metaphor discussion has convinced me that I should try and avoid using a metaphor. I don't think VisualLanguage requires a metaphor. (Source: WebServerSetupSource.)

I won't throw out metaphor, in my personal toolbox.

But, I think the metaphors in the examples above weren't very good, especially for the audience you're addressing.

This latest picture has too small of an information density; My eye's spending way too long tracking back and forth.

I'd work on it more, but I'm busy with some code right now. :)

Good point. I was stuck with some xfig problems, too, so I decided to upload first and solve problems later. ;)

I'm confused. wiki.pl calls current.pl, and current.pl investigates httpd.conf's DataDir? setting..?!

That can't be right…

I'm uploading my present understanding.

image: %s

Oops, my mistake! I'm conflating terms used for the web server setup with terms used for the wiki setup, since I figured that keeping them appart would confuse newbies anyway. The DataDir? is the Oddmuse data directory.

I think I like Inkscape. :)

Define external redirect: DataDir