Date: Fri, 14 Sep 2012 08:32:33 +0000 (UTC) From: Gabor Kovesdan <gabor@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-projects@freebsd.org Subject: svn commit: r39528 - in projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer: doc-build examples overview see-also sgml-markup sgml-primer structure stylesheets the-website tools Message-ID: <201209140832.q8E8WXn8079654@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: gabor Date: Fri Sep 14 08:32:33 2012 New Revision: 39528 URL: http://svn.freebsd.org/changeset/doc/39528 Log: - Partly update the fdp-primer for the new, XML-based documentation Approved by: doceng (implicit) Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/structure/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -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> Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/examples/appendix.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -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"/> Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -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> Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -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> Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -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 Modified: projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml ============================================================================== --- projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml Thu Sep 13 18:03:11 2012 (r39527) +++ projects/sgml2xml/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml Fri Sep 14 08:32:33 2012 (r39528) @@ -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> + +<p>This is another paragraph. A horizontal rule separates this + from the previous paragraph.</p>]]></programlisting> - <programlisting><![CDATA[<p>This is a paragraph.</p> + <para>For such elements, that have no content at all, XML introduced + a shorthand form, which is ccompletely equivalent to the above + form:</para> -<hr> + <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 <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 </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> + the <command>xmllint</command> + <link linkend="xml-primer-validating">validating + parser</link>.</para> - <para>Use <command>onsgmls</command> to check that your - document is valid:</para> + <para>Use <command>xmllint</command> in the following way to + check that your document is valid:</para> - <screen>&prompt.user; <userinput>onsgmls -s example.sgml</userinput></screen> + <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput></screen> - <para>As you will see, <command>onsgmls</command> returns + <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 <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 </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 <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 <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 <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 <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 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 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 <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 <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 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 --> + + <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting> - <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 + <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 <title><envar>SGML_CATALOG_FILES</envar></title> <para>In order to locate a <filename>catalog</filename> file, *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201209140832.q8E8WXn8079654>