Arch Documentation Guide

Summary

This document defines a standard for official ArchLinux documentation. It describes mandatory and optional elements of a document and lists methods of writing a document that conforms to the specifications.

The standard is based upon unmodified XHTML1.0 Strict with CSS2 stylesheets, according to the W3C specifications. Although this results in great freedom for the author, the author must layout a document as outlined in this document, and should file a bug report in case the standard seems to be missing a necessary definition to ensure a consistent layout across all official documents.

Table Of Contents

Introduction

Documentation and support for ArchLinux comes in several forms. The web-based user forum is a very current and broad source of information on all that is Arch, but it naturally lacks a concise organization and proof-reading. To remedy the lack of organization somewhat, the ArchWiki has been set up to structurize available guides, questions and howtos, and put them under constant public supervision. Although being proof-read by potentially dozens of people, the information is still not authoritive in any way; Anyone can add and modify anything in the wiki, which is not acceptable for documents intended as reference.

Enter official documentation. Reference documentation like the installation guide, manuals of system-specific application like pacman and miscellaneous meta-documentation like this standard are static entities under constant maintainance of a close-knit group of volunteers who ensure maximum quality in layout and content. To facilitate this goal, it proved mandantory to create this guideline on how to create a document supposed to be submitted as official reference material.

Get Files

The first thing you will need to do is to download the files used as a template for the documentation look and feel. These files include this stylesheet and a minimal template without any extraneous content so you can start editing immediately, or an example template with a few sample sections and tags to help you get started.

Save the template and stylesheet into the directory you wish to work from. Do not edit the stylesheet file; You should just download it to be able to test and validate your document locally.

You may also want to save a copy of this Documentation Guide for reference, as it contains examples of all styles both inline and in the source code.

Edit Template

Rename the template.html to the filename you wish to work with (ie: mydoc.html), and open the file in your favourite editor (ie: vim).

When editing the document source, limit the line length to 80 characters at max, and use tabs for indenting, not spaces. Of course this does not apply to code blocks where indentation is preserved.

There are a few dummy entries in the template that you are expected to fill in yourself. They are delimited by double underscores and are in all-caps; spaces are replaced with underscores. Thus, to locate the template variables you can use the regular expression __[A-Z_]+__. Having a highlight matches option in your editor helps ensure you don't miss any.

Title

The title of the document needs to be specified in two places, marked with the __TITLE__ dummy text.

• between the <title> tags in the head of the document
• between the <h1> tags right at the beginning of the body

The title should be descriptive, but not overly long. Try to keep it under five words.

Date

Replace __DATE__, located at the beginning of the body below the <h1> heading, with the current date. This value should be changed every time you update the document.

The date should be in <abbrev. monthname> <day>, <year> format. For example: Jan 1, 1970.

Version

Replace __VERSION__, located below the date, with the version of the document. ArchLinux' documentation uses the major.minor.revision versioning scheme, where major is incremented on complete rewrites or other major changes, minor only after small additions or changes, and revision for spelling, grammar, or other simple corrections. The initial version number you should start with should thus be 0.1.0, and stay below 1.0.0 during development and correction phases. Upon public release as an official document, the version must be bumped up to 1.0.0.

Author

Specify each author inside individual <address> tags by providing their first and last name where the __AUTHOR_ mark is located in the template, followed by a valid, unmunged e-mail address (__EMAIL__) linked with an anchor of the email class. Do not seperate author entries with the line break tag, but create multiple address blocks for multiple authors.

Author section example:

	
<address>
  Dusty Phillips 
  <a class="email" href="mailto:dusty@archlinux.org">dusty@archlinux.org</a>
</address>
<address>
  Dennis Herbrich
  <a class="email" href="mailto:dennis@archlinux.org">dennis@archlinux.org</a>
</address>
		

Summary

Change the summary section below the addresses, marked with the __SUMMARY__ dummy, to include two or three paragraphs precisely describing the document's contents.

The summary should be short and to the point.

Character Set

When editing the template, keep in mind that the whole document should be encoded with the UTF-8 character set. In the likely situation that the editor you are using does not output UTF-8 encoded text directly, you must convert the document afterwards to let special characters (ie. the Umlaut-A, Ä) appear correctly. If you are using plain ASCII to write a guide this is not necessary as ASCII is a subset of UTF-8, and thusly there won't be any special characters that'd require conversion.

To convert a file to UTF-8, you may use the iconv application. It is included in the glibc package and should therefore be readily available on linux systems. To convert a file named myguide.html you would run this command to create a new file named myguide-new.html containing the UTF-8 encoded content: $ iconv -t UTF-8 -o myguide-new.html myguide.html

Sections And Content

Once you replaced these dummies with information specific to your document, you can start working on the content which should be divided into sections, subsections, and subsubsections, followed by paragraphs. Headings for these sections are represented by default XHTML default heading tags; <h2>, <h3>, and <h4>, respectively.

Actual flowed text paragraphs following a heading must be initiated with a <p> tag and closed with </p> to be valid XHTML markup.

Place the section/subsection/subsubsection titles between the appropriate heading tags. In addition, for sections and subsections, add an id property with a suitable and unique reference name inside the start heading tag.
For example:

