This chapter describes the two 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.
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.
XHTML is the XML version of the HyperText Markup Language, which is the markup language of choice on the World Wide Web. More information can be found at http://www.w3.org/.
XHTML is used to markup pages on the FreeBSD web site. It should not (generally) be used to mark up other documentation, since DocBook offers a far richer set of elements to choose from. Consequently, you will normally only encounter XHTML pages if you are writing for the web site.
HTML has gone through a number of versions, 1, 2, 3.0, 3.2, 4.0 and then an XML-compliant version has also been created, which is called XHTML and the latest widespread version of it is XHTML 1.0(available in both strict and transitional variants).
The XHTML DTDs are available from the Ports Collection
in the textproc/xhtml port.
They are automatically installed as part of the textproc/docproj port.
There are a number of XHTML FPIs, depending upon the version (also known as the level) of XHTML that you want to declare your document to be compliant with.
The majority of XHTML documents on the FreeBSD web site comply with the transitional version of XHTML 1.0.
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 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.
The Document's Title</title>
</head>
<body>
…
</body>
</html>XHTML 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.
h1, h2,
and Other Header TagsUse:
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. Each
h element
should have the same element, but one further up the
hierarchy, preceding it. Leaving gaps in the numbering is
to be avoided.n
hn
ElementsUse:
XHTML supports a single paragraph element,
p.
A block quotation is an extended quotation from another document that should not appear within the current paragraph.
blockquoteUse:
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.
ul and
olUse:
dlUse:
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 into one, and line breaks in the text are significant.
In order to do this, wrap the content in the
pre element.
preYou could use pre to mark up an
email message:
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, e.g., an email message or program
code.
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.
tableUse:
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 or columns that should be
spanned.
rowspanUse:
colspanUse:
rowspan and
colspan TogetherUse:
You have two levels of emphasis available in XHTML,
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. According to best practices, webpages only hold
structural and semantical information and stylesheets are
later applied to use these two so you should think of
semantics not formatting when using these tags.
em and
strongUse:
Links are also inline elements.
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 color, different mouse cursor when
over the link, and so on).
<a href="...">Use:
These links will take the user to the top of the chosen document.
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
id attribute instead of
href.
<a id="...">Use:
To link to a named part of a document, write a normal
link to that document, but include the id of the anchor
after a # symbol.
Assume that the para1 example
resides in a document called
foo.html.
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 preceding
#).
Assume that the para1 example
resides in this document:
This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.