O O Ø O O O O

The pd.o Guide to Style

Publishing standards we use.

This document is a self-serving guide to the pd.o publishing standards du jour. We, of course, reserve the right to change our minds at any time. We’re bitchy like that.

General Markup

Markup must be XHTML 1.1 compliant. The period at the end of the phrase Fresh Every Tuesday—which can be found at the bottom of every single pd.o page—links to the W3C validation engine to aide in this pursuit.

Specific Markup

Paragraphs

Use <p></p> to mark paragraphs. You have to close a paragraph before a <ul></ul> block begins.

Line Breaks

If you do use <br>, use the XHTML variant <br />. We try to use this as little as possible, as it often implies some sort of visual ordering, which would be better handled via the stylesheets.

Fonts vs. Styles

Don’t use <font>. We fix up most everything in the stylesheet.

Quotes, apostrophes, and the evil inches/feet marks

Use “ and ” (curly quotes). Then, when done, use the ent2num.pl script to change them to their numerical equivalents

We use the ’ entity to handle apostrophes. If there is another entity we should be using for this purpose, and it displays consistently across multiple platforms, we’d love to hear of it.

The things on your keyboard, (") and ('), are inch and foot marks respectively. They are not proper substitutes for quotation marks (“ ”) and apostrophes (’). The only time to use them as stand-ins for curly quotes and apostrophes is in the markup for title="" attributes, since browsers are wildly inconsistent in displaying entities there.

Many occurrences of quotation marks in the text can (and probably should) be handled with <em></em> tags instead. Phrases and jargon are good examples. Quotes should be reserved for actual quotations.

Recall that final punctuation goes inside the quotation marks. i.e. “Whatever, bitch,” he said. But trailing semicolons and colons go outside the quotes.

Numbers, Acronyms, and Small Caps

Put <span class="numeral"></span> around numbers so they get the reduced-size treatment. This is so numbers don’t look disproportional in the body of the text. This is easily the most obsessive bit of markup we do at the pd.o, but we think the inconvenience is worth it for the well adjusted type display. In future versions of XHTML, there will be an <n> element to do this, but it lacks the panache of <span class="numeral">, don’t you think?

Put <abbr title=""></abbr> around abbreviations so they also get smallcapped, and have appropriate popup text.

If you have an abbreviation that is not an acronym, yet you want to use the <abbr title=""></abbr> markup around it (examples include Trans. and Ed.), you will want to turn off the automagic font downsizing. Add a class="fullsize" to the <abbr> tag.

On the <title> attribute

Don’t put any line breaks in the middle of a title="" tag, unless you intend the CR to be there, as browsers will render them literally.

Em-dashes, en-dashes, and hyphens

Use – (–) and — (—) as appropriate instead of “-” or “--”. The em-dash is used for parenthetical comments—like this one—and traditionally has no space around it. The en-dash gets used in date ranges, such as 1772–1834, or any situation where you are spanning a length of time.

href targets

Use id="foo" instead of <a name="foo">. It has the added advantage of being valid in just about any tag. Note that id strings must start with a letter. All-numeric ids are a standards no-no. We have no idea why this ridiculous restriction exists, but for now, we have to live with it.

Orphan control

In multi-word headers, it’s safest to connect the last two words with an   (non-breaking space), so the last word will never sit on a line by itself.

For example:

This line has an
orphan.

This line does not.

So as a rule, just replace the space between the last two words in any header with an  . If you like, you can also do this to the last two words in every paragraph. But that’s pretty extreme.

Horizontal rules

We don’t use <hr>s. Long ago David Seigel taught us they’re unnecessary, and can always be replaced with more whitespace.

pd.o style

We have an id="desc" for a brief introductory line that might help clarify the page title.

We also have a class="tagline" for longer parenthetical thoughts at the beginning of a rant. Since these two elements are italicized in our stylesheets, and because italics are harder to read on screen, it’s best to keep these comments short.

Add <div id="rcallout"> or <div id="lcallout"> to break up the visual monotony of the text. Pick some choice or juicy phrases to call out in this fashion. Or if you’re Evan, do the print-media thing, and call out titles in line with the text using <h2>s.

Use <div id="rsidebar"> and <div id="lsidebar"> to contain passages related to the text, but not part of the narrative. Be careful where you place these sidebars, as non-traditional browsers such as screen readers and text-only devices will display these in line with the text. Sometimes it’s best to call out additional ideas in separate sections at the end of the rant.

Add links, dammit!

When you’re about done writing and marking up your text, go back and find fun things to link to. This leads nicely into our next topic:

Linking

We link to other sites because the web is founded on the idea of interlinked documents, and we like to think we believe in the web.

But we also link to other sites because it’s an additional opportunity for snarkiness.

That means we have two options, when linking documents. If we’re talking about Air Canada, and decide to link to their corporate site, we should match the link up with a suitably snippy title attribute. e.g. <a href="www.aircanada.com" title="Mapleflot">. The advantage is, if enough people use that link to actually go to the site, we might get a visit from whoever reads the web logs. That in turn, may lead to snarky email from the guilty. The pd.o is all about snarky email from the guilty.

An alternative is not to link to the corporate site at all, but to find some other biting commentary, unsavoury news clipping, personal rant or otherwise satirical piece to link to instead. This has the benefit of not driving traffic to the corporate sites, and can also quite often emphasize a point.

We almost always do the latter, with a sniffy title attribute thrown in.

On the Permanence of URIs

At the pd.o, all URIs are considered permanent. This means a couple of things:

Put some thought into coming up with a good URI in the first place. Ask yourself questions like “Is this item in an appropriate directory,” and “Will the URL make sense in two years, when we’ve added more content to this section?”
If you move or rename something (permanently), we must drop in an appropriate HTTP 301 permanent redirect. For now, this involves mucking with the webserver configuration. Mail your nearest administrative geek if you need help with this.

Pint Day vs. pintday.org vs. the pd.o

Pint Day refers to the day, or the ritual. Both words are always capitalized, much like Easter Sunday. pintday.org refers to this web site, and is never capitalized. This can be—and quite often is—contracted to the pd.o, which always carries a leading “the.” Again, it’s never capitalized. And yes, we’re picky.

pintday.org » Fresh every Tuesday .