Date: Sun, 23 Jun 2013 19:45:13 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42005 - in head/en_US.ISO8859-1/books/fdp-primer: . docbook-markup overview sgml-markup xhtml-markup Message-ID: <201306231945.r5NJjDxK055478@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Jun 23 19:45:12 2013 New Revision: 42005 URL: http://svnweb.freebsd.org/changeset/doc/42005 Log: Split the old sgml-markup chapter into two chapters, one for XHTML and one for DocBook. Both are edited and expanded versions of the content from the old chapter. Added: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml - copied, changed from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/ head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml - copied, changed from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml Deleted: head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/ Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile head/en_US.ISO8859-1/books/fdp-primer/book.xml head/en_US.ISO8859-1/books/fdp-primer/chapters.ent head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 17:59:58 2013 (r42004) +++ head/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 19:45:12 2013 (r42005) @@ -23,7 +23,8 @@ SRCS= book.xml SRCS+= overview/chapter.xml SRCS+= psgml-mode/chapter.xml SRCS+= see-also/chapter.xml -SRCS+= sgml-markup/chapter.xml +SRCS+= xhtml-markup/chapter.xml +SRCS+= docbook-markup/chapter.xml SRCS+= sgml-primer/chapter.xml SRCS+= stylesheets/chapter.xml SRCS+= structure/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 17:59:58 2013 (r42004) +++ head/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 19:45:12 2013 (r42005) @@ -248,7 +248,8 @@ Password:</screen></entry> &chap.overview; &chap.tools; &chap.xml-primer; - &chap.xml-markup; + &chap.xhtml-markup; + &chap.docbook-markup; &chap.stylesheets; &chap.structure; &chap.doc-build; Modified: head/en_US.ISO8859-1/books/fdp-primer/chapters.ent ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 17:59:58 2013 (r42004) +++ head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 19:45:12 2013 (r42005) @@ -13,7 +13,8 @@ <!ENTITY chap.overview SYSTEM "overview/chapter.xml"> <!ENTITY chap.xml-primer SYSTEM "sgml-primer/chapter.xml"> <!ENTITY chap.tools SYSTEM "tools/chapter.xml"> -<!ENTITY chap.xml-markup SYSTEM "sgml-markup/chapter.xml"> +<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> +<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> <!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> <!ENTITY chap.structure SYSTEM "structure/chapter.xml"> <!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> Copied and modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml (from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml) ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml Fri Jun 21 17:57:26 2013 (r41997, copy source) +++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Sun Jun 23 19:45:12 2013 (r42005) @@ -31,620 +31,40 @@ $FreeBSD$ --> -<chapter id="xml-markup"> - <title>XML Markup</title> +<chapter id="docbook-markup"> + <title>DocBook Markup</title> - <para>This chapter describes the two markup languages you will - encounter when you contribute to the FreeBSD documentation - project. Each section describes the markup language, and details - the markup that you are likely to want to use, or that is already - in use.</para> - - <para>These markup languages contain a large number of elements, and - it can be confusing sometimes to know which element to use for a - particular situation. This section goes through the elements you - are most likely to need, and gives examples of how you would use - them.</para> - - <para>This is <emphasis>not</emphasis> an exhaustive list of - elements, since that would just reiterate the documentation for - each language. The aim of this section is to list those elements - more likely to be useful to you. If you have a question about how - best to markup a particular piece of content, please post it to - the &a.doc;.</para> - - <note> - <title>Inline Versus Block</title> - - <para>In the remainder of this document, when describing elements, - <emphasis>inline</emphasis> means that the element can occur - within a block element, and does not cause a line break. A - <emphasis>block</emphasis> element, by comparison, will cause a - line break (and other processing) when it is encountered.</para> - </note> - - <sect1 id="xml-markup-xhtml"> - <title>XHTML</title> - - <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>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 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, - 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 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> + <sect1 id="docbook-markup-introduction"> + <title>Introduction</title> - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <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 XHTML documents on the FreeBSD web site - comply with the transitional version of XHTML 1.0.</para> - - <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Sectional Elements</title> - - <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 - second section, the <emphasis>body</emphasis>, contains the - content that will be displayed to the user.</para> - - <para>These sections are indicated with <sgmltag>head</sgmltag> - and <sgmltag>body</sgmltag> elements respectively. These - elements are contained within the top-level - <sgmltag>html</sgmltag> element.</para> - - <example> - <title>Normal XHTML Document Structure</title> - - <programlisting><html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title><replaceable>The Document's Title</replaceable></title> - </head> - - <body> - - … - - </body> -</html></programlisting> - </example> - </sect2> - - <sect2> - <title>Block Elements</title> - - <sect3> - <title>Headings</title> - - <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 - <sgmltag>h1</sgmltag>, then <sgmltag>h2</sgmltag>, - continuing down to <sgmltag>h6</sgmltag>.</para> - - <para>The element's content is the text of the heading.</para> - - <example> - <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, - and Other Header Tags</title> - - <para>Use:</para> - - <programlisting><![CDATA[<h1>First section</h1> - -<!-- Document introduction goes here --> - -<h2>This is the heading for the first section</h2> - -<!-- Content for the first section goes here --> - -<h3>This is the heading for the first sub-section</h3> - -<!-- Content for the first sub-section goes here --> - -<h2>This is the heading for the second section</h2> - -<!-- Content for the second section goes here -->]]></programlisting> - </example> - - <para>Generally, an XHTML page should have one first level - heading (<sgmltag>h1</sgmltag>). This can contain many - second level headings (<sgmltag>h2</sgmltag>), which can in - turn contain many third level headings. Each - <sgmltag>h<replaceable>n</replaceable></sgmltag> element - should have the same element, but one further up the - hierarchy, preceding it. Leaving gaps in the numbering is - to be avoided.</para> - - <example> - <title>Bad Ordering of - <sgmltag>h<replaceable>n</replaceable></sgmltag> - Elements</title> - - <para>Use:</para> - - <programlisting><![CDATA[<h1>First section</h1> - -<!-- Document introduction --> - -<h3>Sub-section</h3> - -<!-- This is bad, <h2> has been left out -->]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Paragraphs</title> - - <para>XHTML supports a single paragraph element, - <sgmltag>p</sgmltag>.</para> - - <example> - <title><sgmltag>p</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any - other element.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Block Quotations</title> - - <para>A block quotation is an extended quotation from another - document that should not appear within the current - paragraph.</para> - - <example> - <title><sgmltag>blockquote</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>A small excerpt from the US Constitution:</p> - -<blockquote>We the People of the United States, in Order to form - a more perfect Union, establish Justice, insure domestic - Tranquility, provide for the common defence, promote the general - Welfare, and secure the Blessings of Liberty to ourselves and our - Posterity, do ordain and establish this Constitution for the - United States of America.</blockquote>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Lists</title> - - <para>You can present the user with three types of lists, - ordered, unordered, and definition.</para> - - <para>Typically, each entry in an ordered list will be - numbered, while each entry in an unordered list will be - preceded by a bullet point. Definition lists are composed - of two sections for each entry. The first section is the - term being defined, and the second section is the definition - of the term.</para> - - <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> - element, unordered lists by the <sgmltag>ul</sgmltag> - element, and definition lists by the <sgmltag>dl</sgmltag> - element.</para> - - <para>Ordered and unordered lists contain listitems, indicated - by the <sgmltag>li</sgmltag> element. A listitem can - contain textual content, or it may be further wrapped in one - or more <sgmltag>p</sgmltag> elements.</para> - - <para>Definition lists contain definition terms - (<sgmltag>dt</sgmltag>) and definition descriptions - (<sgmltag>dd</sgmltag>). A definition term can only contain - inline elements. A definition description can contain other - block elements.</para> - - <example> - <title><sgmltag>ul</sgmltag> and - <sgmltag>ol</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>An unordered list. Listitems will probably be - preceded by bullets.</p> - -<ul> - <li>First item</li> - - <li>Second item</li> - - <li>Third item</li> -</ul> - -<p>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be - numbered.</p> - -<ol> - <li><p>This is the first item. It only has one paragraph.</p></li> - - <li><p>This is the first paragraph of the second item.</p> - - <p>This is the second paragraph of the second item.</p></li> - - <li><p>This is the first and only paragraph of the third - item.</p></li> -</ol>]]></programlisting> - </example> - - <example> - <title>Definition Lists with <sgmltag>dl</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<dl> - <dt>Term 1</dt> - - <dd><p>Paragraph 1 of definition 1.</p> - - <p>Paragraph 2 of definition 1.</p></dd> - - <dt>Term 2</dt> - - <dd><p>Paragraph 1 of definition 2.</p></dd> - - <dt>Term 3</dt> - - <dd><p>Paragraph 1 of definition 3.</p></dd> -</dl>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Pre-formatted Text</title> - - <para>You can indicate that text should be shown to the user - exactly as it is in the file. Typically, this means that - the text is shown in a fixed font, multiple spaces are not - merged into one, and line breaks in the text are - significant.</para> - - <para>In order to do this, wrap the content in the - <sgmltag>pre</sgmltag> element.</para> - - <example> - <title><sgmltag>pre</sgmltag></title> - - <para>You could use <sgmltag>pre</sgmltag> to mark up an - email message:</para> - - <programlisting><![CDATA[<pre> From: nik@FreeBSD.org - To: freebsd-doc@FreeBSD.org - Subject: New documentation available - - There is a new copy of my primer for contributors to the FreeBSD - Documentation Project available at - - <URL:http://people.FreeBSD.org/~nik/primer/index.html> - - Comments appreciated. - - N</pre>]]></programlisting> - - <para>Keep in mind that <literal><</literal> and - <literal>&</literal> still are recognized as special - characters in pre-formatted text. This is why the example - shown had to use <literal>&lt;</literal> instead of - <literal><</literal>. For consistency, - <literal>&gt;</literal> was used in place of - <literal>></literal>, too. Watch out for the special - characters that may appear in text copied from a - plain-text source, e.g., an email message or program - code.</para> - </example> - </sect3> - - <sect3> - <title>Tables</title> - - <note> - <para>Most text-mode browsers (such as Lynx) do not render - tables particularly effectively. If you are relying on - the tabular display of your content, you should consider - using alternative markup to prevent confusion.</para> - </note> - - <para>Mark up tabular information using the - <sgmltag>table</sgmltag> element. A table consists of one - or more table rows (<sgmltag>tr</sgmltag>), each containing - one or more cells of table data (<sgmltag>td</sgmltag>). - Each cell can contain other block elements, such as - paragraphs or lists. It can also contain another table - (this nesting can repeat indefinitely). If the cell only - contains one paragraph then you do not need to include the - <sgmltag>p</sgmltag> element.</para> - - <example> - <title>Simple Use of <sgmltag>table</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>This is a simple 2x2 table.</p> - -<table> - <tr> - <td>Top left cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting></example> - - <para>A cell can span multiple rows and columns. To indicate - this, add the <literal>rowspan</literal> and/or - <literal>colspan</literal> attributes, with values - indicating the number of rows or columns that should be - spanned.</para> - - <example> - <title>Using <literal>rowspan</literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>One tall thin cell on the left, two short cells next to - it on the right.</p> - -<table> - <tr> - <td rowspan="2">Long and thin</td> - </tr> - - <tr> - <td>Top cell</td> - - <td>Bottom cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>colspan</literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>One long cell on top, two short cells below it.</p> - -<table> - <tr> - <td colspan="2">Top cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - - <example> - <title>Using <literal>rowspan</literal> and - <literal>colspan</literal> Together</title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>On a 3x3 grid, the top left block is a 2x2 set of - cells merged into one. The other cells are normal.</p> - -<table> - <tr> - <td colspan="2" rowspan="2">Top left large cell</td> - - <td>Top right cell</td> - </tr> - - <tr> - <!-- Because the large cell on the left merges into - this row, the first <td> will occur on its - right --> - - <td>Middle right cell</td> - </tr> - - <tr> - <td>Bottom left cell</td> - - <td>Bottom middle cell</td> - - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>In-line Elements</title> - - <sect3> - <title>Emphasizing Information</title> - - <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 - emphasis.</para> - - <para>Typically, <sgmltag>em</sgmltag> is rendered in italic - and <sgmltag>strong</sgmltag> is rendered in bold. This is - not always the case, however, and you should not rely on - 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 - <sgmltag>strong</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p><em>This</em> has been emphasized, while - <strong>this</strong> has been strongly emphasized.</p>]]></programlisting> - </example> - </sect3> - - <sect3> - <title>Indicating Fixed-Pitch Text</title> - - <para>If you have content that should be rendered in a fixed - pitch (typewriter) typeface, use <sgmltag>tt</sgmltag> (for - <quote>teletype</quote>).</para> - - <example> - <title><sgmltag>tt</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>This document was originally written by - Nik Clayton, who can be reached by email as - <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also inline elements.</para> - </note> - - <sect3> - <title>Linking to Other Documents on the WWW</title> - - <para>In order to include a link to another document on the - WWW you must know the URL of the document you want to link - to.</para> - - <para>The link is indicated with <sgmltag>a</sgmltag>, and the - <literal>href</literal> attribute contains the URL of the - target document. The content of the element becomes the - link, and is normally indicated to the user in some way - (underlining, change of color, different mouse cursor when - over the link, and so on).</para> - - <example> - <title>Using <literal><a href="..."></literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p>More information is available at the - <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> - </example> - - <para>These links will take the user to the top of the chosen - document.</para> - </sect3> - - <sect3> - <title>Linking to Other Parts of Documents</title> - - <para>Linking to a point within another document (or within - the same document) requires that the document author include - anchors that you can link to.</para> - - <para>Anchors are indicated with <sgmltag>a</sgmltag> and the - <literal>id</literal> attribute instead of - <literal>href</literal>.</para> - - <example> - <title>Using <literal><a id="..."></literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p><a id="para1">This</a> paragraph can be referenced - in other links with the name <tt>para1</tt>.</p>]]></programlisting> - </example> - - <para>To link to a named part of a document, write a normal - link to that document, but include the id of the anchor - after a <literal>#</literal> symbol.</para> - - <example> - <title>Linking to a Named Part of Another Document</title> - - <para>Assume that the <literal>para1</literal> example - resides in a document called - <filename>foo.html</filename>.</para> - - <programlisting><![CDATA[<p>More information can be found in the - <a href="foo.html#para1">first paragraph</a> of - <tt>foo.html</tt>.</p>]]></programlisting> - </example> - - <para>If you are linking to a named anchor within the same - document then you can omit the document's URL, and just - include the name of the anchor (with the preceding - <literal>#</literal>).</para> - - <example> - <title>Linking to a Named Part of the Same Document</title> - - <para>Assume that the <literal>para1</literal> example - resides in this document:</para> - - <programlisting><![CDATA[<p>More information can be found in the - <a href="#para1">first paragraph</a> of this - document.</p>]]></programlisting> - </example> - </sect3> - </sect2> - </sect1> - - <sect1 id="xml-markup-docbook"> - <title>DocBook</title> + <para>This chapter is an introduction to DocBook as it is used for + &os; documentation. DocBook is a large and complex markup + system, but the subset described here covers the parts that are + most widely used for &os; documentation. While a moderate + subset is covered, it is impossible to anticipate every + situation. Please post questions that this document does + not answer to the &a.doc;.</para> <para>DocBook was originally developed by HaL Computer Systems and - O'Reilly & Associates to be a DTD for writing technical - documentation <footnote><para>A short history can be found under - <ulink + O'Reilly & Associates to be a <acronym>DTD</acronym> for + writing technical documentation <footnote><para>A short history + can be found under <ulink url="http://www.oasis-open.org/docbook/intro.shtml#d0e41"> http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>. 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 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> + LinuxDoc and <acronym>XHTML</acronym>, 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> + + <para>The DocBook <acronym>DTD</acronym> is available from the + Ports Collection in the + <filename role="package">textproc/docbook-xml-450</filename> + port. It is automatically installed as part of the + <filename role="package">textproc/docproj</filename> + port.</para> <note> <title>Formal Versus Informal</title> @@ -656,209 +76,217 @@ informal version will not have a title.</para> </note> - <para>The DocBook DTD is available from the Ports Collection - in the <filename role="package">textproc/docbook-xml-450</filename> - port. It is automatically installed as part of the <filename - role="package">textproc/docproj</filename> port.</para> - - <sect2> - <title>&os; Extensions</title> - - <para>The FreeBSD Documentation Project has extended the DocBook - DTD by adding some new elements. These elements serve to make - some of the markup more precise.</para> - - <para>Where a FreeBSD specific element is listed below it is - clearly marked.</para> - - <para>Throughout the rest of this document, the term - <quote>DocBook</quote> is used to mean the FreeBSD extended - DocBook DTD.</para> - - <note> - <para>There is nothing about these extensions that is FreeBSD - specific, it was just felt that they were useful - enhancements for this particular project. Should anyone - from any of the other *nix camps (NetBSD, OpenBSD, Linux, - …) be interested in collaborating on a standard - DocBook extension set, please get in touch with - &a.doceng;.</para> - </note> + <note> + <title>Inline Versus Block</title> - <para>The &os; extensions are not (currently) in the - Ports Collection. They are stored in the &os; Subversion - tree, as <ulink - url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para> - </sect2> + <para>In the remainder of this document, when describing + elements, <emphasis>inline</emphasis> means that the element + can occur within a block element, and does not cause a line + break. A <emphasis>block</emphasis> element, by comparison, + will cause a line break (and other processing) when it is + encountered.</para> + </note> + </sect1> - <sect2> - <title>Formal Public Identifier (FPI)</title> + <sect1 id="docbook-markup-freebsd-extensions"> + <title>&os; Extensions</title> - <para>In compliance with the DocBook guidelines for writing FPIs - for DocBook customizations, the FPI for the FreeBSD extended - DocBook DTD is:</para> + <para>The &os; Documentation Project has extended the + DocBook <acronym>DTD</acronym> by adding some new elements. + These elements serve to make some of the markup more + precise.</para> + + <para>Where a &os;-specific element is listed below, it is + clearly marked.</para> + + <para>Throughout the rest of this document, the term + <quote>DocBook</quote> is used to mean the &os;-extended + DocBook <acronym>DTD</acronym>.</para> - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> - </sect2> + <note> + <para>There is nothing about these extensions that is &os; + specific, it was just felt that they were useful + enhancements for this particular project. Should anyone + from any of the other *nix camps (NetBSD, OpenBSD, Linux, + …) be interested in collaborating on a standard + DocBook extension set, please get in touch with + &a.doceng;.</para> + </note> - <sect2> - <title>Document Structure</title> + <para>The &os; extensions are not (currently) in the + Ports Collection. They are stored in the &os; Subversion + tree, as <ulink + url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para> + </sect1> - <para>DocBook allows you to structure your documentation in - several ways. In the FreeBSD Documentation Project we are - using two primary types of DocBook document: the book and the - article.</para> - - <para>A book is organized into <sgmltag>chapter</sgmltag>s. - This is a mandatory requirement. There may be - <sgmltag>part</sgmltag>s between the book and the chapter to - provide another layer of organization. For example, the - Handbook is arranged in this way.</para> - - <para>A chapter may (or may not) contain one or more sections. - These are indicated with the <sgmltag>sect1</sgmltag> element. - If a section contains another section then use the - <sgmltag>sect2</sgmltag> element, and so on, up to - <sgmltag>sect5</sgmltag>.</para> + <sect1 id="docbook-markup-fpi"> + <title>Formal Public Identifier (FPI)</title> - <para>Chapters and sections contain the remainder of the - content.</para> + <para>In compliance with the DocBook guidelines for writing + <acronym>FPI</acronym>s for DocBook customizations, the + <acronym>FPI</acronym> for the &os; extended DocBook + <acronym>DTD</acronym> is:</para> - <para>An article is simpler than a book, and does not use - chapters. Instead, the content of an article is organized - into one or more sections, using the same - <sgmltag>sect1</sgmltag> (and <sgmltag>sect2</sgmltag> and so - on) elements that are used in books.</para> - - <para>Obviously, you should consider the nature of the - documentation you are writing in order to decide whether it is - best marked up as a book or an article. Articles are well - suited to information that does not need to be broken down - into several chapters, and that is, relatively speaking, quite - short, at up to 20-25 pages of content. Books are best suited - to information that can be broken up into several chapters, - possibly with appendices and similar content as well.</para> - - <para>The <ulink url="&url.base;/docs.html">FreeBSD - tutorials</ulink> are all marked up as articles, while this - document, the - <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>, - and the <ulink url="&url.books.handbook;/index.html">FreeBSD - Handbook</ulink> are all marked up as books, for - example.</para> + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> + </sect1> - <sect3> - <title>Starting a Book</title> + <sect1 id="docbook-markup-document-structure"> + <title>Document Structure</title> - <para>The content of the book is contained within the - <sgmltag>book</sgmltag> element. As well as containing - structural markup, this element can contain elements that - include additional information about the book. This is - either meta-information, used for reference purposes, or - additional content used to produce a title page.</para> + <para>DocBook allows structuring documentation in several ways. + The &os; Documentation Project uses two primary types of DocBook + document: the book and the article.</para> + + <para>Books are organized into <sgmltag>chapter</sgmltag>s. + This is a mandatory requirement. There may be + <sgmltag>part</sgmltag>s between the book and the chapter to + provide another layer of organization. For example, the + Handbook is arranged in this way.</para> + + <para>A chapter may (or may not) contain one or more sections. + These are indicated with the <sgmltag>sect1</sgmltag> element. + If a section contains another section then use the + <sgmltag>sect2</sgmltag> element, and so on, up to + <sgmltag>sect5</sgmltag>.</para> + + <para>Chapters and sections contain the remainder of the + content.</para> + + <para>An article is simpler than a book, and does not use + chapters. Instead, the content of an article is organized into + one or more sections, using the same <sgmltag>sect1</sgmltag> + (and <sgmltag>sect2</sgmltag> and so on) elements that are used + in books.</para> + + <para>The nature of the document being written should be used to + determine whether it is best marked up as a book or an article. + Articles are well suited to information that does not need to be + broken down into several chapters, and that is, relatively + speaking, quite short, at up to 20-25 pages of content. Books + are best suited to information that can be broken up into + several chapters, possibly with appendices and similar content + as well.</para> + + <para>The <ulink url="&url.base;/docs.html">&os; tutorials</ulink> + are all marked up as articles, while this + document, the + <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>, + and the <ulink url="&url.books.handbook;/index.html">FreeBSD + Handbook</ulink> are all marked up as books, for + example.</para> + + <sect2 id="docbook-markup-starting-a-book"> + <title>Starting a Book</title> + + <para>The content of a book is contained within the + <sgmltag>book</sgmltag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the book. This is either + meta-information, used for reference purposes, or additional + content used to produce a title page.</para> - <para>This additional information should be contained within - <sgmltag>bookinfo</sgmltag>.</para> + <para>This additional information is contained within + <sgmltag>bookinfo</sgmltag>.</para> - <example> - <title>Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag></title> + <example> + <title>Boilerplate <sgmltag>book</sgmltag> with + <sgmltag>bookinfo</sgmltag></title> - <!-- Can't put this in a marked section because of the - replaceable elements --> + <!-- Cannot put this in a marked section because of the + replaceable elements --> - <programlisting><book> - <bookinfo> - <title><replaceable>Your Title Here</replaceable></title> - - <author> - <firstname><replaceable>Your first name</replaceable></firstname> - <surname><replaceable>Your surname</replaceable></surname> - <affiliation> - <address><email><replaceable>Your email address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> - </abstract> - </bookinfo> + <programlisting><book> + <bookinfo> + <title><replaceable>Your Title Here</replaceable></title> + + <author> + <firstname><replaceable>Your first name</replaceable></firstname> + <surname><replaceable>Your surname</replaceable></surname> + <affiliation> + <address><email><replaceable>Your email address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> + </abstract> + </bookinfo> … -</book></programlisting> - </example> - </sect3> +</book></programlisting> + </example> + </sect2> - <sect3> - <title>Starting an Article</title> + <sect2 id="docbook-markup-starting-an-article"> + <title>Starting an Article</title> - <para>The content of the article is contained within the - <sgmltag>article</sgmltag> element. As well as containing - structural markup, this element can contain elements that - include additional information about the article. This is - either meta-information, used for reference purposes, or - additional content used to produce a title page.</para> + <para>The content of the article is contained within the + <sgmltag>article</sgmltag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the article. This is + either meta-information, used for reference purposes, or + additional content used to produce a title page.</para> - <para>This additional information should be contained within - <sgmltag>articleinfo</sgmltag>.</para> + <para>This additional information is contained within + <sgmltag>articleinfo</sgmltag>.</para> - <example> - <title>Boilerplate <sgmltag>article</sgmltag> with - <sgmltag>articleinfo</sgmltag></title> + <example> + <title>Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>articleinfo</sgmltag></title> - <!-- Can't put this in a marked section because of the - replaceable elements --> + <!-- Cannot put this in a marked section because of the + replaceable elements --> - <programlisting><article> - <articleinfo> - <title><replaceable>Your title here</replaceable></title> - - <author> *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306231945.r5NJjDxK055478>