aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/xhtml-markup
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2013-06-23 19:45:12 +0000
committerWarren Block <wblock@FreeBSD.org>2013-06-23 19:45:12 +0000
commit4047241ce668f7a77732b3598250136310d93419 (patch)
tree5fc40d041ad43853e85572f6ad03342853422ea1 /en_US.ISO8859-1/books/fdp-primer/xhtml-markup
parent9b0a5ed979240a403528ec25fd54e3461b3f4a74 (diff)
downloaddoc-4047241ce668f7a77732b3598250136310d93419.tar.gz
doc-4047241ce668f7a77732b3598250136310d93419.zip
Split the old sgml-markup chapter into two chapters, one for XHTML and
one for DocBook. Both are edited and expanded versions of the content from the old chapter.
Notes
Notes: svn path=/head/; revision=42005
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/xhtml-markup')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml613
1 files changed, 613 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
new file mode 100644
index 0000000000..43e0f8adbe
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
@@ -0,0 +1,613 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+ Redistribution and use in source (SGML DocBook) and 'compiled' forms
+ (SGML HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ 1. Redistributions of source code (SGML DocBook) must retain the above
+ copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.
+
+ 2. Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must reproduce
+ the above copyright notice, this list of conditions and the
+ following disclaimer in the documentation and/or other materials
+ provided with the distribution.
+
+ THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+ INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.
+
+ $FreeBSD$
+-->
+
+<chapter id="xhtml-markup">
+ <title><acronym>XHTML</acronym> Markup</title>
+
+ <sect1 id="xhtml-markup-introduction">
+ <title>Introduction</title>
+
+ <para>This chapter describes usage of the <acronym>XHTML</acronym>
+ markup language used for the &os; web site.</para>
+
+ <para><acronym>XHTML</acronym> is the <acronym>XML</acronym>
+ version of the HyperText Markup Language, the markup language of
+ choice on the World Wide Web. More information can be found at
+ <ulink url="http://www.w3.org/"></ulink>.</para>
+
+ <para><acronym>XHTML</acronym> 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, <acronym>XHTML</acronym>
+ pages will normally only be encountered when writing for the web
+ site.</para>
+
+ <para><acronym>HTML</acronym> has gone through a number of
+ versions. The <acronym>XML</acronym>-compliant version
+ described here is called <acronym>XHTML</acronym>. The latest
+ widespread version is <acronym>XHTML</acronym> 1.0, available in
+ both <emphasis>strict</emphasis> and
+ <emphasis>transitional</emphasis> variants.</para>
+
+ <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
+ available from the Ports&nbsp;Collection in
+ <filename role="package">textproc/xhtml</filename>. They are
+ automatically installed as part of the <filename
+ role="package">textproc/docproj</filename> port.</para>
+
+ <note>
+ <para>This is <emphasis>not</emphasis> an exhaustive list of
+ elements, since that would just repeat the documentation for
+ <acronym>XHTML</acronym>. The aim is to list those elements
+ most commonly used. Please post questions about elements or
+ uses not covered here to the &a.doc;.</para>
+ </note>
+
+ <note>
+ <title>Inline Versus Block</title>
+
+ <para>In the remainder of this document, when describing
+ elements, <emphasis>inline</emphasis> means that the element
+ can occur within a block element, and does not cause a line
+ break. A <emphasis>block</emphasis> element, by comparison,
+ will cause a line break (and other processing) when it is
+ encountered.</para>
+ </note>
+ </sect1>
+
+ <sect1 id="xhtml-markup-fpi">
+ <title>Formal Public Identifier (<acronym>FPI</acronym>)</title>
+
+ <para>There are a number of <acronym>XHTML</acronym>
+ <acronym>FPI</acronym>s, depending upon the version, or
+ <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
+ a document conforms. Most XHTML documents on the FreeBSD web
+ site comply with the transitional version of
+ <acronym>XHTML</acronym> 1.0.</para>
+
+ <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
+ </sect1>
+
+ <sect1 id="xhtml-markup-sectional-elements">
+ <title>Sectional Elements</title>
+
+ <para>An <acronym>XHTML</acronym> document is normally split into
+ two sections. The first section, called the
+ <emphasis>head</emphasis>, 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
+ <emphasis>body</emphasis>, contains the content that will be
+ displayed to the user.</para>
+
+ <para>These sections are indicated with <sgmltag>head</sgmltag>
+ and <sgmltag>body</sgmltag> elements respectively. These
+ elements are contained within the top-level
+ <sgmltag>html</sgmltag> element.</para>
+
+ <example>
+ <title>Normal <acronym>XHTML</acronym> Document
+ Structure</title>
+
+ <programlisting>&lt;html xmlns="http://www.w3.org/1999/xhtml">
+ &lt;head>
+ &lt;title><replaceable>The Document's Title</replaceable>&lt;/title>
+ &lt;/head>
+
+ &lt;body>
+
+ &hellip;
+
+ &lt;/body>
+&lt;/html></programlisting>
+ </example>
+ </sect1>
+
+ <sect1 id="xhtml-markup-block-elements">
+ <title>Block Elements</title>
+
+ <sect2 id="xhtml-markup-block-elements-headings">
+ <title>Headings</title>
+
+ <para><acronym>XHTML</acronym> has tags to denote headings in
+ the document at up to six different levels.</para>
+
+ <para>The largest and most prominent heading is
+ <sgmltag>h1</sgmltag>, then <sgmltag>h2</sgmltag>,
+ continuing down to <sgmltag>h6</sgmltag>.</para>
+
+ <para>The element's content is the text of the heading.</para>
+
+ <example>
+ <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>,
+ and Other Header Tags</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<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 -->]]></programlisting>
+ </example>
+
+ <para>Generally, an <acronym>XHTML</acronym> page should have
+ one first level heading (<sgmltag>h1</sgmltag>). This can
+ contain many second level headings (<sgmltag>h2</sgmltag>),
+ which can in turn contain many third level headings. Each
+ <sgmltag>h<replaceable>n</replaceable></sgmltag> element
+ should have the same element, but one further up the
+ hierarchy, preceding it. Leaving gaps in the numbering is to
+ be avoided.</para>
+
+ <example>
+ <title>Bad Ordering of
+ <sgmltag>h<replaceable>n</replaceable></sgmltag>
+ Elements</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<h1>First section</h1>
+
+<!-- Document introduction -->
+
+<h3>Sub-section</h3>
+
+<!-- This is bad, <h2> has been left out -->]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-paragraphs">
+ <title>Paragraphs</title>
+
+ <para><acronym>XHTML</acronym> supports a single paragraph
+ element, <sgmltag>p</sgmltag>.</para>
+
+ <example>
+ <title><sgmltag>p</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any
+ other element.</p>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-block-quotations">
+ <title>Block Quotations</title>
+
+ <para>A block quotation is an extended quotation from another
+ document that should not appear within the current
+ paragraph.</para>
+
+ <example>
+ <title><sgmltag>blockquote</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<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>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-lists">
+ <title>Lists</title>
+
+ <para><acronym>XHTML</acronym> can present the user with three
+ types of lists: ordered, unordered, and definition.</para>
+
+ <para>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.</para>
+
+ <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
+ element, unordered lists by the <sgmltag>ul</sgmltag>
+ element, and definition lists by the <sgmltag>dl</sgmltag>
+ element.</para>
+
+ <para>Ordered and unordered lists contain listitems, indicated
+ by the <sgmltag>li</sgmltag> element. A listitem can
+ contain textual content, or it may be further wrapped in one
+ or more <sgmltag>p</sgmltag> elements.</para>
+
+ <para>Definition lists contain definition terms
+ (<sgmltag>dt</sgmltag>) and definition descriptions
+ (<sgmltag>dd</sgmltag>). A definition term can only contain
+ inline elements. A definition description can contain other
+ block elements.</para>
+
+ <example>
+ <title><sgmltag>ul</sgmltag> and
+ <sgmltag>ol</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>An unordered list. Listitems will probably be
+ preceded 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>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Definition Lists with <sgmltag>dl</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<dl>
+ <dt>Term 1</dt>
+
+ <dd><p>Paragraph 1 of definition 1.</p>
+
+ <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><p>Paragraph 1 of definition 3.</p></dd>
+</dl>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-preformatted-text">
+ <title>Pre-formatted Text</title>
+
+ <para>Pre-formatted text can 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.</para>
+
+ <para>In order to do this, wrap the content in the
+ <sgmltag>pre</sgmltag> element.</para>
+
+ <example>
+ <title><sgmltag>pre</sgmltag></title>
+
+ <para>For example, the <sgmltag>pre</sgmltag> tags could be
+ used to mark up an email message:</para>
+
+ <programlisting><![CDATA[<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
+
+ &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;
+
+ Comments appreciated.
+
+ N</pre>]]></programlisting>
+
+ <para>Keep in mind that <literal>&lt;</literal> and
+ <literal>&amp;</literal> still are recognized as special
+ characters in pre-formatted text. This is why the example
+ shown had to use <literal>&amp;lt;</literal> instead of
+ <literal>&lt;</literal>. For consistency,
+ <literal>&amp;gt;</literal> was used in place of
+ <literal>&gt;</literal>, 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.</para>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-block-elements-tables">
+ <title>Tables</title>
+
+ <para>Mark up tabular information using the
+ <sgmltag>table</sgmltag> element. A table consists of one or
+ more table rows (<sgmltag>tr</sgmltag>), each containing one
+ or more cells of table data (<sgmltag>td</sgmltag>). 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 <sgmltag>p</sgmltag>element is not needed.</para>
+
+ <example>
+ <title>Simple Use of <sgmltag>table</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<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>]]></programlisting>
+ </example>
+
+ <para>A cell can span multiple rows and columns. To indicate
+ this, add the <literal>rowspan</literal> and/or
+ <literal>colspan</literal> attributes, with values indicating
+ the number of rows or columns that should be spanned.</para>
+
+ <example>
+ <title>Using <literal>rowspan</literal></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<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>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Using <literal>colspan</literal></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<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>]]></programlisting>
+ </example>
+
+ <example>
+ <title>Using <literal>rowspan</literal> and
+ <literal>colspan</literal> Together</title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>On 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 cell</td>
+
+ <td>Top right cell</td>
+ </tr>
+
+ <tr>
+ <!-- Because the large cell on the left merges into
+ 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>]]></programlisting>
+ </example>
+ </sect2>
+ </sect1>
+
+ <sect1 id="xhtml-markup-inline-elements">
+ <title>In-line Elements</title>
+
+ <sect2 id="xhtml-markup-inline-elements-emphasizing-information">
+ <title>Emphasizing Information</title>
+
+ <para>Two levels of emphasis are available in
+ <acronym>XHTML</acronym>, <sgmltag>em</sgmltag> and
+ <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a
+ normal level of emphasis and <sgmltag>strong</sgmltag>
+ indicates stronger emphasis.</para>
+
+ <para>Typically, <sgmltag>em</sgmltag> is rendered in italic
+ and <sgmltag>strong</sgmltag> is rendered in bold. This is
+ not always the case, however, and should not be relied upon.
+ According to best practices, webpages only hold structural and
+ semantical information and stylesheets are later applied to
+ them. Think of semantics, not formatting, when using these
+ tags.</para>
+
+ <example>
+ <title><sgmltag>em</sgmltag> and
+ <sgmltag>strong</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p><em>This</em> has been emphasized, while
+ <strong>this</strong> has been strongly emphasized.</p>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-inline-elements-fixed-pitch-text">
+ <title>Indicating Fixed-Pitch Text</title>
+
+ <para>Content that should be rendered in a fixed pitch
+ (typewriter) typeface is tagged with <sgmltag>tt</sgmltag>
+ (for <quote>teletype</quote>).</para>
+
+ <example>
+ <title><sgmltag>tt</sgmltag></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>This document was originally written by
+ Nik Clayton, who can be reached by email as
+ <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="xhtml-markup-inline-elements-links">
+ <title>Links</title>
+
+ <note>
+ <para>Links are also inline elements.</para>
+ </note>
+
+ <sect3 id="xhtml-markup-inline-elements-linking">
+ <title>Linking to Other Documents on the Web</title>
+
+ <para>A link points to the <acronym>URL</acronym> of another
+ document on the web. The link is indicated with
+ <sgmltag>a</sgmltag>, and the <literal>href</literal>
+ attribute contains the <acronym>URL</acronym> of the target
+ document. The content of the element becomes the link, and
+ is normally indicated to the user in some way,
+ typically by a different color or underlining.</para>
+
+ <example>
+ <title>Using <literal>&lt;a href="..."&gt;</literal></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p>More information is available at the
+ <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting>
+ </example>
+
+ <para>These links will take the user to the top of the chosen
+ document.</para>
+ </sect3>
+
+ <sect3 id="xhtml-markup-inline-elements-other-parts">
+ <title>Linking to Other Parts of Documents</title>
+
+ <para>Linking to a point within another document, or within
+ the same document, requires that the document author include
+ <emphasis>anchors</emphasis>. Anchors are indicated with
+ <sgmltag>a</sgmltag> and the <literal>id</literal> attribute
+ instead of <literal>href</literal>.</para>
+
+ <example>
+ <title>Using <literal>&lt;a id="..."&gt;</literal></title>
+
+ <para>Usage:</para>
+
+ <programlisting><![CDATA[<p><a id="para1">This</a> paragraph can be referenced
+ in other links with the name <tt>para1</tt>.</p>]]></programlisting>
+ </example>
+
+ <para>To link to a named part of a document, write a normal
+ link to that document, but include the <acronym>ID</acronym>
+ of the anchor after a <literal>#</literal> symbol.</para>
+
+ <example>
+ <title>Linking to a Named Part of Another Document</title>
+
+ <para>Assume that the <literal>para1</literal> example
+ resides in a document called
+ <filename>foo.html</filename>.</para>
+
+ <programlisting><![CDATA[<p>More information can be found in the
+ <a href="foo.html#para1">first paragraph</a> of
+ <tt>foo.html</tt>.</p>]]></programlisting>
+ </example>
+
+ <para>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
+ <literal>#</literal>).</para>
+
+ <example>
+ <title>Linking to a Named Part of the Same Document</title>
+
+ <para>Assume that the <literal>para1</literal> example
+ resides in this document:</para>
+
+ <programlisting><![CDATA[<p>More information can be found in the
+ <a href="#para1">first paragraph</a> of this
+ document.</p>]]></programlisting>
+ </example>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>