diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml | 142 |
1 files changed, 40 insertions, 102 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 8f00e11b6b..14070de750 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -31,8 +31,8 @@ $FreeBSD$ --> -<chapter id="sgml-markup"> - <title>SGML Markup</title> +<chapter id="xml-markup"> + <title>XML Markup</title> <para>This chapter describes the two markup languages you will encounter when you contribute to the FreeBSD documentation @@ -63,46 +63,49 @@ line break (and other processing) when it is encountered.</para> </note> - <sect1 id="sgml-markup-html"> - <title>HTML</title> + <sect1 id="xml-markup-xhtml"> + <title>XHTML</title> - <para>HTML, the HyperText Markup Language, is the markup language + <para>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 <ulink url="http://www.w3.org/"></ulink>.</para> - <para>HTML is used to markup pages on the FreeBSD web site. It + <para>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 HTML pages + from. Consequently, you will normally only encounter XHTML pages if you are writing for the web site.</para> <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, - and the latest, 4.0 (available in both - <emphasis>strict</emphasis> and <emphasis>loose</emphasis> + 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 + <emphasis>strict</emphasis> and <emphasis>transitional</emphasis> variants).</para> - <para>The HTML DTDs are available from the Ports Collection - in the <filename role="package">textproc/html</filename> port. + <para>The XHTML DTDs are available from the Ports Collection + in the <filename role="package">textproc/xhtml</filename> port. They are automatically installed as part of the <filename role="package">textproc/docproj</filename> port.</para> <sect2> <title>Formal Public Identifier (FPI)</title> - <para>There are a number of HTML FPIs, depending upon the - version (also known as the level) of HTML that you want to + <para>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.</para> - <para>The majority of HTML documents on the FreeBSD web site - comply with the loose version of HTML 4.0.</para> + <para>The majority of XHTML documents on the FreeBSD web site + comply with the transitional version of XHTML 1.0.</para> - <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> </sect2> <sect2> <title>Sectional Elements</title> - <para>An HTML document is normally split into two sections. The + <para>An XHTML 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 @@ -115,9 +118,9 @@ <sgmltag>html</sgmltag> element.</para> <example> - <title>Normal HTML Document Structure</title> + <title>Normal XHTML Document Structure</title> - <programlisting><html> + <programlisting><html xmlns="http://www.w3.org/1999/xhtml"> <head> <title><replaceable>The Document's Title</replaceable></title> </head> @@ -137,7 +140,7 @@ <sect3> <title>Headings</title> - <para>HTML allows you to denote headings in your document, at + <para>XHTML allows you to denote headings in your document, at up to six different levels.</para> <para>The largest and most prominent heading is @@ -169,7 +172,7 @@ <!-- Content for the second section goes here -->]]></programlisting> </example> - <para>Generally, an HTML page should have one first level + <para>Generally, an HXTML 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 @@ -198,7 +201,7 @@ <sect3> <title>Paragraphs</title> - <para>HTML supports a single paragraph element, + <para>XHTML supports a single paragraph element, <sgmltag>p</sgmltag>.</para> <example> @@ -493,7 +496,7 @@ <sect3> <title>Emphasizing Information</title> - <para>You have two levels of emphasis available in HTML, + <para>You have two levels of emphasis available in XHTML, <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal level of emphasis and <sgmltag>strong</sgmltag> indicates stronger @@ -502,7 +505,10 @@ <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 you should not rely on - it.</para> + 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.</para> <example> <title><sgmltag>em</sgmltag> and @@ -516,22 +522,6 @@ </sect3> <sect3> - <title>Bold and Italics</title> - - <para>Because HTML includes presentational markup, you can - also indicate that particular content should be rendered in - bold or italic. The elements are <sgmltag>b</sgmltag> and - <sgmltag>i</sgmltag> respectively.</para> - - <example> - <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> - - <programlisting><![CDATA[<p><b>This</b> is in bold, while <i>this</i> is - in italics.</p>]]></programlisting> - </example> - </sect3> - - <sect3> <title>Indicating Fixed-Pitch Text</title> <para>If you have content that should be rendered in a fixed @@ -548,65 +538,13 @@ <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> </example> </sect3> - - <sect3> - <title>Content Size</title> - - <para>You can indicate that content should be shown in a - larger or smaller font. There are three ways of doing - this.</para> - - <orderedlist> - <listitem> - <para>Use <sgmltag>big</sgmltag> and - <sgmltag>small</sgmltag> around the content you wish to - change size. These tags can be nested, so - <literal><big><big>This is much - bigger</big></big></literal> is - possible.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the - <literal>size</literal> attribute set to - <literal>+1</literal> or <literal>-1</literal> - respectively. This has the same effect as using - <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. - However, the use of this approach is deprecated.</para> - </listitem> - - <listitem> - <para>Use <sgmltag>font</sgmltag> with the - <literal>size</literal> attribute set to a number - between <literal>1</literal> and <literal>7</literal>. - The default font size is <literal>3</literal>. This - approach is deprecated.</para> - </listitem> - </orderedlist> - - <example> - <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and - <sgmltag>font</sgmltag></title> - - <para>The following fragments all do the same thing.</para> - - <programlisting><![CDATA[<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>]]></programlisting> - </example> - </sect3> </sect2> <sect2> <title>Links</title> <note> - <para>Links are also in-line elements.</para> + <para>Links are also inline elements.</para> </note> <sect3> @@ -644,20 +582,20 @@ anchors that you can link to.</para> <para>Anchors are indicated with <sgmltag>a</sgmltag> and the - <literal>name</literal> attribute instead of + <literal>id</literal> attribute instead of <literal>href</literal>.</para> <example> - <title>Using <literal><a name="..."></literal></title> + <title>Using <literal><a id="..."></literal></title> <para>Use:</para> - <programlisting><![CDATA[<p><a name="para1">This</a> paragraph can be referenced + <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 name of the anchor + link to that document, but include the id of the anchor after a <literal>#</literal> symbol.</para> <example> @@ -691,7 +629,7 @@ </sect2> </sect1> - <sect1 id="sgml-markup-docbook"> + <sect1 id="xml-markup-docbook"> <title>DocBook</title> <para>DocBook was originally developed by HaL Computer Systems and @@ -703,7 +641,7 @@ Since 1998 it is maintained by the <ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> DocBook Technical Committee</ulink>. As such, and unlike - LinuxDoc and HTML, DocBook is very heavily oriented towards + LinuxDoc and XHTML, DocBook is very heavily oriented towards markup that describes <emphasis>what</emphasis> something is, rather than describing <emphasis>how</emphasis> it should be presented.</para> @@ -760,7 +698,7 @@ for DocBook customizations, the FPI for the FreeBSD extended DocBook DTD is:</para> - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting> + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> </sect2> <sect2> @@ -1804,7 +1742,7 @@ This is the file called 'foo2'</screen> manual page section.</para> <para>This can be cumbersome to write, and so a series of - <link linkend="sgml-primer-general-entities">general + <link linkend="xml-primer-general-entities">general entities</link> have been created to make this easier. Each entity takes the form <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> @@ -2568,7 +2506,7 @@ IMAGES+= fig3.png <para>You must be careful when you separate your documentation into smaller files (see - <xref linkend="sgml-primer-include-using-gen-entities"/>) in + <xref linkend="xml-primer-include-using-gen-entities"/>) in different directories.</para> <para>Suppose you have a book with three chapters, and the |