FreeBSD Documentation Project Primer for New Contributors
Prev		Next

Chapter 4. SGML Markup

Table of Contents
4.1. HTML
4.2. DocBook
4.3. * LinuxDoc

This chapter describes the three markup languages you will encounter when you contribute to the FreeBSD documentation project. Each section describes the markup language, and details the markup that you are likely to want to use, or that is already in use.

These markup languages contain a large number of elements, and it can be confusing sometimes to know which element to use for a particular situation. This section goes through the elements you are most likely to need, and gives examples of how you would use them.

This is not an exhaustive list of elements, since that would just reiterate the documentation for each language. The aim of this section is to list those elements more likely to be useful to you. If you have a question about how best to markup a particular piece of content, please post it to the FreeBSD Documentation Project mailing list <freebsd-doc@FreeBSD.org>.

Inline vs. block: In the remainder of this document, when describing elements, inline means that the element can occur within a block element, and does not cause a line break. A block element, by comparison, will cause a line break (and other processing) when it is encountered.

4.1. HTML

HTML, the HyperText Markup Language, is the markup language of choice on the World Wide Web. More information can be found at <URL:http://www.w3.org/>.

HTML is used to markup pages on the FreeBSD web site. It should not (generally) be used to mark up other documention, since DocBook offers a far richer set of elements to choose from. Consequently, you will normally only encounter HTML pages if you are writing for the web site.

HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the latest, 4.0 (available in both strict and loose variants).

The HTML DTDs are available from the ports collection in the textproc/html port. They are automatically installed as part of the textproc/docproj port.

4.1.1. Formal Public Identifier (FPI)

There are a number of HTML FPIs, depending upon the version (also known as the level) of HTML that you want to declare your document to be compliant with.

The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0.

    PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

4.1.2. Sectional elements

An HTML document is normally split in to two sections. The first section, called the head, contains meta-information about the document, such as its title, the name of the author, the parent document, and so on. The second section, the body, contains the content that will be displayed to the user.

These sections are indicated with <head> and <body> elements respectively. These elements are contained within the top-level <html> element.

Example 4-1. Normal HTML document structure

    <html>
      <head>
          <title>The document's title</title>
      </head>
    
      <body>
    
        ...
    
      </body>
    </html>

4.1.3. Block elements

4.1.3.1. Headings

HTML allows you to denote headings in your document, at up to six different levels.

The largest and most prominent heading is <h1>, then <h2>, continuing down to <h6>.

The element's content is the text of the heading.

Example 4-2. <h1>, <h2>, etc.

Use:

    <h1>First section</h1>
    
    <!-- Document introduction goes here -->
    
    <h2>This is the heading for the first section</h2>
    
    <!-- Content for the first section goes here -->
    
    <h3>This is the heading for the first sub-section</h3>
    
    <!-- Content for the first sub-section goes here -->
    
    <h2>This is the heading for the second section</h2>
    
    <!-- Content for the second section goes here -->

Generally, an HTML page should have one first level heading (<h1>). This can contain many second level headings (<h2>), which can in turn contain many third level headings. Each <hn> element should have the same element, but one further up the hierarchy, preceeding it. Leaving gaps in the numbering is to be avoided.

Example 4-3. Bad ordering of <hn> elements

Use:

    <h1>First section</h1>
    
    <!-- Document introduction -->
    
    <h3>Sub-section</h3>
    
    <!-- This is bad, <h2> has been left out -->

4.1.3.2. Paragraphs

HTML supports a single paragraph element, <p>.

Example 4-4. <p>

Use:

    <p>This is a paragraph.  It can contain just about any
      other element.</p>

4.1.3.3. Block quotations

A block quotation is an extended quotation from another document that should not appear within the current paragraph.

Example 4-5. <blockquote>

Use:

    <p>A small excerpt from the US Constitution:</p>
    
    <blockquote>We the People of the United States, in Order to form
      a more perfect Union, establish Justice, insure domestic
      Tranquility, provide for the common defence, promote the general
      Welfare, and secure the Blessings of Liberty to ourselves and our
      Posterity, do ordain and establish this Constitution for the
      United States of America.</blockquote>

4.1.3.4. Lists

