Markup Toolkit

√vnav«labs«PHP«markup

Markup

is the process of adding codes to a document to identify the structure (of a document) or the format in which it is to appear.

Brief History of Document Markup (Circular 1086) — UF/ IFAS

Introduction
Adding Content
<abbr> and <acronym>
The Anchor Element
The Image Element
PHP Labs Navigation

Introduction

Writing is a craft, a true art form few people will master. It’s a big challenge, especially when the material tends to be pretty dry or technical. It’s a rare individual that would relish a quiet evening at home with an old PDP-11 reference manual. Read on to find some that do.

Everyone has their own approach to writing, and as unique as each author’s style and methods are, the Web as this so-called new media adds yet another complexity. So, unless you’re using a complete HTML authoring program such as Dreamweaver to create your pages, or perhaps a CMS of some kind, you’re free to use whatever methods work best for you. Web publishers often combine a number of different tools and technologies.

Some people will create an entire page on their client machine and then upload it to the host using the FTP protocol. Often times they will use a word processor, which certainly has its merits as they all have spell/grammar check and many other powerful features. Too many features in my opinion. HTML is plain text, so I consider a word processor overkill.

I’m personally more comfortable with text editors, and I place emphasis on simplicity and power over an application that tries to do everything for everyone. I prefer to have more control over the formatting of the text itself, so for large blocks (paragraphs) like these I use a good quality program that has spell check and other features that are geared towards text. (Hint: Find one with block select, it’s wonderful.) Many word processors also allow you to export your work as HTML. That’s the last time you’ll hear me mention that. I have found that TextPad works well for me, it has just the features I want without all the bloat of some others. Mac users tend to rave about BBEdit.

But that’s just for major blocks of text like these paragraphs. In fact I create all my pages on the host the same way I code everything else (PHP, CSS, Perl, C, Makefiles, server config files...), using the vi editor that has been a ubiquitous feature of BSD Unix for years. To be more specific, I use an open-source, enhanced version of vi called Vim. No editor wars please.

If you’ve never heard of Bill Joy then I recommend this history lesson. These guys enjoy reading PDP reference manuals. Or did. Which is a good thing, otherwise who really knows if any of this would exist. By that I mean the Internet.

Adding Content

When I actually do get down to the job of adding content, what works for me may sound a little unusual. But the point is it works. I write Web pages in a rather eclectic mixture of dialects that includes PHP, English text, markup tags and dictionaries in the form of MySQL tables.

So my toolkit is basically a library of PHP functions that do one thing each, and do it well according what I want to accomplish. Often times I’ll start with something very simple. Normally these basic functions are nothing more than wrapping an element in its opening and closing XHTML tags. For example, if I want to insert some source code:

function code($s) { return '<code>' . $s . '</code>'; }

Whoa, how is that going to help if I can just enter the tags around the string in my text? I build from the atomic:

function tag($t) { return code('<' . $t . '>'); }

Now when I want to insert an <html> tag into the text of a paragraph I can do something like:

$html = tag('html');

(which is exactly what I just did) and from then on while writing I can simply type in the tag as $html, my text flows freely as I write and PHP will expand the variable for me before it gets to your browser.

But what if I want to refer to a literal variable name? (which is what I just did again) Simple, another function:

function vary($v) { return code('$' . $v); }

<abbr> and <acronym>

Like the other little functions, I have one I use to format these two elements. See the source code for details. But I almost never use it. Why? Because I have a MySQL table that holds quite a few of them already. It is by no means exhaustive, but when I need to I simply add a new one (this has the added benefit of never misspelling it again). If I need access to them, which is often, I include the module:

include('abbr.php');

And from then on I can use one like this:

{$abbr['XHTML']}

And it expands to XHTML, styled with CSS of course. Even under IE, but that’s another article. (IE ignores the <abbr> element and also any styling on it.) You have no idea how much of a time saver this trick is. Eventually this feature will lead to a glossary of terms.

For more information on how this is implemented, visit my dbrowse application and its description of the abbr table.

All these little functions may seem trivial, until you start combining them and building more complex ones.

The Anchor Element

Frequently doesn’t even begin to describe how often I use anchors. Just in case you haven’t noticed. I like to add them as links to other parts of this site, sometimes within the current document using fragment identifiers, and to external resources so the reader can get additional information about concepts I don’t have the time or space to elaborate on. After all, hyperlinks are the KEYSTONE of the Web.

Opinion: Any Web author that avoids using, or obfuscates, external links in a delusional attempt at preventing their visitors from surfing away from their site should be taken to the woodshed. These are usually the same guys that have blinking and flashing links to advertisers.

I’m not going to continue to fill this page with more examples from the library, instead you can check out the source code to markup.php yourself for reference. You’re welcome to save it or parts of it or do whatever you want.

Note: this is a frozen copy from the time I wrote this article. So don’t be surprised if you see variations or new functions being used. I edit the original often. Also, there are functions in the library that are quite a bit more complex than I’ve mentioned here. Functions that relate more to the MySQL labs (which is still in the design/development phase).

The anchor() function follows the specification of the <a> element itself, which you can study at this W3C document: Links in HTML documents. At least partially, or what I consider important for my needs. The function accepts these arguments:

href — the destination anchor, which can be a full or relative URL, and/or optionally a fragment identifier
link label — or source anchor, which is normally text or an image
and optionally:
1. a title attribute
2. a class (I’ve never seen any need to use an ID)
3. a rel — eg. prev, next, home...
4. an accesskey

I normally use the first three — if I omit the 3rd and the source anchor is not an image the function will automatically set the title to the same string as the source anchor text.

Why all the fuss just to create links? For the same reasons I mentioned above. When writing and editing chunks of text I can abstract out the gory details of how the link will be expanded by PHP and concentrate on the grammar and flow of the text. And because my links are consistent — I prefer to have the attributes in a certain order so my eye will go directly to the same place when I need to check on something (did I use the correct class?) and free of typos (if I don’t call the function properly PHP will give me a parse error long before it ever gets to your browser). And because there’s no law stating I HAVE to use the function I can, and sometimes do, code them by hand.

Which I should really avoid. Why? Let’s say I need to make a modification to my links. If it’s just a presentation thing then I would only need to edit the necessary stylesheet(s). But what if it’s not a presentation issue? I can modify the function and EVERY link on my site will reflect the change. Nice. Beats the snot out off editing 40, or a 100 (or whatever) individual files.

The Image Element

I used the exact same concepts and methods when designing and coding my PHP image() function, so I don’t feel it’s necessary to elaborate on it. Note that combining these two functions is especially powerful. Study the markup.php source for details or drop me a note if you have questions. Two things to remember: the alt attribute is required, and you must self-close the <img> tag in order to create valid XHTML markup. If you use this function or something similar you will never forget to do either again.

Did someone say closure? Since that’s the Next topic you’d almost think I planned that — almost.