XHTML Markup
Introduction
This chapter describes usage of the XHTML
markup language used for the &os; web site.
XHTML is the XML
version of the HyperText Markup Language, the markup language of
choice on the World Wide Web. More information can be found at
http://www.w3.org/.
XHTML is used to mark up pages on the
&os; web site. It is usually not used to mark up other
documentation, since DocBook offers a far richer set of elements
from which to choose. Consequently, XHTML
pages will normally only be encountered when writing for the web
site.
HTML has gone through a number of
versions. The XML-compliant version
described here is called XHTML. The latest
widespread version is XHTML 1.0, available in
both strict and
transitional variants.
The XHTML DTDs are
available from the Ports Collection in
textproc/xhtml. They are automatically
installed by the textproc/docproj
port.
This is not an exhaustive list of
elements, since that would just repeat the documentation for
XHTML. The aim is to list those elements
most commonly used. Please post questions about elements or
uses not covered here to the &a.doc;.
Inline Versus 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.
Formal Public Identifier (FPI)
There are a number of XHTML
FPIs, depending upon the version, or
level of XHTML to which
a document conforms. Most XHTML documents on
the &os; web site comply with the transitional version of
XHTML 1.0.
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
Sectional Elements
An XHTML document is normally split into
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 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.
Normal XHTML Document
Structure
html xmlns="http://www.w3.org/1999/xhtml"
head
titleThe Document's Titletitle
head
body
…
body
html
Block Elements
Headings
XHTML has tags to denote headings in
the 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.
h1, h2,
and Other Header Tags
Usage:
h1First sectionh1
<!-- Document introduction goes here -->
h2This is the heading for the first sectionh2
<!-- Content for the first section goes here -->
h3This is the heading for the first sub-sectionh3
<!-- Content for the first sub-section goes here -->
h2This is the heading for the second sectionh2
<!-- Content for the second section goes here -->
Generally, an XHTML 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. Do not
leave gaps in the numbering.
Paragraphs
XHTML supports a single paragraph
element, p.
p Example
Usage:
pThis is a paragraph. It can contain just about any
other element.p
Block Quotations
A block quotation is an extended quotation from another
document that will appear in a separate paragraph.
blockquote Example
Usage:
pA small excerpt from the US Constitution:p
blockquoteWe 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
Lists
XHTML can present the user with three
types of lists: ordered, unordered, and definition.
Entries in an ordered list will be numbered, while entries
in an unordered list will be preceded by bullet points.
Definition lists have two sections for each entry. The first
section is the term being defined, and the second section is
the definition.
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.
ul and
ol Example
Usage:
pAn unordered list. Listitems will probably be
preceded by bullets.p
ul
liFirst itemli
liSecond itemli
liThird itemli
ul
pAn ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be
numbered.p
ol
lipThis is the first item. It only has one paragraph.pli
lipThis is the first paragraph of the second item.p
pThis is the second paragraph of the second item.pli
lipThis is the first and only paragraph of the third
item.pli
ol
Definition Lists with dl
Usage:
dl
dtTerm 1dt
ddpParagraph 1 of definition 1.p
pParagraph 2 of definition 1.pdd
dtTerm 2dt
ddpParagraph 1 of definition 2.pdd
dtTerm 3dt
ddpParagraph 1 of definition 3.pdd
dl
Pre-formatted Text
Pre-formatted text is shown to the user exactly as it is
in the file. Text is shown in a fixed font. Multiple spaces
and line breaks are shown exactly as they are in the
file.
Wrap pre-formatted text in the pre
element.
pre Example
For example, the pre tags could be
used to mark up an email message:
pre From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org
Subject: New documentation available
There is a new copy of my primer for contributors to the FreeBSD
Documentation Project available at
<URL:https://people.FreeBSD.org/~nik/primer/index.html>
Comments appreciated.
Npre
Keep in mind that < and
& still are recognized as special
characters in pre-formatted text. This is why the example
shown had to use < instead of
<. For consistency,
> was used in place of
>, too. Watch out for the special
characters that may appear in text copied from a plain-text
source, like an email message or program code.
Tables
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 the pelement is not needed.
Simple Use of table
Usage:
pThis is a simple 2x2 table.p
table
tr
tdTop left celltd
tdTop right celltd
tr
tr
tdBottom left celltd
tdBottom right celltd
tr
table
A cell can span multiple rows and columns by adding the
rowspan or
colspan attributes with
values for the number of rows or columns to be spanned.
Using
rowspan
Usage:
pOne tall thin cell on the left, two short cells next to
it on the right.p
table
tr
td rowspan="2"Long and thintd
tr
tr
tdTop celltd
tdBottom celltd
tr
table
Using
colspan
Usage:
pOne long cell on top, two short cells below it.p
table
tr
td colspan="2"Top celltd
tr
tr
tdBottom left celltd
tdBottom right celltd
tr
table
Using rowspan and
colspan
Together
Usage:
pOn a 3x3 grid, the top left block is a 2x2 set of
cells merged into one. The other cells are normal.p
table
tr
td colspan="2" rowspan="2"Top left large celltd
tdTop right celltd
tr
tr
<!-- Because the large cell on the left merges into
this row, the first <td> will occur on its
right -->
tdMiddle right celltd
tr
tr
tdBottom left celltd
tdBottom middle celltd
tdBottom right celltd
tr
table
In-line Elements
Emphasizing Information
Two levels of emphasis are available in
XHTML, em and
strong. em is for a
normal level of emphasis and strong
indicates stronger emphasis.
em is typically rendered in italic
and strong is rendered in bold. This is
not always the case, and should not be relied upon. According
to best practices, web pages only hold structural and
semantical information, and stylesheets are later applied to
them. Think of semantics, not formatting, when using these
tags.
em and
strong Example
Usage:
pemThisem has been emphasized, while
strongthisstrong has been strongly emphasized.p
Indicating Fixed-Pitch Text
Content that should be rendered in a fixed pitch
(typewriter) typeface is tagged with tt
(for teletype
).
tt Example
Usage:
pMany system settings are stored in
tt/etctt.p
Links
Links are also inline elements.
Linking to Other Documents on the Web
A link points to the URL of a
document on the web. 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, indicated to the
user by showing it in a different color or with an
underline.
Using
a href="..."
Usage:
pMore information is available at the
a href="http://www.&os;.org/"&os; web sitea.p
This link always takes the user to the top of the linked
document.
Linking to Specific Parts of Documents
To link to a specific point within a document, that
document must include an anchor at the
desired point. Anchors are included by setting the
id attribute of an
element to a name. This example creates an anchor by
setting the id
attribute of a p
element.
Creating an Anchor
Usage:
p id="samplepara"This paragraph can be referenced
in other links with the name ttsampleparatt.p
Links to anchors are similar to plain links, but include
a # symbol and the anchor's
ID at the end of the
URL.
Linking to a Named Part of a Different
Document
The samplepara example is part of a
document called foo.html. A link to
that specific paragraph in the document is constructed in
this example.
pMore information can be found in the
a href="foo.html#samplepara"sample paragrapha of
ttfoo.htmltt.p
To link to a named anchor within the same document, omit
the document's URL, and just use the
# symbol followed by the name of the
anchor.
Linking to a Named Part of the Same Document
The samplepara example
resides in this document. To link to it:
pMore information can be found in the
a href="#samplepara"sample paragrapha of this
document.p