Last week I updated my wiki theme MentalWealth to support version MoinMoin 1.5. I now have a new version that adds some style support that I had missed before, namely for the .strike class and the TableOfContents macro. I also have a good number of tweaks to make skinning the theme easier.

Foremost among the changes is a refactoring of the screen.css code out into base.css, which contains all the basic classes, and a series of skin-*.css stylesheets which represent different colour skins. So now it's easy to change what colour you'd like the interface to be: simply uncomment the skin you want used.

I've also simplified the classes in base.css and rejigged some of the appearance. Changes you might notice include a slightly smaller typeface, the fact that the sidebar margins now better match the other panels, and alterations to the h5 and h6 headings to make them distinct.

I have no further plans to change this theme, unless I get bug reports or a solution to the issue I outline in the readme file.

As usual, MentalWealth is available at the MoinMoin ThemeMarket.

See the most recent article on this topic.

more

Following on my article Styling A Sitemap I thought it might be helpful to present the list of references I came up with while doing my research.

These first two should be your primary source of information.

CSS Design: Taming Lists from A List Apart covers a gamut of styling techniques.

Listamatic contains dozens of examples of styled lists.

Further examples of styling lists for site maps or folder trees can be found here:

• Styling Nested Lists article from SimpleBits


• Spruced-Up Site Maps article on A List Apart


• Tree Menu example


• CheckTree expanding tree menu


• sitemap example from Zab Design


• sitemap example from loadaveragezero


• sitemap example from Peter Müller

more

I was recently thinking about sitemaps, since it so happens I have to design several for different sites I'm working on. In many cases a plain-old list (POL) works just fine as is, so long as each level of indentation is styled distinctly. But in other situations you want something just a little bit fancier, some graphics to jazz it up. I thought that this time it would be nice to use CSS on a plain-old list (POL), so that the markup would degrade nicely on problem systems. Here's a step-by-step tutorial explaining what I came up with.

Introduction

First I went looking for existing solutions. Alexander Sperl has a very nice tutorial, in which he shows how to make graphics that can be used on various list-style-image tags. Different levels of the sitemap tree are marked up with different classes, each one corresponding to a specific image.

There is one big problem with this method, namely that many different graphics (and corresponding list styles) are needed. His code handles 3 levels and requires 8 different images. His discussion of level four items is short: "that's something you can figure out for yourself." No wonder he doesn't want to tackle it; his method is not scalable. I want one that is.

There are three major parts to this exercise. We need to build the graphics files, design our stylesheets, and code the markup.

Our Goal

Let's take a closer look at the problem. Below is a screen capture of a typical nested list such as one might find in a sitemap. If you mouse over it you see the graphical version I want to build. Our objective in this will be to keep the underlying markup as close as possible to the original.

Inspection of the problem shows that the tree is made up of only four separate graphic elements. To see this for yourself, mouse over the graphic above, but this time press and hold the mouse button. I have marked the different graphical components vertically in the first section as 1, 2, 3, 4. Rather than build all possible combinations of graphics for as many levels of indentation as we may need, we'll just use these four graphics directly. And since one of them is empty we won't even bother with a graphic file for that. See? Simple!

The horizontal set of boxes shows how we need three sequential graphics for a third-level indent. The red boxes are margins we'll remember to add.

Basic HTML

Here follows the POL layout for the sitemap. I have indented freely so the structure is more obvious.

<p><b>Post-Punk And All That</b> [album version]</p>
<ul>
  <li>Manchester
    <ul>
      <li>Magazine
        <ul>
          <li>Spiral Scratch</li>
          <li>Real Life</li>
          <li>Secondhand Daylight</li>
          <li>The Correct Use of Soap</li>
        </ul>
      </li>
      <li>Buzzcocks
        <ul>
          <li>Time's Up</li>
          <li>Another Music in A Different Kitchen</li>
          <li>Love Bites</li>
          <li>A Different Kind Of Tension</li>
        </ul>
      </li>
      <li>Joy Division
        <ul>
          <li>Unknown Pleasures</li>
          <li>Closer</li>
          <li>Still</li>
        </ul>
      </li>
    </ul>
  </li>
  <li>Liverpool
    <ul>
      <li>OMD
        <ul>
          <li>OMD</li>
          <li>Organisation</li>
        </ul>
      </li>
      <li>Echo & the Bunnymen
        <ul>
          <li>Crocodiles</li>
          <li>Heaven Up Here</li>
          <li>Porcupine</li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

