diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml | 613 |
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 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><html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title><replaceable>The Document's Title</replaceable></title> + </head> + + <body> + + … + + </body> +</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 + + <URL:http://people.FreeBSD.org/~nik/primer/index.html> + + Comments appreciated. + + N</pre>]]></programlisting> + + <para>Keep in mind that <literal><</literal> and + <literal>&</literal> still are recognized as special + characters in pre-formatted text. This is why the example + shown had to use <literal>&lt;</literal> instead of + <literal><</literal>. For consistency, + <literal>&gt;</literal> was used in place of + <literal>></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><a href="..."></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><a id="..."></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> |