You can present the user with three types of lists, ordered, unordered, and definition.

Typically, each entry in an ordered list will be numbered, while each entry in an unordered list will be preceded by a bullet point. Definition lists are composed of two sections for each entry. The first section is the term being defined, and the second section is the definition of the term.

Ordered lists are indicated by the <ol> element, unordered lists by the <ul> element, and definition lists by the <dl> element.

Ordered and unordered lists contain listitems, indicated by the <li> element. A listitem can contain textual content, or it may be further wrapped in one or more <p> elements.

Definition lists contain definition terms (<dt>) and definition descriptions (<dd>). A definition term can only contain inline elements. A definition description can contain other block elements.

Example 4-6. <ul> and <ol>

Use:

    <p>An unordered list.  Listitems will probably be
      preceeded by bullets.</p>
    
    <ul>
      <li>First item</li>
    
      <li>Second item</li>
    
      <li>Third item</li>
    </ul>
    
    <p>An ordered list, with list items consisting of multiple
      paragraphs.  Each item (note: not each paragraph) will be
      numbered.</p>
    
    <ol>
      <li><p>This is the first item.  It only has one paragraph.</p></li>
    
      <li><p>This is the first paragraph of the second item.</p>
    
        <p>This is the second paragraph of the second item.</p></li>
    
      <li><p>This is the first and only paragraph of the third
        item.</p></li>
    </ol>

Example 4-7. Definition lists with <dl>

Use:

    <dl>
      <dt>Term 1</dt>
    
      <dd><p>Paragraph 1 of definition 1.</p></dd>
    
        <p>Paragraph 2 of definition 1.</p></dd>
    
      <dt>Term 2</dt>
    
      <dd><p>Paragraph 1 of definition 2.</p></dd>
    
      <dt>Term 3</dt>
    
      <dd>Paragraph 1 of definition 3.  Note that the &lt;p&gt;
        element is not required in the single paragraph case.</dd>
    </dl>

4.1.3.5. Pre-formatted text

You can indicate that text should be shown to the user exactly as it is in the file. Typically, this means that the text is shown in a fixed font, multiple spaces are not merged in to one, and line breaks in the text are significant.

In order to do this, wrap the content in the <pre> element.

Example 4-8. <pre>

You could use <pre> to mark up an e-mail message;

    <pre>  From: nik@FreeBSD.org
      To: freebsd-doc@FreeBSD.org
      Subject: New documentation available
    
      There's a new copy of my primer for contributers to the FreeBSD
      Documentation Project available at
    
        <URL:http://people.FreeBSD.org/~nik/primer/index.html>
    
      Comments appreciated.
    
      N</pre>

4.1.3.6. Tables

Note: Most text-mode browsers (such as Lynx) do not render tables particularly effectively. If you are relying on the tabular display of your content, you should consider using alternative markup to prevent confusion.

Mark up tabular information using the <table> element. A table consists of one or more table rows (<tr>), each containing one or more cells of table data (<td>). Each cell can contain other block elements, such as paragraphs or lists. It can also contain another table (this nesting can repeat indefinitely). If the cell only contains one paragraph then you do not need to include the <p> element.

Example 4-9. Simple use of <table>

Use:

    <p>This is a simple 2x2 table.</p>
    
    <table>
      <tr>
        <td>Top left cell</td>
    
        <td>Top right cell</td>
      </tr>
    
      <tr>
        <td>Bottom left cell</td>
    
        <td>Bottom right cell</td>
      </tr>
    </table>

A cell can span multiple rows and columns. To indicate this, add the rowspan and/or colspan attributes, with values indicating the number of rows of columns that should be spanned.

Example 4-10. Using rowspan

Use:

    <p>One tall thin cell on the left, two short cells next to
      it on the right.</p>
    
    <table>
      <tr>
        <td rowspan="2">Long and thin</td>
      </tr>
    
      <tr>
        <td>Top cell</td>
    
        <td>Bottom cell</td>
      </tr>
    </table>

Example 4-11. Using colspan

Use:

    <p>One long cell on top, two short cells below it.</p>
    
    <table>
      <tr>
        <td colspan="2">Top cell</td>
      </tr>
    
      <tr>
        <td>Bottom left cell</td>
    
        <td>Bottom right cell</td>
      </tr>
    </table>

