diff options
Diffstat (limited to 'en_US.ISO8859-1')
10 files changed, 401 insertions, 573 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml index 097f3af6a6..bb03eb46df 100644 --- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml @@ -46,7 +46,7 @@ <listitem> <para>Know what you need to build the FDP documentation, in addition to those mentioned in the - <link linkend="tools">SGML tools chapter</link>.</para> + <link linkend="tools">XML tools chapter</link>.</para> </listitem> <listitem> diff --git a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml index eaa899d2ae..82c3ff7fb7 100644 --- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml @@ -34,7 +34,7 @@ <appendix id="examples"> <title>Examples</title> - <para>This appendix contains example SGML files and command lines + <para>This appendix contains example XML files and command lines you can use to convert them from one output format to another. If you have successfully installed the Documentation Project tools then you should be able to use these examples directly.</para> @@ -42,7 +42,7 @@ <para>These examples are not exhaustive—they do not contain all the elements you might want to use, particularly in your document's front matter. For more examples of DocBook markup you - should examine the SGML source for this and other documents, + should examine the XML source for this and other documents, available in the <application>svn</application> <literal>doc</literal> repository, or available online starting at <ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>.</para> @@ -60,7 +60,8 @@ <example> <title>DocBook <sgmltag>book</sgmltag></title> - <programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + <programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <book lang='en'> <bookinfo> @@ -112,7 +113,8 @@ <example> <title>DocBook <sgmltag>article</sgmltag></title> - <programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + <programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <article lang='en'> <articleinfo> @@ -269,7 +271,7 @@ <example id="examples-docbook-postscript"> <title>Converting DocBook to Postscript</title> - <para>The source SGML file must be converted to a &tex; + <para>The source XML file must be converted to a &tex; file.</para> <screen>&prompt.user; <userinput>jade -V tex-backend \ <co id="examples-co-jade-3-tex-backend"/> diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml index 931dba3ff1..ad64e28d31 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -63,7 +63,7 @@ </listitem> <listitem> - <para>Be able to read and understand the SGML source code for + <para>Be able to read and understand the XML source code for the documentation maintained by the FDP.</para> </listitem> diff --git a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml index 884613e0f1..ea6d299b49 100644 --- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml @@ -35,7 +35,7 @@ <title>See Also</title> <para>This document is deliberately not an exhaustive discussion of - SGML, the DTDs listed, and the FreeBSD Documentation Project. For + XML, the DTDs listed, and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites.</para> @@ -55,20 +55,13 @@ </itemizedlist> </sect1> - <sect1 id="see-also-sgml"> - <title>SGML</title> + <sect1 id="see-also-xml"> + <title>XML</title> <itemizedlist> <listitem> - <para><ulink url="http://www.oasis-open.org/cover/">The - SGML/XML web page</ulink>, a comprehensive SGML - resource</para> - </listitem> - - <listitem> - <para><ulink - url="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">Gentle - introduction to SGML</ulink></para> + <para><ulink url="http://www.w3.org/XML/">W3C's XML page + SGML/XML web page</ulink></para> </listitem> </itemizedlist> </sect1> 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 diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml index 933f9ed2a2..3f8473be14 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -31,20 +31,20 @@ $FreeBSD$ --> -<chapter id="sgml-primer"> - <title>SGML Primer</title> +<chapter id="xml-primer"> + <title>XML Primer</title> <para>The majority of FDP documentation is written in applications - of SGML. This chapter explains exactly what that means, how to + of XML. This chapter explains exactly what that means, how to read and understand the source to the documentation, and the sort - of SGML tricks you will see used in the documentation.</para> + of XML tricks you will see used in the documentation.</para> <para>Portions of this section were inspired by Mark Galassi's <ulink url="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para> - <sect1 id="sgml-primer-overview"> + <sect1 id="xml-primer-overview"> <title>Overview</title> <para>Way back when, electronic text was simple to deal with. @@ -127,26 +127,28 @@ is a first language that you use to write these other markup languages. A <emphasis>meta markup language</emphasis>.</para> - <para>This is exactly what the Standard Generalized Markup - Language (SGML) is. Many markup languages have been written in - SGML, including the two most used by the FDP, HTML and + <para>This is exactly what the eXtensible Markup + Language (XML) is. Many markup languages have been written in + XML, including the two most used by the FDP, XHTML and DocBook.</para> - <para>Each language definition is more properly called a Document - Type Definition (DTD). The DTD specifies the name of the - elements that can be used, what order they appear in (and + <para>Each language definition is more properly called a grammar, + vocabulary, schema or Document Type Definition (DTD). There + are various languages to specify an XML grammar, for example, + DTD (yes, it also means the specification language itself), + XML Schema (XSD) or RELANG NG. The schema specifies the name + of the elements that can be used, what order they appear in (and whether some markup can be used inside other markup) and related - information. A DTD is sometimes referred to as an - <emphasis>application</emphasis> of SGML.</para> + information.</para> - <para id="sgml-primer-validating">A DTD is a + <para id="xml-primer-validating">A schema is a <emphasis>complete</emphasis> specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so - forth. This makes it possible to write an SGML - <emphasis>parser</emphasis> which reads in both the DTD and a - document which claims to conform to the DTD. The parser can - then confirm whether or not all the elements required by the DTD + forth. This makes it possible to write an XML + <emphasis>parser</emphasis> which reads in both the schema and a + document which claims to conform to the schema. The parser can + then confirm whether or not all the elements required by the vocabulary are in the document in the right order, and whether there are any errors in the markup. This is normally referred to as <quote>validating the document</quote>.</para> @@ -154,27 +156,27 @@ <note> <para>This processing simply confirms that the choice of elements, their ordering, and so on, conforms to that listed - in the DTD. It does <emphasis>not</emphasis> check that you + in the grammar. It does <emphasis>not</emphasis> check that you have used <emphasis>appropriate</emphasis> markup for the content. If you tried to mark up all the filenames in your document as function names, the parser would not flag this as - an error (assuming, of course, that your DTD defines elements + an error (assuming, of course, that your schema defines elements for filenames and functions, and that they are allowed to appear in the same place).</para> </note> <para>It is likely that most of your contributions to the Documentation Project will consist of content marked up in - either HTML or DocBook, rather than alterations to the DTDs. + either XHTML or DocBook, rather than alterations to the schemas. For this reason this book will not touch on how to write a - DTD.</para> + vocabulary.</para> </sect1> - <sect1 id="sgml-primer-elements"> + <sect1 id="xml-primer-elements"> <title>Elements, Tags, and Attributes</title> - <para>All the DTDs written in SGML share certain characteristics. - This is hardly surprising, as the philosophy behind SGML will + <para>All the vocabularies written in XML share certain characteristics. + This is hardly surprising, as the philosophy behind XML will inevitably show through. One of the most obvious manifestations of this philosophy is that of <emphasis>content</emphasis> and <emphasis>elements</emphasis>.</para> @@ -201,20 +203,20 @@ character names, and so on.</para> <para>Notice how you can make this differentiation between - different elements of the content without resorting to any SGML + different elements of the content without resorting to any XML terms. It really is surprisingly straightforward. You could do this with a highlighter pen and a printout of the book, using different colors to indicate different chunks of content.</para> <para>Of course, we do not have an electronic highlighter pen, so we need some other way of indicating which element each piece of - content belongs to. In languages written in SGML (HTML, + content belongs to. In languages written in XML (XHTML, DocBook, et al) this is done by means of <emphasis>tags</emphasis>.</para> <para>A tag is used to identify where a particular element starts, and where the element ends. <emphasis>The tag is not part of - the element itself</emphasis>. Because each DTD was normally + the element itself</emphasis>. Because each grammar was normally written to mark up specific types of information, each one will recognize different elements, and will therefore have different names for the tags.</para> @@ -229,10 +231,9 @@ <example> <title>Using an Element (Start and End Tags)</title> - <para>HTML has an element for indicating that the content + <para>XHTML has an element for indicating that the content enclosed by the element is a paragraph, called - <sgmltag>p</sgmltag>. This element has both start and end - tags.</para> + <sgmltag>p</sgmltag>.</para> <programlisting><![CDATA[<p>This is a paragraph. It starts with the start tag for the 'p' element, and it will end with the end tag for the 'p' @@ -241,22 +242,35 @@ <p>This is another paragraph. But this one is much shorter.</p>]]></programlisting> </example> - <para>Not all elements require an end tag. Some elements have no - content. For example, in HTML you can indicate that you want a - horizontal line to appear in the document. Obviously, this line - has no content, so just the start tag is required for this - element.</para> + <para>Some elements have no + content. For example, in XHTML you can indicate that you want a + horizontal line to appear in the document.</para> + + <para>For such elements, that have no content at all, XML introduced + a shorthand form, which is ccompletely equivalent to the above + form:</para> + + <programlisting><![CDATA[<hr/>]]></programlisting> <example> - <title>Using an Element (Start Tag Only)</title> + <title>Using an Element (Without Content)</title> - <para>HTML has an element for indicating a horizontal rule, + <para>XHTML has an element for indicating a horizontal rule, called <sgmltag>hr</sgmltag>. This element does not wrap - content, so only has a start tag.</para> + content, so it looks like this.</para> + + <programlisting><![CDATA[<p>One paragraph.</p> +<hr></hr> - <programlisting><![CDATA[<p>This is a paragraph.</p> +<p>This is another paragraph. A horizontal rule separates this + from the previous paragraph.</p>]]></programlisting> -<hr> + <para>For such elements, that have no content at all, XML introduced + a shorthand form, which is ccompletely equivalent to the above + form:</para> + + <programlisting><![CDATA[<p>One paragraph.</p> +<hr/> <p>This is another paragraph. A horizontal rule separates this from the previous paragraph.</p>]]></programlisting> @@ -274,7 +288,7 @@ of the <em>words</em> have been <em>emphasized</em>.</p>]]></programlisting> </example> - <para>The DTD will specify the rules detailing which elements can + <para>The grammar will specify the rules detailing which elements can contain other elements, and exactly what they can contain.</para> @@ -288,7 +302,7 @@ element starts and end.</para> <para>When this document (or anyone else knowledgeable about - SGML) refers to <quote>the <sgmltag>p</sgmltag> tag</quote> + XML) refers to <quote>the <sgmltag>p</sgmltag> tag</quote> they mean the literal text consisting of the three characters <literal><</literal>, <literal>p</literal>, and <literal>></literal>. But the phrase <quote>the @@ -310,11 +324,11 @@ take the form <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> - <para>In sufficiently recent versions of HTML, the + <para>In XHTML, the <sgmltag>p</sgmltag> element has an attribute called <sgmltag>align</sgmltag>, which suggests an alignment (justification) for the paragraph to the program displaying the - HTML.</para> + XHTML.</para> <para>The <literal>align</literal> attribute can take one of four defined values, <literal>left</literal>, @@ -333,9 +347,7 @@ <para>Some attributes will only take specific values, such as <literal>left</literal> or <literal>justify</literal>. Others - will allow you to enter anything you want. If you need to - include quotes (<literal>"</literal>) within an attribute then - use single quotes around the attribute value.</para> + will allow you to enter anything you want.</para> <example> <title>Single Quotes Around Attributes</title> @@ -343,16 +355,17 @@ <programlisting><![CDATA[<p align='right'>I am on the right!</p>]]></programlisting> </example> - <para>Sometimes you do not need to use quotes around attribute - values at all. However, the rules for doing this are subtle, - and it is far simpler just to <emphasis>always</emphasis> quote - your attribute values.</para> + <para>XML requires you to quote each attribute value with either + single or double quotes. It is more habitual to use double quotes + but you may use single quotes, as well. Using single quotes is + practical if you want to include double quotes in the attribute + value.</para> <para>The information on attributes, elements, and tags is stored - in SGML catalogs. The various Documentation Project tools use + in XML catalogs. The various Documentation Project tools use these catalog files to validate your work. The tools in <filename role="package">textproc/docproj</filename> include a - variety of SGML catalog files. The FreeBSD Documentation + variety of XML catalog files. The FreeBSD Documentation Project includes its own set of catalog files. Your tools need to know about both sorts of catalog files.</para> @@ -380,7 +393,7 @@ to substitute the correct directory for your language.)</para> - <example id="sgml-primer-envars"> + <example id="xml-primer-envars"> <title><filename>.profile</filename>, for &man.sh.1; and &man.bash.1; Users</title> @@ -415,14 +428,14 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATA <procedure> <step> - <para>Create <filename>example.sgml</filename>, and enter + <para>Create <filename>example.xml</filename>, and enter the following text:</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html> +<html xmlns="http://www.w3.org/1999/xhtml"> <head> - <title>An Example HTML File</title> + <title>An Example XHTML File</title> </head> <body> @@ -436,30 +449,20 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATA </step> <step> - <para>Try to validate this file using an SGML parser.</para> + <para>Try to validate this file using an XML parser.</para> <para>Part of <filename role="package">textproc/docproj</filename> is - the <command>onsgmls</command> - <link linkend="sgml-primer-validating">validating - parser</link>. Normally, <command>onsgmls</command> - reads in a document marked up according to an SGML DTD and - returns a copy of the document's Element Structure - Information Set (ESIS, but that is not important right - now).</para> - - <para>However, when <command>onsgmls</command> is given the - <option>-s</option> parameter, <command>onsgmls</command> - will suppress its normal output, and just print error - messages. This makes it a useful way to check to see if - your document is valid or not.</para> - - <para>Use <command>onsgmls</command> to check that your - document is valid:</para> - - <screen>&prompt.user; <userinput>onsgmls -s example.sgml</userinput></screen> - - <para>As you will see, <command>onsgmls</command> returns + the <command>xmllint</command> + <link linkend="xml-primer-validating">validating + parser</link>.</para> + + <para>Use <command>xmllint</command> in the following way to + check that your document is valid:</para> + + <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput></screen> + + <para>As you will see, <command>xmllint</command> returns without displaying any output. This means that your document validated successfully.</para> </step> @@ -470,91 +473,18 @@ setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATA <sgmltag>/title</sgmltag> tags, and re-run the validation.</para> - <screen>&prompt.user; <userinput>onsgmls -s example.sgml</userinput> -onsgmls:example.sgml:5:4:E: character data is not allowed here -onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> - - <para>The error output from <command>onsgmls</command> is - organized into colon-separated groups, or columns.</para> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="2"> - <thead> - <row> - <entry>Column</entry> - <entry>Meaning</entry> - </row> - </thead> - - <tbody> - <row> - <entry>1</entry> - <entry>The name of the program generating the error. - This will always be - <literal>onsgmls</literal>.</entry> - </row> - - <row> - <entry>2</entry> - <entry>The name of the file that contains the - error.</entry> - </row> - - <row> - <entry>3</entry> - <entry>Line number where the error appears.</entry> - </row> - - <row> - <entry>4</entry> - <entry>Column number where the error - appears.</entry> - </row> - - <row> - <entry>5</entry> - - <entry>A one letter code indicating the nature of - the message. <literal>I</literal> indicates an - informational message, <literal>W</literal> is for - warnings, and <literal>E</literal> is for errors - <footnote><para>It is not always the fifth column - either. <command>onsgmls -sv</command> - displays <literal>onsgmls:I: "OpenSP" version - "1.5.2"</literal> (depending on the - installed version). As you can see, this is - an informational message.</para></footnote>, - and <literal>X</literal> is for - cross-references. As you can see, these messages - are errors.</entry> - </row> - - <row> - <entry>6</entry> - <entry>The text of the message.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para>Simply omitting the <sgmltag>title</sgmltag> tags has - generated 2 different errors.</para> - - <para>The first error indicates that content (in this case, - characters, rather than the start tag for an element) has - occurred where the SGML parser was expecting something - else. In this case, the parser was expecting to see one - of the start tags for elements that are valid inside - <sgmltag>head</sgmltag> (such as - <sgmltag>title</sgmltag>).</para> - - <para>The second error is because <sgmltag>head</sgmltag> - elements <emphasis>must</emphasis> contain a - <sgmltag>title</sgmltag> element. Because it does not - <command>onsgmls</command> considers that the element has - not been properly finished. However, the closing tag - indicates that the element has been closed before it has - been finished.</para> + <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput> +example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen> + + <para>This line tells you that the validation error comes from + the <replaceable>fifth</replaceable> line of the + <replaceable>example.xml</replaceable> file and that the + content of the <sgmltag>head</sgmltag> is the part, which + does not follow the rules described by the XHTML grammar.</para> + + <para>Below this line <command>xmllint</command> will show you + the line where the error has been found and will also mark the + exact character position with a ^ sign.</para> </step> <step> @@ -565,21 +495,20 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> </sect2> </sect1> - <sect1 id="sgml-primer-doctype-declaration"> + <sect1 id="xml-primer-doctype-declaration"> <title>The DOCTYPE Declaration</title> - <para>The beginning of each document that you write must specify - the name of the DTD that the document conforms to. This is so - that SGML parsers can determine the DTD and ensure that the - document does conform to it.</para> - - <para>This information is generally expressed on one line, in the - DOCTYPE declaration.</para> + <para>The beginning of each document that you write may specify + the name of the DTD that the document conforms to in case you use + the DTD specification language. Other specification languages, like + XML Schema and RELAX NG are not referred in the source document. + This DOCTYPE declaration serves the XML parsers so that they can + determine the DTD and ensure that the document does conform to it.</para> <para>A typical declaration for a document written to conform with - version 4.0 of the HTML DTD looks like this:</para> + version 1.0 of the XHTML DTD looks like this:</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">]]></programlisting> <para>That line contains a number of different components.</para> @@ -589,7 +518,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <listitem> <para>Is the <emphasis>indicator</emphasis> that indicates - that this is an SGML declaration. This line is declaring + that this is an XML declaration. This line is declaring the document type.</para> </listitem> </varlistentry> @@ -598,7 +527,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <term><literal>DOCTYPE</literal></term> <listitem> - <para>Shows that this is an SGML declaration for the + <para>Shows that this is an XML declaration for the document type.</para> </listitem> </varlistentry> @@ -608,29 +537,36 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <listitem> <para>Names the first - <link linkend="sgml-primer-elements">element</link> that + <link linkend="xml-primer-elements">element</link> that will appear in the document.</para> </listitem> </varlistentry> <varlistentry> - <term><literal>PUBLIC "-//W3C//DTD HTML - 4.0//EN"</literal></term> + <term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> <listitem> <para>Lists the Formal Public Identifier (FPI) <indexterm> <primary>Formal Public Identifier</primary> </indexterm> - for the DTD that this document conforms to. Your SGML + for the DTD that this document conforms to. Your XML parser will use this to find the correct DTD when processing this document.</para> <para><literal>PUBLIC</literal> is not a part of the FPI, - but indicates to the SGML processor how to find the DTD - referenced in the FPI. Other ways of telling the SGML + but indicates to the XML processor how to find the DTD + referenced in the FPI. Other ways of telling the XML parser how to find the DTD are shown <link - linkend="sgml-primer-fpi-alternatives">later</link>.</para> + linkend="xml-primer-fpi-alternatives">later</link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> + + <listitem> + <para>A local filename or an URL to find the DTD.</para> </listitem> </varlistentry> @@ -651,7 +587,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <note> <para>You do not need to know this, but it is useful - background, and might help you debug problems when your SGML + background, and might help you debug problems when your XML processor can not locate the DTD you are using.</para> </note> @@ -673,7 +609,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> Symbols//EN"</literal> lists <literal>ISO 8879:1986</literal> as being the owner for the set of entities for Greek symbols. ISO 8879:1986 is - the ISO number for the SGML standard.</para> + the ISO number for the SGML standard, the predecessor + (and a superset) of XML.</para> <para>Otherwise, this string will either look like <literal>-//<replaceable>Owner</replaceable></literal> @@ -715,7 +652,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> used only for DTD files, <literal>ELEMENT</literal> is usually used for DTD fragments that contain only entity or element declarations. <literal>TEXT</literal> is - used for SGML content (text and tags).</para> + used for XML content (text and tags).</para> </listitem> </varlistentry> @@ -726,7 +663,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <para>Any description you want to supply for the contents of this file. This may include version numbers or any short text that is meaningful to you and unique for the - SGML system.</para> + XML system.</para> </listitem> </varlistentry> @@ -745,7 +682,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <title><filename>catalog</filename> Files</title> <para>If you use the syntax above and process this document - using an SGML processor, the processor will need to have + using an XML processor, the processor will need to have some way of turning the FPI into the name of the file on your computer that contains the DTD.</para> @@ -754,17 +691,19 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> contains lines that map FPIs to filenames. For example, if the catalog file contained the line:</para> - <programlisting>PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> +<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog --> - <para>The SGML processor would know to look up the DTD from - <filename>strict.dtd</filename> in the - <filename>4.0</filename> subdirectory of whichever directory + <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting> + + <para>The XML processor would know to look up the DTD from + <filename>transitional.dtd</filename> in the + <filename>1.0</filename> subdirectory of whichever directory held the <filename>catalog</filename> file that contained that line.</para> <para>Look at the contents of - <filename>/usr/local/share/sgml/html/catalog</filename>. - This is the catalog file for the HTML DTDs that will have + <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>. + This is the catalog file for the XHTML DTDs that will have been installed as part of the <filename role="package">textproc/docproj</filename> port.</para> </sect3> @@ -773,7 +712,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <title><envar>SGML_CATALOG_FILES</envar></title> <para>In order to locate a <filename>catalog</filename> file, - your SGML processor will need to know where to look. Many + your XML processor will need to know where to look. Many of them feature command line parameters for specifying the path to one or more catalogs.</para> @@ -804,12 +743,12 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> </listitem> </itemizedlist> - <para>You should <link linkend="sgml-primer-envars">already + <para>You should <link linkend="xml-primer-envars">already have done this</link>.</para> </sect3> </sect2> - <sect2 id="sgml-primer-fpi-alternatives"> + <sect2 id="xml-primer-fpi-alternatives"> <title>Alternatives to FPIs</title> <para>Instead of using an FPI to indicate the DTD that the @@ -822,7 +761,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> <para>The <literal>SYSTEM</literal> keyword indicates that the - SGML processor should locate the DTD in a system specific + XML processor should locate the DTD in a system specific fashion. This typically (but not always) means the DTD will be provided as a filename.</para> @@ -834,46 +773,46 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> </sect2> </sect1> - <sect1 id="sgml-primer-sgml-escape"> + <sect1 id="xml-primer-xml-escape"> <title>Escaping Back to SGML</title> - <para>As mentioned earlier, SGML is only used when writing a DTD. - This is not strictly true. There is certain SGML syntax that + <para>As mentioned earlier, XML is only used when writing a DTD. + This is not strictly true. There is certain XML syntax that you will want to be able to use within your documents. For example, comments can be included in your document, and will be - ignored by the parser. Comments are entered using SGML syntax. - Other uses for SGML syntax in your document will be shown later + ignored by the parser. Comments are entered using XML syntax. + Other uses for XML syntax in your document will be shown later too.</para> - <para>Obviously, you need some way of indicating to the SGML + <para>Obviously, you need some way of indicating to the XML processor that the following content is not elements within the - document, but is SGML that the parser should act upon.</para> + document, but is XML that the parser should act upon.</para> <para>These sections are marked by <literal><! ... ></literal> in your document. Everything - between these delimiters is SGML syntax as you might find within + between these delimiters is XML syntax as you might find within a DTD.</para> <para>As you may just have realized, the - <link linkend="sgml-primer-doctype-declaration">DOCTYPE - declaration</link> is an example of SGML syntax that you need + <link linkend="xml-primer-doctype-declaration">DOCTYPE + declaration</link> is an example of XML syntax that you need to include in your document…</para> </sect1> - <sect1 id="sgml-primer-comments"> + <sect1 id="xml-primer-comments"> <title>Comments</title> - <para>Comments are an SGML construction, and are normally only + <para>Comments are an XML construction, and are normally only valid inside a DTD. However, as - <xref linkend="sgml-primer-sgml-escape"/> shows, it is possible - to use SGML syntax within your document.</para> + <xref linkend="xml-primer-xml-escape"/> shows, it is possible + to use XML syntax within your document.</para> - <para>The delimiter for SGML comments is the string + <para>The delimiter for XML comments is the string <quote><literal>--</literal></quote>. The first occurrence of this string opens a comment, and the second closes it.</para> <example> - <title>SGML Generic Comment</title> + <title>XML Generic Comment</title> <programlisting><!-- test comment --></programlisting> @@ -889,7 +828,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> -- doing multiline comments -->]]></programlisting> </example> - <![ %output.print; [ + <![%output.print;[ <important> <title>Use 2 Dashes</title> @@ -906,24 +845,24 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> professional <emphasis>em-dash</emphasis>, and broken this example in the process.</para> - <para>The HTML, plain text, and RTF versions of this document + <para>The XHTML, plain text, and RTF versions of this document are not affected.</para> </important> ]]> - <para>If you have used HTML before you may have been shown + <para>If you have used XHTML before you may have been shown different rules for comments. In particular, you may think that the string <literal><!--</literal> opens a comment, and it is only closed by <literal>--></literal>.</para> <para>This is <emphasis>not</emphasis> the case. A lot of web - browsers have broken HTML parsers, and will accept that as - valid. However, the SGML parsers used by the Documentation + browsers have broken XHTML parsers, and will accept that as + valid. However, the XML parsers used by the Documentation Project are much stricter, and will reject documents that make that error.</para> <example> - <title>Erroneous SGML Comments</title> + <title>Erroneous XML Comments</title> <programlisting><![CDATA[ <!-- This is in the comment -- @@ -932,12 +871,12 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> -- back inside the comment -->]]></programlisting> - <para>The SGML parser will treat this as though it were + <para>The XML parser will treat this as though it were actually:</para> <programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting> - <para>This is not valid SGML, and may give confusing error + <para>This is not valid XML, and may give confusing error messages.</para> <programlisting><![CDATA[<!--------------- This is a very bad idea --------------->]]></programlisting> @@ -948,7 +887,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <programlisting><![CDATA[<!--===================================================-->]]></programlisting> <para>That is a (slightly) better approach, but it still - potentially confusing to people new to SGML.</para> + potentially confusing to people new to XML.</para> </example> <sect2> @@ -957,44 +896,44 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <procedure> <step> <para>Add some comments to - <filename>example.sgml</filename>, and check that the file - still validates using <command>onsgmls</command>.</para> + <filename>example.xml</filename>, and check that the file + still validates using <command>xmllint</command>.</para> </step> <step> <para>Add some invalid comments to - <filename>example.sgml</filename>, and see the error - messages that <command>onsgmls</command> gives when it + <filename>example.xml</filename>, and see the error + messages that <command>xmllint</command> gives when it encounters an invalid comment.</para> </step> </procedure> </sect2> </sect1> - <sect1 id="sgml-primer-entities"> + <sect1 id="xml-primer-entities"> <title>Entities</title> <para>Entities are a mechanism for assigning names to chunks of - content. As an SGML parser processes your document, any + content. As an XML parser processes your document, any entities it finds are replaced by the content of the entity.</para> <para>This is a good way to have re-usable, easily changeable - chunks of content in your SGML documents. It is also the only + chunks of content in your XML documents. It is also the only way to include one marked up file inside another using - SGML.</para> + XML.</para> <para>There are two types of entities which can be used in two different situations; <emphasis>general entities</emphasis> and <emphasis>parameter entities</emphasis>.</para> - <sect2 id="sgml-primer-general-entities"> + <sect2 id="xml-primer-general-entities"> <title>General Entities</title> - <para>You cannot use general entities in an SGML context + <para>You cannot use general entities in an XML context (although you define them in one). They can only be used in your document. Contrast this with <link - linkend="sgml-primer-parameter-entities">parameter + linkend="xml-primer-parameter-entities">parameter entities</link>.</para> <para>Each general entity has a name. When you want to @@ -1014,9 +953,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> your document.</para> <para>You can also use general entities to enter characters that - you could not otherwise include in an SGML document. For + you could not otherwise include in an XML document. For example, <literal><</literal> and <literal>&</literal> - cannot normally appear in an SGML document. When the SGML + cannot normally appear in an XML document. When the XML parser sees the <literal><</literal> symbol it assumes that a tag (either a start tag or an end tag) is about to appear, and when it sees the <literal>&</literal> symbol it @@ -1026,14 +965,15 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <literal>&lt;</literal> and <literal>&amp;</literal> whenever you need to include one or other of these.</para> - <para>A general entity can only be defined within an SGML + <para>A general entity can only be defined within an XML context. Typically, this is done immediately after the DOCTYPE declaration.</para> <example> <title>Defining General Entities</title> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY current.version "3.0-RELEASE"> <!ENTITY last.version "2.2.7-RELEASE"> ]>]]></programlisting> @@ -1050,15 +990,15 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> </example> </sect2> - <sect2 id="sgml-primer-parameter-entities"> + <sect2 id="xml-primer-parameter-entities"> <title>Parameter Entities</title> - <para>Like <link linkend="sgml-primer-general-entities">general + <para>Like <link linkend="xml-primer-general-entities">general entities</link>, parameter entities are used to assign names to reusable chunks of text. However, whereas general entities can only be used within your document, parameter entities can only be used within an <link - linkend="sgml-primer-sgml-escape">SGML + linkend="xml-primer-xml-escape">XML context</link>.</para> <para>Parameter entities are defined in a similar way to general @@ -1075,7 +1015,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <example> <title>Defining Parameter Entities</title> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY % param.some "some"> <!ENTITY % param.text "text"> <!ENTITY % param.new "%param.some more %param.text"> @@ -1093,15 +1034,16 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <procedure> <step> <para>Add a general entity to - <filename>example.sgml</filename>.</para> + <filename>example.xml</filename>.</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [ + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY version "1.1"> ]> -<html> +<html xmlns="http://www.w3.org/1999/xhtml"> <head> - <title>An Example HTML File</title> + <title>An Example XHTML File</title> </head> <!-- You might well have some comments in here as well --> @@ -1120,94 +1062,86 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <step> <para>Validate the document using - <command>onsgmls</command>.</para> + <command>xmllint</command>.</para> </step> <step> - <para>Load <filename>example.sgml</filename> into your web + <para>Load <filename>example.xml</filename> into your web browser (you may need to copy it to <filename>example.html</filename> before your browser - recognizes it as an HTML document).</para> + recognizes it as an XHTML document).</para> <para>Unless your browser is very advanced, you will not see the entity reference <literal>&version;</literal> replaced with the version number. Most web browsers have - very simplistic parsers which do not handle proper - SGML<footnote><para>This is a shame. Imagine all the - problems and hacks (such as Server Side Includes) that - could be avoided if they - did.</para></footnote>.</para> + very simplistic parsers which do not handle XML DTD + constructs. Furthermore, the closing <literal>]<</literal> + of the XML context are not recognized properly by browser and + will probably be rendered.</para> </step> <step> <para>The solution is to <emphasis>normalize</emphasis> your - document using an SGML normalizer. The normalizer reads - in valid SGML and outputs equally valid SGML which has + document using an XML normalizer. The normalizer reads + in valid XML and outputs equally valid XML which has been transformed in some way. One of the ways in which - the normalizer transforms the SGML is to expand all the + the normalizer transforms the XML is to expand all the entity references in the document, replacing the entities with the text that they represent.</para> - <para>You can use <command>osgmlnorm</command> to do - this.</para> + <para>You can use <command>xmllint</command> to do + this. It also has an option to drop the initial + DTD section so that the closing <literal>]<</literal> + does not confuse browsers:</para> - <screen>&prompt.user; <userinput>osgmlnorm example.sgml > example.html</userinput></screen> + <screen>&prompt.user; <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput></screen> <para>You should find a normalized (i.e., entity references expanded) copy of your document in <filename>example.html</filename>, ready to load into your web browser.</para> </step> - - <step> - <para>If you look at the output from - <command>osgmlnorm</command> you will see that it does not - include a DOCTYPE declaration at the start. To include - this you need to use the <option>-d</option> - option:</para> - - <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml > example.html</userinput></screen> - </step> </procedure> </sect2> </sect1> - <sect1 id="sgml-primer-include"> + <sect1 id="xml-primer-include"> <title>Using Entities to Include Files</title> <para>Entities (both - <link linkend="sgml-primer-general-entities">general</link> and - <link linkend="sgml-primer-parameter-entities">parameter</link>) + <link linkend="xml-primer-general-entities">general</link> and + <link linkend="xml-primer-parameter-entities">parameter</link>) are particularly useful when used to include one file inside another.</para> - <sect2 id="sgml-primer-include-using-gen-entities"> + <sect2 id="xml-primer-include-using-gen-entities"> <title>Using General Entities to Include Files</title> - <para>Suppose you have some content for an SGML book organized + <para>Suppose you have some content for an XML book organized into files, one file per chapter, called - <filename>chapter1.sgml</filename>, - <filename>chapter2.sgml</filename>, and so forth, with a - <filename>book.sgml</filename> file that will contain these + <filename>chapter1.xml</filename>, + <filename>chapter2.xml</filename>, and so forth, with a + <filename>book.xml</filename> file that will contain these chapters.</para> <para>In order to use the contents of these files as the values for your entities, you declare them with the - <literal>SYSTEM</literal> keyword. This directs the SGML + <literal>SYSTEM</literal> keyword. This directs the XML parser to use the contents of the named file as the value of the entity.</para> <example> <title>Using General Entities to Include Files</title> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY chapter.1 SYSTEM "chapter1.sgml"> <!ENTITY chapter.2 SYSTEM "chapter2.sgml"> <!ENTITY chapter.3 SYSTEM "chapter3.sgml"> <!-- And so forth --> ]> -<html> +<html xmlns="http://www.w3.org/1999/xhtml"> <!-- Use the entities to load in the chapters --> &chapter.1; @@ -1222,7 +1156,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> (<filename>chapter1.sgml</filename>, <filename>chapter2.sgml</filename>, and so on) <emphasis>must not</emphasis> start with a DOCTYPE - declaration. This is a syntax error.</para> + declaration. This is a syntax error because entities + are low-level constructs and they are resolved before + any parsing happens.</para> </warning> </sect2> @@ -1230,8 +1166,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <title>Using Parameter Entities to Include Files</title> <para>Recall that parameter entities can only be used inside an - SGML context. Why then would you want to include a file - within an SGML context?</para> + XML context. Why then would you want to include a file + within an XML context?</para> <para>You can use this to ensure that you can reuse your general entities.</para> @@ -1254,9 +1190,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> called <filename>chapters.ent</filename>. This file contains the following:</para> - <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> -<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> -<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> + <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting> <para>Now create a parameter entity to refer to the contents of the file. Then use the parameter entity to load the file @@ -1264,7 +1200,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> entities available for use. Then use the general entities as before:</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!-- Define a parameter entity to load in the chapter general entities --> <!ENTITY % chapters SYSTEM "chapters.ent"> @@ -1272,7 +1209,7 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> %chapters; ]> -<html> +<html xmlns="http://www.w3.org/1999/xhtml"> &chapter.1; &chapter.2; &chapter.3; @@ -1288,9 +1225,9 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <procedure> <step> - <para>Create three files, <filename>para1.sgml</filename>, - <filename>para2.sgml</filename>, and - <filename>para3.sgml</filename>.</para> + <para>Create three files, <filename>para1.xml</filename>, + <filename>para2.xml</filename>, and + <filename>para3.xml</filename>.</para> <para>Put content similar to the following in each file:</para> @@ -1299,19 +1236,20 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> </step> <step> - <para>Edit <filename>example.sgml</filename> so that it + <para>Edit <filename>example.xml</filename> so that it looks like this:</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"> ]> -<html> +<html xmlns="http://www.w3.org/1999/xhtml"> <head> - <title>An Example HTML File</title> + <title>An Example XHTML File</title> </head> <body> @@ -1326,15 +1264,15 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <step> <para>Produce <filename>example.html</filename> by - normalizing <filename>example.sgml</filename>.</para> + normalizing <filename>example.xml</filename>.</para> - <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml > example.html</userinput></screen> + <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> </step> <step> <para>Load <filename>example.html</filename> into your web browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> + <filename>para<replaceable>n</replaceable>.xml</filename> files have been included in <filename>example.html</filename>.</para> </step> @@ -1350,16 +1288,17 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <procedure> <step> - <para>Edit <filename>example.sgml</filename> so that it + <para>Edit <filename>example.xml</filename> so that it looks like this:</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % entities SYSTEM "entities.sgml"> %entities; + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % entities SYSTEM "entities.ent"> %entities; ]> -<html> +<html xmlns="http://www.w3.org/1999/xhtml"> <head> - <title>An Example HTML File</title> + <title>An Example XHTML File</title> </head> <body> @@ -1374,26 +1313,26 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <step> <para>Create a new file, - <filename>entities.sgml</filename>, with this + <filename>entities.ent</filename>, with this content:</para> <programlisting><![CDATA[<!ENTITY version "1.1"> -<!ENTITY para1 SYSTEM "para1.sgml"> -<!ENTITY para2 SYSTEM "para2.sgml"> -<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting> </step> <step> <para>Produce <filename>example.html</filename> by - normalizing <filename>example.sgml</filename>.</para> + normalizing <filename>example.xml</filename>.</para> - <screen>&prompt.user; <userinput>osgmlnorm -d example.sgml > example.html</userinput></screen> + <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> </step> <step> <para>Load <filename>example.html</filename> into your web browser, and confirm that the - <filename>para<replaceable>n</replaceable>.sgml</filename> + <filename>para<replaceable>n</replaceable>.xml</filename> files have been included in <filename>example.html</filename>.</para> </step> @@ -1402,22 +1341,22 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> </sect2> </sect1> - <sect1 id="sgml-primer-marked-sections"> + <sect1 id="xml-primer-marked-sections"> <title>Marked Sections</title> - <para>SGML provides a mechanism to indicate that particular pieces + <para>XML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are termed <quote>marked sections</quote>.</para> <example> <title>Structure of A Marked Section</title> - <programlisting><![ <replaceable>KEYWORD</replaceable> [ + <programlisting><![<replaceable>KEYWORD</replaceable>[ Contents of marked section ]]></programlisting> </example> - <para>As you would expect, being an SGML construct, a marked + <para>As you would expect, being an XML construct, a marked section starts with <literal><!</literal>.</para> <para>The first square bracket begins to delimit the marked @@ -1431,20 +1370,19 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <para>The marked section is finished by closing the two square brackets, and then returning to the document context from the - SGML context with <literal>></literal>.</para> + XGML context with <literal>></literal>.</para> <sect2> <title>Marked Section Keywords</title> <sect3> - <title><literal>CDATA</literal>, - <literal>RCDATA</literal></title> + <title><literal>CDATA</literal></title> <para>These keywords denote the marked sections <emphasis>content model</emphasis>, and allow you to change it from the default.</para> - <para>When an SGML parser is processing a document it keeps + <para>When an XML parser is processing a document it keeps track of what is called the <quote>content model</quote>.</para> @@ -1452,9 +1390,8 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> content the parser is expecting to see, and what it will do with it when it finds it.</para> - <para>The two content models you will probably find most - useful are <literal>CDATA</literal> and - <literal>RCDATA</literal>.</para> + <para>The content model you will probably find most + useful is <literal>CDATA</literal>.</para> <para><literal>CDATA</literal> is for <quote>Character Data</quote>. If the parser is in this content model then @@ -1463,32 +1400,12 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <literal>&</literal> symbols lose their special status, and will be treated as ordinary characters.</para> - <para><literal>RCDATA</literal> is for <quote>Entity - references and character data</quote>. If the parser is - in this content model then it is expecting to see characters - <emphasis>and</emphasis> entities. <literal><</literal> - loses its special status, but <literal>&</literal> will - still be treated as starting the beginning of a general - entity.</para> - - <para>This is particularly useful if you are including some - verbatim text that contains lots of <literal><</literal> - and <literal>&</literal> characters. While you could go - through the text ensuring that every <literal><</literal> - is converted to a <literal>&lt;</literal> and every - <literal>&</literal> is converted to a - <literal>&amp;</literal>, it can be easier to mark the - section as only containing <literal>CDATA</literal>. When - the SGML parser encounters this it will ignore the - <literal><</literal> and <literal>&</literal> symbols - embedded in the content.</para> - <note> - <para>When you use <literal>CDATA</literal> or - <literal>RCDATA</literal> in examples of text marked up in - SGML, keep in mind that the content of + <para>When you use <literal>CDATA</literal> + in examples of text marked up in + XML, keep in mind that the content of <literal>CDATA</literal> is not validated. You have to - check the included SGML text using other means. You + check the included XML text using other means. You could, for example, write the example in another document, validate the example code, and then paste it to your <literal>CDATA</literal> content.</para> @@ -1502,13 +1419,13 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <programlisting><para>Here is an example of how you would include some text that contained many <literal>&lt;</literal> and <literal>&amp;</literal> symbols. The sample - text is a fragment of HTML. The surrounding text (<para> and + text is a fragment of XHTML. The surrounding text (<para> and <programlisting>) are from DocBook.</para> <programlisting> - <![CDATA[ <![ CDATA [ + <![CDATA[<![CDATA[ <p>This is a sample that shows you some of the elements within - HTML. Since the angle brackets are used so many times, it is + XHTML. Since the angle brackets are used so many times, it is simpler to say the whole example is a CDATA marked section than to use the entity names for the left and right angle brackets throughout.</p> @@ -1542,11 +1459,11 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <title>Using <literal>INCLUDE</literal> and <literal>IGNORE</literal> in Marked Sections</title> - <programlisting><![ INCLUDE [ + <programlisting><![INCLUDE[ This text will be processed and included. ]]> -<![ IGNORE [ +<![IGNORE[ This text will not be processed or included. ]]></programlisting> </example> @@ -1556,50 +1473,50 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> it in comments.</para> <para>It becomes more useful when you realize you can use - <link linkend="sgml-primer-parameter-entities">parameter - entities</link> to control this. Remember that parameter - entities can only be used in SGML contexts, and the keyword - of a marked section <emphasis>is</emphasis> an SGML - context.</para> + <link linkend="xml-primer-parameter-entities">parameter + entities</link> to control this, yet this usage is limited + to entity files.</para> <para>For example, suppose that you produced a hard-copy version of some documentation and an electronic version. In the electronic version you wanted to include some extra content that was not to appear in the hard-copy.</para> - <para>Create a parameter entity, and set its value to - <literal>INCLUDE</literal>. Write your document, using - marked sections to delimit content that should only appear - in the electronic version. In these marked sections use the - parameter entity in place of the keyword.</para> - - <para>When you want to produce the hard-copy version of the - document, change the parameter entity's value to - <literal>IGNORE</literal> and reprocess the document.</para> + <para>Create an entity file that defines general entities + to include each chapter and guard these definitions with + a parameter entity that can be set to either + <literal>INCLUDE</literal> or <literal>IGNORE</literal> + to control whether the entity is defined. After these + conditional general entity definitions, place one more + definition for each general entity to set them to an + empty value. This technique makes use of the fact that + entity definitions cannot be overridden but always the + first definition takes effect. So you can control the + inclusion of your chapter with the corrsponding parameter + entity; if you set it to <literal>INCLUDE</literal>, the + first general entity definition will be read and the + second one will be ignored but if you set it to + <literal>IGNORE</literal>, the first definition will be + ignored and the second one will take effect.</para> <example> <title>Using A Parameter Entity to Control a Marked Section</title> - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ + <programlisting> <!ENTITY % electronic.copy "INCLUDE"> -]]> -... +<![%electronic.copy;[ +<!ENTITY chap.preface SYSTEM "preface.xml"> +]]> -<![ %electronic.copy [ - This content should only appear in the electronic - version of the document. -]]></programlisting> +<!ENTITY chap.preface ""> +</programlisting> <para>When producing the hard-copy version, change the - entity's definition to:</para> - - <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> + parameter entity's definition to:</para> - <para>On reprocessing the document, the marked sections that - use <literal>%electronic.copy</literal> as their keyword - will be ignored.</para> + <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> </example> </sect3> </sect2> @@ -1609,64 +1526,42 @@ onsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen> <procedure> <step> - <para>Create a new file, <filename>section.sgml</filename>, - that contains the following:</para> - - <programlisting><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ -<!ENTITY % text.output "INCLUDE"> -]> - -<html> - <head> - <title>An example using marked sections</title> - </head> - - <body> - <p>This paragraph <![CDATA[contains many < - characters (< < < < <) so it is easier - to wrap it in a CDATA marked section.]]></p> - - <![IGNORE[ - <p>This paragraph will definitely not be included in the - output.</p> - ]]> - - <![ <![CDATA[%text.output]]> [ - <p>This paragraph might appear in the output, or it - might not.</p> - - <p>Its appearance is controlled by the <![CDATA[%text.output]]> - parameter entity.</p> - ]]> - </body> -</html></programlisting> - </step> + <para>Modify the <filename>entities.ent</filename> file to contain + the following:</para> - <step> - <para>Normalize this file using <command>osgmlnorm</command> - and examine the output. Notice which paragraphs have - appeared, which have disappeared, and what has happened to - the content of the CDATA marked section.</para> + <programlisting><!ENTITY version "1.1"> +<!ENTITY % conditional.text "IGNORE"> + +<![%conditional.text;[ +<!ENTITY para1 SYSTEM "para1.xml"> +]]> + +<!ENTITY para1 ""> + +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"></programlisting> </step> <step> - <para>Change the definition of the - <literal>text.output</literal> entity from - <literal>INCLUDE</literal> to <literal>IGNORE</literal>. - Re-normalize the file, and examine the output to see what - has changed.</para> + <para>Normalize the <filename>example.xml</filename> file and notice + that the conditional text is not present on the output document. + Now if you set the parameter entity guard to <literal>INCLUDE</literal> + and regenerate the normalized document, it will appear there again. + Of course, this method makes more sense if you have more conditional + chunks that depend on the same condition, for example, whether you are + generating printed or online text.</para> </step> </procedure> </sect2> </sect1> - <sect1 id="sgml-primer-conclusion"> + <sect1 id="xml-primer-conclusion"> <title>Conclusion</title> - <para>That is the conclusion of this SGML primer. For reasons of + <para>That is the conclusion of this XML primer. For reasons of space and complexity several things have not been covered in depth (or at all). However, the previous sections cover enough - SGML for you to be able to follow the organization of the FDP + XML for you to be able to follow the organization of the FDP documentation.</para> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml index 4867d25391..ab25b68972 100644 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml @@ -83,7 +83,7 @@ subdirectories to further categorize the information. For example, the files that comprise the &man.make.1; infrastructure are in <filename>share/mk</filename>, while - the additional SGML support files (such as the FreeBSD + the additional XML support files (such as the FreeBSD extended DocBook DTD) are in <filename>share/sgml</filename>.</seg> </seglistitem> @@ -124,7 +124,7 @@ <seg>Documentation marked up as a DocBook <sgmltag>article</sgmltag> (or equivalent). Reasonably short, and broken up into sections. Normally only available - as one HTML file.</seg> + as one XHTML file.</seg> </seglistitem> <seglistitem> @@ -133,7 +133,7 @@ <seg>Documentation marked up as a DocBook <sgmltag>book</sgmltag> (or equivalent). Book length, and broken up into chapters. Normally available as both one - large HTML file (for people with fast connections, or who + large XHTML file (for people with fast connections, or who want to print it easily from a browser) and as a collection of linked, smaller files.</seg> </seglistitem> @@ -195,7 +195,7 @@ <title><filename>Makefile</filename></title> <para>The <filename>Makefile</filename> defines some - variables that affect how the SGML source is converted to + variables that affect how the XML source is converted to other formats, and lists the various source files that make up the Handbook. It then includes the standard <filename>doc.project.mk</filename> file, to bring in the @@ -208,16 +208,16 @@ <para>This is the top level document in the Handbook. It contains the Handbook's <link - linkend="sgml-primer-doctype-declaration">DOCTYPE + linkend="xml-primer-doctype-declaration">DOCTYPE declaration</link>, as well as the elements that describe the Handbook's structure.</para> <para><filename>book.sgml</filename> uses <link - linkend="sgml-primer-parameter-entities">parameter + linkend="xml-primer-parameter-entities">parameter entities</link> to load in the files with the <filename>.ent</filename> extension. These files (described later) then define <link - linkend="sgml-primer-general-entities">general + linkend="xml-primer-general-entities">general entities</link> that are used throughout the rest of the Handbook.</para> </sect4> @@ -246,7 +246,7 @@ the entire contents of the chapter will be held in this file.</para> - <para>When the HTML version of the Handbook is produced, + <para>When the XHTML version of the Handbook is produced, this will yield <filename>kernelconfig.html</filename>. This is because of the <literal>id</literal> value, and is not related to the name of the directory.</para> @@ -260,7 +260,7 @@ Handbook chapter are stored within <filename class="directory">share/images/books/handbook</filename>. Note that localized version of these images should be - placed in the same directory as the SGML sources for each + placed in the same directory as the XML sources for each chapter. Namespace collisions would be inevitable, and it is easier to work with several directories with a few files in them than it is to work with one directory that @@ -283,12 +283,12 @@ </important> <para>Each <filename>chapter.sgml</filename> file will not - be a complete SGML document. In particular, they will not + be a complete XML document. In particular, they will not have their own DOCTYPE lines at the start of the files.</para> <para>This is unfortunate as it makes it impossible to treat - these as generic SGML files and simply convert them to + these as generic XML files and simply convert them to HTML, RTF, PS, and other formats in the same way the main Handbook is generated. This <emphasis>would</emphasis> force you to rebuild the Handbook every time you want to diff --git a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml index 2b1d16ddb6..9975364fa6 100644 --- a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml @@ -40,7 +40,7 @@ Panorama, SPICE, JSSS, FOSI, CSS, and DSSSL.</para> <para>For DocBook, we are using stylesheets written in DSSSL. For - HTML we are using CSS.</para> + XHTML we are using CSS.</para> <sect1 id="stylesheets-dsssl"> <title>* DSSSL</title> @@ -69,7 +69,7 @@ <para>Cascading Stylesheets (CSS) are a mechanism for attaching style information (font, weight, size, color, and so forth) to - elements in an HTML document without abusing HTML to do + elements in an XHTML document without abusing XHTML to do so.</para> <sect2> @@ -77,10 +77,10 @@ <para>The FreeBSD DSSSL stylesheets include a reference to a stylesheet, <filename>docbook.css</filename>, which is - expected to appear in the same directory as the HTML files. + expected to appear in the same directory as the XHTML files. The project-wide CSS file is copied from <filename>doc/share/misc/docbook.css</filename> when documents - are converted to HTML, and is installed automatically.</para> + are converted to XHTML, and is installed automatically.</para> </sect2> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml index a53a76c0a6..6bb2de2e09 100644 --- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml @@ -39,7 +39,7 @@ <para>Use a disk with sufficient free space. You may need anything from 200 MB to over 500 MB, depending on the - method you choose. This space will hold the SGML tools, a + method you choose. This space will hold the XML tools, a subset of the <application>svn</application> tree, temporary build space and the installed web pages.</para> diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml index f06cde4928..89b2310641 100644 --- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml @@ -81,7 +81,7 @@ These slave ports define the <makevar>JADETEX</makevar> variable for you, therefore they will install the same suite of applications on your machine. Note that you can produce only - HTML or ASCII text output if you do not install + XHTML or ASCII text output if you do not install <application>JadeTeX</application>. PostScript or PDF output requires &tex;.</para> </tip> @@ -94,7 +94,7 @@ <para>These programs are required before you can usefully work with the FreeBSD documentation, and they will allow you to - convert the documentation to HTML, plain text, and RTF + convert the documentation to XHTML, plain text, and RTF formats. They are all included in <filename role="package">textproc/docproj</filename>.</para> @@ -115,8 +115,8 @@ (<filename role="package">www/tidy</filename>)</term> <listitem> - <para>An HTML <quote>pretty printer</quote>, used to - reformat some of the automatically generated HTML so + <para>An (X)HTML <quote>pretty printer</quote>, used to + reformat some of the automatically generated pages so that it is easier to follow.</para> </listitem> </varlistentry> @@ -127,7 +127,7 @@ <listitem> <para>A text-mode WWW browser that can also convert - HTML files to plain text.</para> + XHTML files to plain text.</para> </listitem> </varlistentry> @@ -154,11 +154,11 @@ <variablelist> <varlistentry> - <term>HTML DTD (<filename - role="package">textproc/html</filename>)</term> + <term>XHTML DTD (<filename + role="package">textproc/xhtml</filename>)</term> <listitem> - <para>HTML is the markup language of choice for the World + <para>XHTML is the markup language of choice for the World Wide Web, and is used throughout the FreeBSD web site.</para> </listitem> @@ -282,7 +282,7 @@ </variablelist> <para>If anyone has recommendations for other software that is - useful when manipulating SGML documents, please let &a.doceng; + useful when manipulating XML documents, please let &a.doceng; know, so they can be added to this list.</para> </sect2> </sect1> |