Using the Linux Step-by-Step Template

The Step Title

The Step title should be embedded between <h1></h1> tags. If you wish, you can also add an icon or small image relating to your Step, as shown in the example for this page. Just replace the HTML src="info.png" with your own image. We prefer PNGs. Please include the image's height and width as shown in the following example code:

<img src="info.png" height="48" width="48">

Categorizing Your Step

If your Step is a subset of an existing category, the title should indicate this:

<h2>CATEGORY-MySteps</h2>

As an editorial note, the editors might change the category to which you submit a step to better fit with the site's overall layout. Don't take it personally.

Credits and Document Versioning

Each Step should indicate who wrote it and your email address, as shown above. Please be sure to use a mailto: link:

<a href="mailto:bubba@example.com">Bubba</a>

Likewise, all URLs in the Step itself should have active links because cutting and pasting email addresses and URLs gets annoying! This is the Web, after all.

When appropriate, a Step should indicate the Linux distribution(s), program version, or kernel release to which the Step applies and/or on which it has been tested. For example:

• Tested on: Fedora Core 3 with the standard kernel binaries
• Tested on: Kernel 2.6.11.4
• Applies to: Firefox 1.0.5 and newer

It's also a good idea to include one or both of:

• Date Submitted: 25 Dec 2005
• Document Version: 1.1

This helps you and us maintain things. If you are updating someone else's work, add an line beneath the "Submitted by:" line that indicates this. See the top of this guide for an example.

Font Styles & Colors

Font styling and colors have been moved into a stylesheet that is included in the HTML header. Rather than cluttering up the text with <font> and <color> tags, you can use basic HTML tags. Leave the styling and presentation up to the stylesheet. This creates greater uniformity across the site and makes it considerably easier for you to write a Step and for us to maintain it.

HTML Usage Tips and Guidelines

Because the stylesheet handles font and color styling, focus on getting the semantic markup right. As a general rule, don't use markup that is intended merely to affect how something looks. If you're looking for a specific appearance, contact the editors and we can modify the stylesheet. A few specific tips follow.

Emphasizing Text

When you want to emphasize an important point or word, enclose it between <em></em> tags. Thus, the markup looks like this:

Important points or words will <em>look like this</em>

and gets rendered like this:

Really, really important points should be embedded between <strong></strong> tags. Thus, the markup looks like this:

Really, really important points <strong>look like this</strong>.

and gets rendered like this:

Marking Directories and Filenames

When you want to show a directory path or filename, such as /usr/local/bin, embed the path in a path <span>. For example, the following HTML code:

To build the kernel, change to your kernel source directory,
<span id="path">/usr/src/kernel<span>.

will appear like the following in the rendered document:

To build the kernel, change to your kernel source directory, /usr/src/kernel.

Similarly, to tell readers to type a command, say, /usr/bin/gcc -c hello.c , embed the command in cmd <span>. For example, the following HTML code:

To start the kernel configuration, type <span id="cmd">make
menuconfig<span>.

will appear like the following in the rendered document:

To start the kernel configuration, type make menuconfig

Sections

If you want to divide your Step into sections, use <h2></h2>, <h3></h3>, and <h4></h4> heading tags. Please, no more than three levels of headings! The <h1></h1> tag is reserved for the title of the Step, so the top-level head is <h2></h2>, subheadings are tagged with <h3></h3>, and subsubheadings are tagged with <h4></h4>. For example:

<h2>Top Level Heading</h2>
<h3>Sub Heading</h3>
<h4>Sub Sub Heading</h4>
<h4>Sub Sub Heading</h4>
<h3>Sub Heading</h3>
<h4>Sub Sub Heading</h4>
<h4>Sub Sub Heading</h4>

This renders as shown below. Notice that the example's font size is smaller than the default to illustrate the progresson.

Top Level Heading

Sub Heading

Sub Sub Heading

Sub Sub Heading

Sub Heading

Sub Sub Heading

Sub Sub Heading

Bullets & Numbers

If your Step can be presented as a series of bullet points or, the preferred option, as a series of numbered steps, this is by far the best way to go for a few reasons:

• Numbered steps are easier to follow. Just "paint by numbers" and voilá!
• It's easier to easier to read and follow instructions like "See section 2" or "Jump to step 3" than is it to read "See the 3rd paragraph."
• If you use numbered steps, you don't have to renumber them manually — HTML does it for you.
• Embedded lists (that is, lists within lists) automatically Do The Right Thing ©.

Final Notes

These are not hard and fast rules and your Step submission won't be rejected automatically if it doesn't meet them. However, it is easier on the editors if you at least try to follow these few guideslines. There will not be a huge effort put into changing existing Steps to this format, but we will be gradually moving them into the new format. What we're hoping to achieve is a simple look that is easy to maintain and that results in a consistent, uniform appearance across the site. If we stick to a similar format, the site's pages will all look like they belong together, not like visitors have jumped to a new site when they've only opened a new page. Thanks for your help!