Let's start the process of converting this simple code. To begin we will put a span classed as "sitemap" around this HTML, so that other CSS classes can be assigned relative to that. This prevents what we are doing here from affecting other parts of our markup. It also makes it easy to turn our effect on and off -- simply remove the outlying span.

Our CSS

We need to turn off the usual list formatting. This is a common first step in any list styling exercise. Thus the stylesheet begins with the following.

.sitemap ul, .sitemap li {
  list-style-type: none;
  margin: 0;
  padding: 0;
}

In order to be able to freely use our three line graphics in any combination we need, I'm going to assign each one to a span element. Then, those spans can be used in place of the images themselves, giving us more flexibility in styling and better degradation.

.sitemap span.vert {background-image: url(map_vert.gif);}
.sitemap span.last {background-image: url(map_last.gif);}
.sitemap span.midd {background-image: url(map_midd.gif);}

The last part of the CSS works on each of those three spans, plus a fourth for that phantom blank element I referred to earlier. We style them to be the same height and width as the graphics themselves, and then add a margin to the left to ensure a nice offset. Since this is a typographic feature, I use ems, though the truth is this method is going to break down at other font sizes, since it would need graphics of different sizes as well. (That's also true of the original method.)

We need to ensure the background elements don't repeat. In order to get the spans acting as graphic segments we set them to display as blocks. Finally, we float them to the left so that each does not start a new line. Here's the finished CSS.

.sitemap span.none, .sitemap span.vert, .sitemap span.last, .sitemap span.midd {
  width: 24px;
  height: 18px;
  margin-left: 1em;
  background: transparent 0px 0px no-repeat;
  display: block;
  float: left;
}

For those wondering, I have kept the names of the graphics and the styles the same length (eg: "midd" instead of "mid") because this way the HTML code lines up better. No other reason!

Building Blocks

These four styles now act as graphical building blocks that we can drop into our HTML where we need them. The code looks quite verbose, but it's regular and hence a piece of cake to generate in the typical scenario of dynamic code. More importantly, it does not add any other structural information to the nested lists. Here's the complete HTML.

<span class="sitemap">
<p><b>Post-Punk And All That</b> [dub mix]</p>
<ul>
  <li><span class="midd"></span>Manchester
    <ul>
      <li><span class="vert"></span><span class="midd"></span>Magazine
        <ul>
          <li><span class="vert"></span><span class="vert"></span><span class="midd"></span>Spiral Scratch</li>
          <li><span class="vert"></span><span class="vert"></span><span class="midd"></span>Real Life</li>
          <li><span class="vert"></span><span class="vert"></span><span class="midd"></span>Secondhand Daylight</li>
          <li><span class="vert"></span><span class="vert"></span><span class="last"></span>The Correct Use of Soap</li>
        </ul>
      </li>
      <li><span class="vert"></span><span class="midd"></span>Buzzcocks
        <ul>
          <li><span class="vert"></span><span class="vert"></span><span class="midd"></span>Time's Up</li>
          <li><span class="vert"></span><span class="vert"></span><span class="midd"></span>Another Music in A Different Kitchen</li>
          <li><span class="vert"></span><span class="vert"></span><span class="midd"></span>Love Bites</li>
          <li><span class="vert"></span><span class="vert"></span><span class="last"></span>A Different Kind Of Tension</li>
        </ul>
      </li>
      <li><span class="vert"></span><span class="last"></span>Joy Division
        <ul>
          <li><span class="vert"></span><span class="none"></span><span class="midd"></span>Unknown Pleasures</li>
          <li><span class="vert"></span><span class="none"></span><span class="midd"></span>Closer</li>
          <li><span class="vert"></span><span class="none"></span><span class="last"></span>Still</li>
        </ul>
      </li>
    </ul>
  </li>
  <li><span class="last"></span>Liverpool
    <ul>
      <li><span class="none"></span><span class="midd"></span>OMD
        <ul>
          <li><span class="none"></span><span class="vert"></span><span class="midd"></span>OMD</li>
          <li><span class="none"></span><span class="vert"></span><span class="last"></span>Organisation</li>
        </ul>
      </li>
      <li><span class="none"></span><span class="last"></span>Echo & the Bunnymen
        <ul>
          <li><span class="none"></span><span class="none"></span><span class="midd"></span>Crocodiles</li>
          <li><span class="none"></span><span class="none"></span><span class="midd"></span>Heaven Up Here</li>
          <li><span class="none"></span><span class="none"></span><span class="last"></span>Porcupine</li>
        </ul>
      </li>
    </ul>
  </li>
</ul> 
</span>

Conclusions

What's the score? Sperl styled 9 different areas and used 8 graphics to support a maximum of 3 nested levels. We've styled 4 spans and have used 3 (simpler) graphics to support an arbitrary number of levels. Furthermore, though I don't explore the options here, we have more flexibility in how to put together the graphics to form different types of maps. Finally, if we take away the outer span everything collapses back to the original look.

On the downside, this method does require additional spans in your code.

I am happy with that, but would love to hear from anyone who has further optimisations.

Resources

A sample file with all of the code is available for download as sitemap.html.

You will also need the graphics files. Save them to the same folder as the HTML via the usual right-click thingie.

  

more

I have finally updated my MoinMoin theme for version 1.5 of that software. For those who don't know, MoinMoin is an advanced, easy to use, and popular wiki server implemented in Python. A wiki is a collaborative web environment that allows anyone to contribute. The most popular wiki website would have to be wikipedia.

I have retired the popular MentalHealth theme to make way for MentalWealth. The name change is to signify the new version compatibility, but also because I've switched to a left-side menu bar. Having it on the right is just too prone to style and rendering problems.

There are some nice new tweaks and the missing header issue is remedied. The documentation has been expanded and stylesheets cleaned up even further. Of course it is free and available under the GPL. Hope you like it and keep the comments coming!

MentalWealth is available at the MoinMoin ThemeMarket

See the most recent article on this topic..

more

There are several famous holy wars in the history of computing. There's emacs versus vi, Mac versus PC, and tab versus spaces. These are commonly referred to as "religious issues", meaning that they are a matter of belief only. Now, the first I couldn't care less about, since I use neither text editor and preferences for keyboard mappings seem a relic of the days when dinosaurs walked the punch-card strewn floors of computing. Mac versus PC is an easy one too: use a Mac if you like spending more money for other people to make up your mind for you, otherwise use a PC. (Actually, Macs are becoming PCs¹ so what's the difference?)

But on the tab versus spaces issue I must take a stand and make a few declarations. First, the common wisdom, as espoused most emblematically by Jamie Zawinski, is dead wrong. And second, it is not a religious issue at all, because there is a correct answer.

This relates to Python in a very direct way. Python is unique among programming languages in mandating indentation as part of the language syntax: every code block must be indented.

Some slack-brains take one look at this and run away screaming "Whitespace as syntax! Whitespace as syntax! Garrrrrrr!" But anyone who actually uses Python for longer than .3 seconds realises that this rule simply enforces what any good programmer already practices. This correct indentation becomes a guide to the compiler, so curly braces and other excess syntactic cruft are not needed. It's a neat, simple solution that results in code of greater readability -- a real win-win scenario as managers say on television. (And possibly elsewhere. I wouldn't know; I avoid managers².)

But back to the issue at hand. First, why is tab versus spaces not a trivial issue? I suppose that for any given programmer it is, but if you work on a team you must come to some sort of agreement or be constantly converting back and forth. This is possibly time-consuming, possibly error-prone, and possibly not even that easy depending on your tools. So it's best avoided by agreeing on a standard.

Before going any further we should acknowledge the most important article on the subject and read jwz's "Tabs versus Spaces: An Eternal Holy War."

Jamie breaks the issue down into three parts. He notes that hitting the tab key does different things on different systems, but as you can configure this behaviour it's not the main problem at hand. Furthermore, encountering a tab character in a file is the same: you can do what you wish to do.

The third part of the issue (actually it's his #1) must then be the real problem: people care about how many columns a tab/indent represents. He calls this a "religious war" because he has misidentified the problem. His solution is to have tabs expand to spaces before writing a file to disk, so tabs never exist in interchanged files.

This assumes one will never have to open a file containing spaces and intuit what tabs are supposed to be there, or how the spaces should be interpreted. Perhaps jwz never has bugs or has to re-edit his code. Or perhaps he's used to write-only languages like C++ and Perl where the least of your problems are relating to tabs because you are already committed to spending inordinate amounts of your precious life wading through code trying to find the crucial lines that actually do something.

Then he spends the second half of the rant talking about specific settings in arcane software.

Where did jwz go wrong?

First, his three points are not separable, at least not in the way he would like. Discussing the tab key he says "this is an editor user interface issue" in order to dismiss the problem. Editors treat tabs here as "indent to a column position", there as "add so many spaces", and in a third case as a single character of value "ASCII 9". So, according to jwz, it's not an important part of the problem.

But how is this different from the point he says is the most important, that when reading and writing code, people "care about how many screen columns by which the code tends to indent when a new scope (or sexpr, or whatever) opens"? (Strangulated syntax in original.)

Answer: it is not different. There are not three points; there are two.

A tab has both syntax, a representation, and semantics, a meaning.

With this plain and simple approach it is dead obvious that using spaces to represent tabs at the level of encoding is inherently wrong because we are throwing away meaning. A tab no longer has its own representation but is instead subsumed into how we represent spaces.

An example illustrates the problem. If you save all tabs as two spaces and the next person who opens the file instead wants to see tabs as indenting to a given column position, how are they going to do that? First they'll have to assume that all two-space sequences are tabs, and then they can interpret those tabs. But the assumption is dangerous and wrong. Everywhere that two spaces do not in fact represent a tab there will be an error of interpretation. Meaning will have been lost.

Spaces cannot represent tabs as encoding. They can in a display, but that is the choice of the viewer at the instant and not something to be persisted eternally in the file.

Preserving tab characters allows them to mean something different to each user. This makes no assumptions about the capabilities of the tools used. It does not require everyone to use the same editor with certain macros playing to automatically convert, or any such nonsense.

Furthermore tabs have the following advantages:
* one key to hit instead of up to 8 ³
* not open to error when 7 or 6 spaces are hit instead of 8
* makes diffing files easier (because of previous two points)
* smallest file size

Use tabs not spaces. Why would anyone be so foolish as to suggest any different?



¹ Not only do they use Intel processors and ATI video cards but also boot Windows.

² For that matter I avoid television as well.

³ You think you won't ever have to do this because you have your tabs set to 4 characters and inserted automatically? Just wait until you look at someone else's code and all you have are spaces as guides. Sucker.

more

A new Python logo (pictured at left) has been approved by the PSF, following the heated debate that broke out on comp.lang.python after the new Python home page design was revealed. Many people disliked the interim logo, claiming it looked like two copulating tadpoles, not at all the sort of image a programming language named after a comedy troupe should promulgate.

A spokesperson for the PSF said "We realise our mistake in attempting a design that might be symbolic, subtle, or otherwise obscure. We want instead to present a direct image of the Python language, something which people can identify with. Python is for everybody and the logo should be too."

So apparently they've gone back to a snake, something immediately recognisable, and included a second image to play off the catch-phrase "batteries included".

"We did not feel that the logo needed any text, as it's obvious that what we have here is a Python. All of us know that this represents the Python language. Those who don't will either soon find out or make their way to Ruby or some other non-snake language."

I wondered if it was not significant that the shape formed by the intersection of the snake head and battery was a distinct cross. But when asked the spokesperson replied "There's really nothing I can say about that. Are you a member of the PSF? No? Sorry, I can't talk to you any further about our inner rites. No comment."

more