<h2 id="sections">Sections And Content</h2>
		

Finally, update the table of contents to include the new section as outlined in the next step.

Table Of Contents

The table of contents' location is marked with the __TOC__ dummy in the template, and is located below the document's summary. The existence of a TOC may be considered optional for very short documents.

The TOC section must be given a <h2 heading like any other section. This heading is included in the template, and should be modified when writing a document in a language other than english. The correct location for the name of a section within the document is marked with __SECTION__ in the template, whilst a reference id of your choice must be put where __REFERENCE__ is listed.

The table itself must be enclosed in a <div class="toc"> block. It consists of an ordered list, instantiated with the <ol> and </ol> tags, with every document section represented by a list item (<li>,</li>) linked to the id of the section's heading. If a section contains subsections, these are embedded within the list item tags of the superior section, in an ordered list of their own. See the following example code.

<h2 id="toc">Table Of Contents</h2>
<div class="toc">
<ol>
  <li><a href="#section1">Section 1</a></li>
  <li><a href="#section2">Section 2</a>
    <ol>
      <li><a href="#subsec21">Subsection 2.1</a></li>
      <li><a href="#subsec22">Subsection 2.2</a></li>
    </ol>
  </li>
  <li><a href="#section3">Section 3</a></li>
  <li><a href="#section4">Section 4</a></li>
</ol>
</div>
		

Special Styles

The stylesheet file contains several predefined styles you should use when displaying certain information to the user:

• inline code and literals
• code blocks
• user input
• hints and notes
• warnings

When referring to a command, filename, or similar construct inline (within the text), enclose it in the <code> and </code> tags: <code>command</code>

Command lines a user is supposed to type into the shell should be enclosed in the <kbd> and </kbd> tags, which must be placed within a paragraph. Just like the <pre> tags described below, whitespace is preserved, and additionally line wrapping is suppressed if possible.

To display a block of code, configuration file contents, or anything else that should retain it's formatting on the page, use the <pre> and </pre> tag. Note that whitespace will be preserved in this block, so refrain from using indentation where not intended! Start filling the block from the beginning of the line, even if other XHTML code is indented.

As illustrated above, you may use the <div class="note"> content </div> construct to offset some note or remark from the rest of the text.

Similarly, instructions that can be potentially dangerous should be enclosed in the <div class="warning"> content </div> construct to alert the user to the possible problems:

Style Guidelines

You may use all standard XHTML1.0 markup as needed in your text. You should not, however, redefine styles, alter the general layout or include scripting content of any kind. Using anything beyond the techniques outlined above should be well considered under the general rule of ArchLinux, Keep It Simple, Stupid!, as well as the W3C recommendations for using XHTML.

Avoid using tables for anything other than tables of values. Avoid tables when a unordered list will suffice.

To include a large image (such as a screenshot), create an appropriately sized thumbnail to show, and add a link to the full sized image, all within a <div class="thumbnail""> block.

click to enlarge

To create the above picture, this code was used:

<div class="thumbnail">
  <a href="archbg.png">
    <img src="archbg-thumbnail.png"
         alt="A shiny glass ArchLinux logo - Thumbnail"
         title="ArchLinux Logo Background Image"/>
  </a>
  <p>click to enlarge</p>
</div>
		

If the image you intend to show is rather small, simply leave away the anchor tags. Using a short descriptive paragraph and appropriate alt and title properties in the image tag is encouraged, though.

Validation and Submission

Your finished document must be fully conforming to the XHTML1.0Strict standard as defined by the W3C. To ensure validity, you should probably use a validity checking application. To check your document for validity using the xmllint command line tool (included in the libxml2 package), call it with these parameters: $ xmllint --valid --noout <filename>

A different option is the W3C Validator. You must stick to strict XHTML1.0 markup for your document to be successfully validated.

Before you submit a document, make sure you understand the requirements for official documentation:

• At least two (2) persons must be named who are willing and able to keep the submitted document up to date when changes become necessary. Exceptions can and will be made for documents that tend not to change often or at all.
• The document's contents must be your own work, or you must have written permission by the original author(s) to redistribute it in full on the web and (potentially) in printed form.
• You explicitly grant the documentation maintainer(s) of ArchLinux the non-exclusive right to distribute your document on any webpage or in printed form, in parts or complete, without any modification beyond technical necessity or fixing typos. You may revoke this right at any time by sending a statement to that effect to one of the documentation maintainers by email, after which any copy directly under the control of the ArchLinux developers will be removed.
• Speling Erors and, incorrect, grammar, should be kept to a minimum.
• The documentation maintainer(s) may reject your document for any reason. To make sure you won't be wasting your time, it's always a good idea to ask first if an official document is needed for a specific topic, or if it wouldn't fit better into the Wiki.

If you agree to the terms above, we'd love to hear from you!
To submit your document, e-mail it to dusty@archlinux.org or dennis@archlinux.org and we'll have it put on site as soon as possible. You do not need to include the CSS file or template, just your finished document and any images it may need.

Thanks for your help on making ArchLinux a little easier to use!