Example 4-12. Using rowspan and colspan together

Use:

    <p>On a 3x3 grid, the top left block is a 2x2 set of
      cells merged in to one.  The other cells are normal.</p>
    
    <table>
      <tr>
        <td colspan="2" rowspan="2">Top left large cell</td>
    
        <td>Top right cell</td>
      </tr>
    
      <tr>
        <!-- Because the large cell on the left merges in to
             this row, the first <td> will occur on its
             right -->
            
        <td>Middle right cell</td>
      </tr>
    
      <tr>
        <td>Bottom left cell</td>
    
        <td>Bottom middle cell</td>
    
        <td>Bottom right cell</td>
      </tr>
    </table>

4.1.4. In-line elements

4.1.4.1. Emphasising information

You have two levels of emphasis available in HTML, <em> and <strong>. <em> is for a normal level of emphasis and <strong> indicates stronger emphasis.

Typically, <em> is rendered in italic and <strong> is rendered in bold. This is not always the case, however, and you should not rely on it.

Example 4-13. <em> and <strong>

Use:

    <p><em>This</em> has been emphasised, while
      <strong>this</strong> has been strongly emphasised.</p>

4.1.4.2. Bold and italics

Because HTML includes presentational markup, you can also indicate that particular content should be rendered in bold or italic. The elements are <b> and <i> respectively.

Example 4-14. <b> and <i>

    <p><b>This</b> is in bold, while <i>this</i> is
      in italics.</p>

4.1.4.3. Indicating fixed pitch text

If you have content that should be rendered in a fixed pitch (typewriter) typeface, use <tt> (for ``teletype'').

Example 4-15. <tt>

Use:

    <p>This document was originally written by
      Nik Clayton, who can be reached by e-mail as
      <tt>nik@FreeBSD.org</tt>.</p>

4.1.4.4. Content size

You can indicate that content should be shown in a larger or smaller font. There are three ways of doing this.

Use <big> and <small> around the content you wish to change size. These tags can be nested, so <big><big>This is much bigger</big></big> is possible.
Use <font> with the size attribute set to +1 or -1 respectively. This has the same effect as using <big> or <small>. However, the use of this approach is deprecated.
Use <font> with the size attribute set to a number between 1 and 7. The default font size is 3. This approach is deprecated.

Example 4-16. <big>, <small>, and <font>

The following fragments all do the same thing.

    <p>This text is <small>slightly smaller</small>.  But
      this text is <big>slightly bigger</big>.</p>
    
    <p>This text is <font size="-1">slightly smaller</font>.  But
      this text is <font size="+1">slightly bigger</font.</p>
    
    <p>This text is <font size="2">slightly smaller</font>.  But
      this text is <font size="4">slightly bigger</font>.</p>

4.1.5. Links

Note: Links are also in-line elements.

4.1.5.1. Linking to other documents on the WWW

In order to include a link to another document on the WWW you must know the URL of the document you want to link to.

The link is indicated with <a>, and the href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of colour, different mouse cursor when over the link, and so on).

Example 4-17. Using <a href="...">

Use:

    <p>More information is available at the
      <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>

These links will take the user to the top of the chosen document.

4.1.5.2. Linking to other parts of documents

Linking to a point within another document (or within the same document) requires that the document author include anchors that you can link to.

Anchors are indicated with <a> and the name attribute instead of href.

Example 4-18. Using <a name="...">

Use:

    <p><a name="para1">This</a> paragraph can be referenced
      in other links with the name <tt>para1</tt>.</p>

To link to a named part of a document, write a normal link to that document, but include the name of the anchor after a # symbol.

Example 4-19. Linking to a named part of another document

Assume that the para1 example resides in a document called foo.html.

    <p>More information can be found in the
      <a href="foo.html#para1">first paragraph</a> of
      <tt>foo.html</tt>.</p>

If you are linking to a named anchor within the same document then you can omit the document's URL, and just include the name of the anchor (with the preceeding #).

Example 4-20. Linking to a named part of the same document

Assume that the para1 example resides in this document

    <p>More information can be found in the
      <a href="#para1">first paragraph</a> of this
      document.</p>