diff options
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml | 344 | ||||
| -rw-r--r-- | en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml | 344 |
2 files changed, 390 insertions, 298 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 2d74c89f07..71959ba6a4 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 @@ -27,7 +27,7 @@ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $Id: chapter.sgml,v 1.7 1999-08-30 11:53:03 jhb Exp $ + $Id: chapter.sgml,v 1.8 1999-09-03 17:16:06 nik Exp $ --> <chapter id="sgml-markup"> @@ -93,8 +93,7 @@ <para>The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0.</para> - <programlisting> -PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> </sect2> <sect2> @@ -114,8 +113,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <example> <title>Normal HTML document structure</title> - <programlisting> -<html> + <programlisting><html> <head> <title><replaceable>The document's title</replaceable></title> </head> @@ -149,8 +147,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<h1>First section</h1> + <programlisting><![ CDATA [<h1>First section</h1> <!-- Document introduction goes here --> @@ -181,8 +178,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<h1>First section</h1> + <programlisting><![ CDATA [<h1>First section</h1> <!-- Document introduction --> @@ -203,8 +199,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>This is a paragraph. It can contain just about any + <programlisting><![ CDATA [<p>This is a paragraph. It can contain just about any other element.</p>]]></programlisting> </example> </sect3> @@ -220,8 +215,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>A small excerpt from the US Constitution;</p> + <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 @@ -264,8 +258,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>An unordered list. Listitems will probably be + <programlisting><![ CDATA [<p>An unordered list. Listitems will probably be preceeded by bullets.</p> <ul> @@ -297,8 +290,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<dl> + <programlisting><![ CDATA [<dl> <dt>Term 1</dt> <dd><p>Paragraph 1 of definition 1.</p></dd> @@ -334,9 +326,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail message;</para> - <programlisting> -<![ CDATA [<pre> - From: nik@FreeBSD.org + <programlisting><![ CDATA [<pre> From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available @@ -347,8 +337,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> Comments appreciated. - N -</pre>]]></programlisting> + N</pre>]]></programlisting> </example> </sect3> @@ -376,8 +365,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>This is a simple 2x2 table.</p> + <programlisting><![ CDATA [<p>This is a simple 2x2 table.</p> <table> <tr> @@ -403,8 +391,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>One tall thin cell on the left, two short cells next to + <programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to it on the right.</p> <table> @@ -425,8 +412,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>One long cell on top, two short cells below it.</p> + <programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p> <table> <tr> @@ -447,8 +433,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of + <programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of cells merged in to one. The other cells are normal.</p> <table> @@ -461,7 +446,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <tr> <!-- Because the large cell on the left merges in to this row, the first <td> will occur on its - right --> + right --> <td>Middle right cell</td> </tr> @@ -498,8 +483,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p><em>This</em> has been emphasised, while + <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> </example> </sect3> @@ -515,8 +499,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <example> <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> - <programlisting> -<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is + <programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is in italics.</p>]]></programlisting> </example> </sect3> @@ -533,8 +516,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>This document was originally written by + <programlisting><![ CDATA [<p>This document was originally written by Nik Clayton, who can be reached by e-mail as <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> </example> @@ -575,8 +557,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>The following fragments all do the same thing.</para> - <programlisting> -<![ CDATA [<p>This text is <small>slightly smaller</small>. But + <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 @@ -613,8 +594,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>More information is available at the + <programlisting><![ CDATA [<p>More information is available at the <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> </example> @@ -638,8 +618,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced + <programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced in other links with the name <tt>para1</tt>.</p>]]></programlisting> </example> @@ -653,8 +632,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <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 + <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> @@ -669,8 +647,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Assume that the <literal>para1</literal> example resides in this document</para> - <programlisting> -<![ CDATA [<p>More information can be found in the + <programlisting><![ CDATA [<p>More information can be found in the <a href="#para1">first paragraph</a> of this document.</p>]]></programlisting> </example> @@ -725,6 +702,11 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> collaborating on a standard DocBook extension set, please get in touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para> </note> + + <para>The FreeBSD extensions are not (currently) in the ports + collection. It is a part of the Documentation Project source + repository, and can be found in + <filename>doc/share/sgml/freebsd.dtd</filename>.</para> </sect2> <sect2> @@ -734,18 +716,15 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> DocBook customisations, the FPI for the FreeBSD extended DocBook DTD is;</para> - <programlisting> -PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> </sect2> - - <sect2> - <title>Sectional elements</title> - <para>DocBook contains a number of elements for marking up the structure - of a book.</para> + <sect2> + <title>Document structure</title> - <para>Generally, the top level (first) element will be - <sgmltag>book</sgmltag>.</para> + <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 organised into <sgmltag>chapter</sgmltag>s. This is a mandatory requirement. There may be <sgmltag>part</sgmltag>s between @@ -759,6 +738,27 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <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 organised 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 in to 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 in to several + chapters, possibly with appendices and similar content as well.</para> + + <para>The <ulink url="http://www.FreeBSD.org/tutorials/">FreeBSD + tutorials</ulink> are all marked up as articles, while this + document, the <ulink url="http://www.FreeBSD.org/FAQ/">FreeBSD + FAQ</ulink>, and the <ulink + url="http://www.FreeBSD.org/handbook/">FreeBSD Handbook</ulink> are + all marked up as books.</para> + <sect3> <title>Starting a book</title> @@ -778,8 +778,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <!-- Can't put this in a marked section because of the replaceable elements --> - <programlisting> -<book> + <programlisting><book> <bookinfo> <title><replaceable>Your title here</replaceable></title> @@ -812,16 +811,66 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> </sect3> <sect3> + <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>This additional information should be contained within + <sgmltag>artheader</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>artheader</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting><article> + <artheader> + <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 e-mail address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <pubdate role="rcs">$Date$</pubdate> + + <releaseinfo>$Id$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</article></programlisting> + </example> + </sect3> + <sect3> <title>Indicating chapters</title> <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each - chapter has a mandatory <sgmltag>title</sgmltag>.</para> + chapter has a mandatory <sgmltag>title</sgmltag>. Articles do not + contain chapters, they are reserved for books.</para> <example> <title>A simple chapter</title> - <programlisting> -<![ CDATA [<chapter> + <programlisting><![ CDATA [<chapter> <title>The chapter's title</title> ... @@ -835,8 +884,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <example> <title>Empty chapters</title> - <programlisting> -<![ CDATA [<chapter> + <programlisting><![ CDATA [<chapter> <title>This is an empty chapter</title> <para></para> @@ -847,10 +895,13 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <sect3> <title>Sections below chapters</title> - <para>Chapters can be broken up into sections, subsections, and so - on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag> - element. The <replaceable>n</replaceable> indicates the section - number, which identifies the section level.</para> + <para>In books, chapters may (but do not need to) be broken up into + sections, subsections, and so on. In articles, sections are the + main structural element, and each article must contain at least one + section. Use the + <sgmltag>sect<replaceable>n</replaceable></sgmltag> element. The + <replaceable>n</replaceable> indicates the section number, which + identifies the section level.</para> <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is <sgmltag>sect1</sgmltag>. You can have one or more of these in a @@ -860,8 +911,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <example> <title>Sections in chapters</title> - <programlisting> -<![ CDATA [<chapter> + <programlisting><![ RCDATA [<chapter> <title>A sample chapter</title> <para>Some text in the chapter.</para> @@ -869,7 +919,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <sect1> <title>First section (1.1)</title> - ... + … </sect1> <sect1> @@ -881,18 +931,25 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <sect3> <title>First sub-sub-section (1.2.1.1)</title> - ... + … </sect3> </sect2> <sect2> <title>Second sub-section (1.2.2)</title> - ... + … </sect2> </sect1> </chapter>]]></programlisting> </example> + + <note> + <para>This example includes section numbers in the section titles. + You should not do this in your documents. Adding the section + numbers is carried out the by the stylesheets (of which more + later), and you do not need to manage them yourself.</para> + </note> </sect3> <sect3> @@ -900,10 +957,10 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>You can introduce another layer of organisation between <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or - more <sgmltag>part</sgmltag>s.</para> + more <sgmltag>part</sgmltag>s. This can not be done in an + <sgmltag>article</sgmltag>.</para> - <programlisting> -<![ CDATA [<part> + <programlisting><![ CDATA [<part> <title>Introduction</title> <chapter> @@ -948,8 +1005,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<para>This is a paragraph. It can contain just about any + <programlisting><![ CDATA [<para>This is a paragraph. It can contain just about any other element.</para> ]]></programlisting> <para>Appearance:</para> @@ -974,8 +1030,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<para>A small excerpt from the US Constitution;</para> + <programlisting><![ CDATA [<para>A small excerpt from the US Constitution;</para> <blockquote> <title>Preamble to the Constitution of the United States</title> @@ -1050,8 +1105,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<warning> + <programlisting><![ CDATA [<warning> <para>Installing FreeBSD may make you want to delete Windows from your harddisk.</para> </warning>]]></programlisting> @@ -1100,8 +1154,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<itemizedlist> + <programlisting><![ CDATA [<itemizedlist> <listitem> <para>This is the first itemized item.</para> </listitem> @@ -1119,7 +1172,21 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <listitem> <para>This is the second ordered item.</para> </listitem> -</orderedlist>]]></programlisting> +</orderedlist> + +<procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <para>And now do this.</para> + </step> +</procedure>]]></programlisting> <para>Appearance:</para> @@ -1143,6 +1210,22 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> </listitem> </orderedlist> </example> + + <!-- Can't have <procedure> inside <example>, so this is a cheat --> + + <procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <para>And now do this.</para> + </step> + </procedure> </sect3> <sect3> @@ -1154,21 +1237,20 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>White space and line breaks within <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> - significant. In particular, this means that the closing tag should - appear on the same line as the last line of the output, otherwise a - spurious blank line will be included.</para> + significant. In particular, this means that the opening tag should + appear on the same line as the first line of the output, and the + closing tag should appear on the same line as the last line of the + output, otherwise spurious blank lines may be included.</para> <example> <title><sgmltag>programlisting</sgmltag></title> <para>Use:</para> - <programlisting> -<![ CDATA[<para>When you have finished, your program should look like + <programlisting><![ CDATA[<para>When you have finished, your program should look like this;</para> -<programlisting> -#include <stdio.h> +<programlisting>#include <stdio.h> int main(void) @@ -1185,8 +1267,7 @@ main(void) <para>When you have finished, your program should look like this;</para> - <programlisting> -#include <stdio.h> + <programlisting>#include <stdio.h> int main(void) @@ -1234,8 +1315,7 @@ main(void) <para>Use:</para> - <programlisting> -<![ CDATA [<informaltable> + <programlisting><![ CDATA [<informaltable> <tgroup cols="2"> <thead> <row> @@ -1333,19 +1413,6 @@ main(void) <variablelist> <varlistentry> - <term><sgmltag>informalexample</sgmltag></term> - - <listitem> - <para>Most of the time these examples will occur - “mid-flow” as it were, and you won't need to put a - title on them. So, most of the time, the outermost element - will be <sgmltag>informalexample</sgmltag>. For those times - when you do need to include a title on the example, use - <sgmltag>example</sgmltag>.</para> - </listitem> - </varlistentry> - - <varlistentry> <term><sgmltag>screen</sgmltag></term> <listitem> @@ -1397,15 +1464,12 @@ main(void) </variablelist> <example> - <title><sgmltag>informalexample</sgmltag>, - <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and + <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and <sgmltag>userinput</sgmltag></title> <para>Use:</para> - <programlisting> -<![ CDATA [<informalexample> - <screen>&prompt.user; <userinput>ls -1</userinput> + <programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput> foo1 foo2 foo3 @@ -1414,12 +1478,10 @@ foo2 &prompt.user; <userinput>su</userinput> <prompt>Password: </prompt> &prompt.root; <userinput>cat foo2</userinput> -This is the file called 'foo2'</screen> -</informalexample>]]></programlisting> +This is the file called 'foo2'</screen>]]></programlisting> - <para>Appearance:</para> + <para>Appearance:</para> - <informalexample> <screen>&prompt.user; <userinput>ls -1</userinput> foo1 foo2 @@ -1430,7 +1492,6 @@ foo2 <prompt>Password: </prompt> &prompt.root; <userinput>cat foo2</userinput> This is the file called 'foo2'</screen> - </informalexample> </example> <note> @@ -1466,8 +1527,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> + <programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> <para>Appearance:</para> @@ -1526,7 +1586,7 @@ This is the file called 'foo2'</screen> … -]]></programlisting> +]></programlisting> <para>Use <sgmltag>command</sgmltag> when you want to include a command name “in-line” but present it as something the @@ -1543,8 +1603,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para><application>Sendmail</application> is the most + <programlisting><![ CDATA [<para><application>Sendmail</application> is the most widely used Unix mail application.</para> <para><application>Sendmail</application> includes the @@ -1603,8 +1662,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The SGML source for the Handbook in English can be + <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be found in <filename>/usr/doc/en/handbook/</filename>. The first file is called <filename>handbook.sgml</filename> in that directory. You should also see a <filename>Makefile</filename> @@ -1645,8 +1703,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para><devicename>sio</devicename> is used for serial + <programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial communication in FreeBSD. <devicename>sio</devicename> manifests through a number of entries in <filename>/dev</filename>, including <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> @@ -1761,8 +1818,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The local machine can always be referred to by the + <programlisting><![ CDATA [<para>The local machine can always be referred to by the name <hostid>localhost</hostid>, which will have the IP address <hostid role="ipaddr">127.0.0.1</hostid>.</para> @@ -1823,8 +1879,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>To carry out most system administration functions you + <programlisting><![ CDATA [<para>To carry out most system administration functions you will need to be <username>root</username>.</para>]]></programlisting> <para>Appearance:</para> @@ -1861,8 +1916,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>Two common targets in a <filename>Makefile</filename> + <programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename> are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> <para>Typically, invoking <maketarget>all</maketarget> will rebuild the @@ -1912,8 +1966,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel + <programlisting><![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.</para>]]></programlisting> @@ -1945,8 +1998,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<informalexample> + <programlisting><![ CDATA [<informalexample> <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> </informalexample>]]></programlisting> @@ -1964,8 +2016,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal> + <programlisting><![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal> line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.</para> @@ -2015,8 +2066,7 @@ This is the file called 'foo2'</screen> <example> <title><literal>id on chapters and sections</literal></title> - <programlisting> -<![ CDATA [<chapter id="chapter1"> + <programlisting><![ CDATA [<chapter id="chapter1"> <title>Introduction</title> <para>This is the introduction. It contains a subsection, @@ -2045,8 +2095,7 @@ This is the file called 'foo2'</screen> <example> <title><sgmltag>anchor</sgmltag></title> - <programlisting> -<![ CDATA [<para>This paragraph has an embedded + <programlisting><![ CDATA [<para>This paragraph has an embedded <anchor id="para1">link target in it. It won't show up in the document.</para>]]></programlisting> </example> @@ -2071,8 +2120,7 @@ This is the file called 'foo2'</screen> <para>Assume that this fragment appears somewhere in a document that includes the <literal>id</literal> example;</para> - <programlisting> -<![ CDATA [<para>More information can be found + <programlisting><![ CDATA [<para>More information can be found in <xref linkend="chapter1">.</para> <para>More specific information can be found @@ -2113,8 +2161,7 @@ This is the file called 'foo2'</screen> <para>Assume that this fragment appears somewhere in a document that includes the <literal>id</literal> example.</para> - <programlisting> -<![ CDATA [<para>More information can be found in + <programlisting><![ CDATA [<para>More information can be found in <link linkend="chapter1">the first chapter</link>.</para> <para>More specific information can be found in @@ -2164,8 +2211,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>Of course, you could stop reading this document and + <programlisting><![ CDATA [<para>Of course, you could stop reading this document and go to the <ulink url="http://www.FreeBSD.org/">FreeBSD home page</ulink> instead.</para>]]></programlisting> diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 2d74c89f07..71959ba6a4 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -27,7 +27,7 @@ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $Id: chapter.sgml,v 1.7 1999-08-30 11:53:03 jhb Exp $ + $Id: chapter.sgml,v 1.8 1999-09-03 17:16:06 nik Exp $ --> <chapter id="sgml-markup"> @@ -93,8 +93,7 @@ <para>The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0.</para> - <programlisting> -PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + <programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> </sect2> <sect2> @@ -114,8 +113,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <example> <title>Normal HTML document structure</title> - <programlisting> -<html> + <programlisting><html> <head> <title><replaceable>The document's title</replaceable></title> </head> @@ -149,8 +147,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<h1>First section</h1> + <programlisting><![ CDATA [<h1>First section</h1> <!-- Document introduction goes here --> @@ -181,8 +178,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<h1>First section</h1> + <programlisting><![ CDATA [<h1>First section</h1> <!-- Document introduction --> @@ -203,8 +199,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>This is a paragraph. It can contain just about any + <programlisting><![ CDATA [<p>This is a paragraph. It can contain just about any other element.</p>]]></programlisting> </example> </sect3> @@ -220,8 +215,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>A small excerpt from the US Constitution;</p> + <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 @@ -264,8 +258,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>An unordered list. Listitems will probably be + <programlisting><![ CDATA [<p>An unordered list. Listitems will probably be preceeded by bullets.</p> <ul> @@ -297,8 +290,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<dl> + <programlisting><![ CDATA [<dl> <dt>Term 1</dt> <dd><p>Paragraph 1 of definition 1.</p></dd> @@ -334,9 +326,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail message;</para> - <programlisting> -<![ CDATA [<pre> - From: nik@FreeBSD.org + <programlisting><![ CDATA [<pre> From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available @@ -347,8 +337,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> Comments appreciated. - N -</pre>]]></programlisting> + N</pre>]]></programlisting> </example> </sect3> @@ -376,8 +365,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>This is a simple 2x2 table.</p> + <programlisting><![ CDATA [<p>This is a simple 2x2 table.</p> <table> <tr> @@ -403,8 +391,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>One tall thin cell on the left, two short cells next to + <programlisting><![ CDATA [<p>One tall thin cell on the left, two short cells next to it on the right.</p> <table> @@ -425,8 +412,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>One long cell on top, two short cells below it.</p> + <programlisting><![ CDATA [<p>One long cell on top, two short cells below it.</p> <table> <tr> @@ -447,8 +433,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of + <programlisting><![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of cells merged in to one. The other cells are normal.</p> <table> @@ -461,7 +446,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <tr> <!-- Because the large cell on the left merges in to this row, the first <td> will occur on its - right --> + right --> <td>Middle right cell</td> </tr> @@ -498,8 +483,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p><em>This</em> has been emphasised, while + <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> </example> </sect3> @@ -515,8 +499,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <example> <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> - <programlisting> -<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is + <programlisting><![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is in italics.</p>]]></programlisting> </example> </sect3> @@ -533,8 +516,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>This document was originally written by + <programlisting><![ CDATA [<p>This document was originally written by Nik Clayton, who can be reached by e-mail as <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> </example> @@ -575,8 +557,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>The following fragments all do the same thing.</para> - <programlisting> -<![ CDATA [<p>This text is <small>slightly smaller</small>. But + <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 @@ -613,8 +594,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p>More information is available at the + <programlisting><![ CDATA [<p>More information is available at the <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> </example> @@ -638,8 +618,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced + <programlisting><![ CDATA [<p><a name="para1">This</a> paragraph can be referenced in other links with the name <tt>para1</tt>.</p>]]></programlisting> </example> @@ -653,8 +632,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <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 + <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> @@ -669,8 +647,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <para>Assume that the <literal>para1</literal> example resides in this document</para> - <programlisting> -<![ CDATA [<p>More information can be found in the + <programlisting><![ CDATA [<p>More information can be found in the <a href="#para1">first paragraph</a> of this document.</p>]]></programlisting> </example> @@ -725,6 +702,11 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> collaborating on a standard DocBook extension set, please get in touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para> </note> + + <para>The FreeBSD extensions are not (currently) in the ports + collection. It is a part of the Documentation Project source + repository, and can be found in + <filename>doc/share/sgml/freebsd.dtd</filename>.</para> </sect2> <sect2> @@ -734,18 +716,15 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> DocBook customisations, the FPI for the FreeBSD extended DocBook DTD is;</para> - <programlisting> -PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> </sect2> - - <sect2> - <title>Sectional elements</title> - <para>DocBook contains a number of elements for marking up the structure - of a book.</para> + <sect2> + <title>Document structure</title> - <para>Generally, the top level (first) element will be - <sgmltag>book</sgmltag>.</para> + <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 organised into <sgmltag>chapter</sgmltag>s. This is a mandatory requirement. There may be <sgmltag>part</sgmltag>s between @@ -759,6 +738,27 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <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 organised 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 in to 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 in to several + chapters, possibly with appendices and similar content as well.</para> + + <para>The <ulink url="http://www.FreeBSD.org/tutorials/">FreeBSD + tutorials</ulink> are all marked up as articles, while this + document, the <ulink url="http://www.FreeBSD.org/FAQ/">FreeBSD + FAQ</ulink>, and the <ulink + url="http://www.FreeBSD.org/handbook/">FreeBSD Handbook</ulink> are + all marked up as books.</para> + <sect3> <title>Starting a book</title> @@ -778,8 +778,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <!-- Can't put this in a marked section because of the replaceable elements --> - <programlisting> -<book> + <programlisting><book> <bookinfo> <title><replaceable>Your title here</replaceable></title> @@ -812,16 +811,66 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> </sect3> <sect3> + <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>This additional information should be contained within + <sgmltag>artheader</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>artheader</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting><article> + <artheader> + <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 e-mail address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <pubdate role="rcs">$Date$</pubdate> + + <releaseinfo>$Id$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</article></programlisting> + </example> + </sect3> + <sect3> <title>Indicating chapters</title> <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each - chapter has a mandatory <sgmltag>title</sgmltag>.</para> + chapter has a mandatory <sgmltag>title</sgmltag>. Articles do not + contain chapters, they are reserved for books.</para> <example> <title>A simple chapter</title> - <programlisting> -<![ CDATA [<chapter> + <programlisting><![ CDATA [<chapter> <title>The chapter's title</title> ... @@ -835,8 +884,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <example> <title>Empty chapters</title> - <programlisting> -<![ CDATA [<chapter> + <programlisting><![ CDATA [<chapter> <title>This is an empty chapter</title> <para></para> @@ -847,10 +895,13 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <sect3> <title>Sections below chapters</title> - <para>Chapters can be broken up into sections, subsections, and so - on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag> - element. The <replaceable>n</replaceable> indicates the section - number, which identifies the section level.</para> + <para>In books, chapters may (but do not need to) be broken up into + sections, subsections, and so on. In articles, sections are the + main structural element, and each article must contain at least one + section. Use the + <sgmltag>sect<replaceable>n</replaceable></sgmltag> element. The + <replaceable>n</replaceable> indicates the section number, which + identifies the section level.</para> <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is <sgmltag>sect1</sgmltag>. You can have one or more of these in a @@ -860,8 +911,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <example> <title>Sections in chapters</title> - <programlisting> -<![ CDATA [<chapter> + <programlisting><![ RCDATA [<chapter> <title>A sample chapter</title> <para>Some text in the chapter.</para> @@ -869,7 +919,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <sect1> <title>First section (1.1)</title> - ... + … </sect1> <sect1> @@ -881,18 +931,25 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <sect3> <title>First sub-sub-section (1.2.1.1)</title> - ... + … </sect3> </sect2> <sect2> <title>Second sub-section (1.2.2)</title> - ... + … </sect2> </sect1> </chapter>]]></programlisting> </example> + + <note> + <para>This example includes section numbers in the section titles. + You should not do this in your documents. Adding the section + numbers is carried out the by the stylesheets (of which more + later), and you do not need to manage them yourself.</para> + </note> </sect3> <sect3> @@ -900,10 +957,10 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>You can introduce another layer of organisation between <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or - more <sgmltag>part</sgmltag>s.</para> + more <sgmltag>part</sgmltag>s. This can not be done in an + <sgmltag>article</sgmltag>.</para> - <programlisting> -<![ CDATA [<part> + <programlisting><![ CDATA [<part> <title>Introduction</title> <chapter> @@ -948,8 +1005,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<para>This is a paragraph. It can contain just about any + <programlisting><![ CDATA [<para>This is a paragraph. It can contain just about any other element.</para> ]]></programlisting> <para>Appearance:</para> @@ -974,8 +1030,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<para>A small excerpt from the US Constitution;</para> + <programlisting><![ CDATA [<para>A small excerpt from the US Constitution;</para> <blockquote> <title>Preamble to the Constitution of the United States</title> @@ -1050,8 +1105,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<warning> + <programlisting><![ CDATA [<warning> <para>Installing FreeBSD may make you want to delete Windows from your harddisk.</para> </warning>]]></programlisting> @@ -1100,8 +1154,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>Use:</para> - <programlisting> -<![ CDATA [<itemizedlist> + <programlisting><![ CDATA [<itemizedlist> <listitem> <para>This is the first itemized item.</para> </listitem> @@ -1119,7 +1172,21 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <listitem> <para>This is the second ordered item.</para> </listitem> -</orderedlist>]]></programlisting> +</orderedlist> + +<procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <para>And now do this.</para> + </step> +</procedure>]]></programlisting> <para>Appearance:</para> @@ -1143,6 +1210,22 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> </listitem> </orderedlist> </example> + + <!-- Can't have <procedure> inside <example>, so this is a cheat --> + + <procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <para>And now do this.</para> + </step> + </procedure> </sect3> <sect3> @@ -1154,21 +1237,20 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting> <para>White space and line breaks within <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> - significant. In particular, this means that the closing tag should - appear on the same line as the last line of the output, otherwise a - spurious blank line will be included.</para> + significant. In particular, this means that the opening tag should + appear on the same line as the first line of the output, and the + closing tag should appear on the same line as the last line of the + output, otherwise spurious blank lines may be included.</para> <example> <title><sgmltag>programlisting</sgmltag></title> <para>Use:</para> - <programlisting> -<![ CDATA[<para>When you have finished, your program should look like + <programlisting><![ CDATA[<para>When you have finished, your program should look like this;</para> -<programlisting> -#include <stdio.h> +<programlisting>#include <stdio.h> int main(void) @@ -1185,8 +1267,7 @@ main(void) <para>When you have finished, your program should look like this;</para> - <programlisting> -#include <stdio.h> + <programlisting>#include <stdio.h> int main(void) @@ -1234,8 +1315,7 @@ main(void) <para>Use:</para> - <programlisting> -<![ CDATA [<informaltable> + <programlisting><![ CDATA [<informaltable> <tgroup cols="2"> <thead> <row> @@ -1333,19 +1413,6 @@ main(void) <variablelist> <varlistentry> - <term><sgmltag>informalexample</sgmltag></term> - - <listitem> - <para>Most of the time these examples will occur - “mid-flow” as it were, and you won't need to put a - title on them. So, most of the time, the outermost element - will be <sgmltag>informalexample</sgmltag>. For those times - when you do need to include a title on the example, use - <sgmltag>example</sgmltag>.</para> - </listitem> - </varlistentry> - - <varlistentry> <term><sgmltag>screen</sgmltag></term> <listitem> @@ -1397,15 +1464,12 @@ main(void) </variablelist> <example> - <title><sgmltag>informalexample</sgmltag>, - <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and + <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and <sgmltag>userinput</sgmltag></title> <para>Use:</para> - <programlisting> -<![ CDATA [<informalexample> - <screen>&prompt.user; <userinput>ls -1</userinput> + <programlisting><![ CDATA [<screen>&prompt.user; <userinput>ls -1</userinput> foo1 foo2 foo3 @@ -1414,12 +1478,10 @@ foo2 &prompt.user; <userinput>su</userinput> <prompt>Password: </prompt> &prompt.root; <userinput>cat foo2</userinput> -This is the file called 'foo2'</screen> -</informalexample>]]></programlisting> +This is the file called 'foo2'</screen>]]></programlisting> - <para>Appearance:</para> + <para>Appearance:</para> - <informalexample> <screen>&prompt.user; <userinput>ls -1</userinput> foo1 foo2 @@ -1430,7 +1492,6 @@ foo2 <prompt>Password: </prompt> &prompt.root; <userinput>cat foo2</userinput> This is the file called 'foo2'</screen> - </informalexample> </example> <note> @@ -1466,8 +1527,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> + <programlisting><![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> <para>Appearance:</para> @@ -1526,7 +1586,7 @@ This is the file called 'foo2'</screen> … -]]></programlisting> +]></programlisting> <para>Use <sgmltag>command</sgmltag> when you want to include a command name “in-line” but present it as something the @@ -1543,8 +1603,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para><application>Sendmail</application> is the most + <programlisting><![ CDATA [<para><application>Sendmail</application> is the most widely used Unix mail application.</para> <para><application>Sendmail</application> includes the @@ -1603,8 +1662,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The SGML source for the Handbook in English can be + <programlisting><![ CDATA [<para>The SGML source for the Handbook in English can be found in <filename>/usr/doc/en/handbook/</filename>. The first file is called <filename>handbook.sgml</filename> in that directory. You should also see a <filename>Makefile</filename> @@ -1645,8 +1703,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para><devicename>sio</devicename> is used for serial + <programlisting><![ CDATA [<para><devicename>sio</devicename> is used for serial communication in FreeBSD. <devicename>sio</devicename> manifests through a number of entries in <filename>/dev</filename>, including <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> @@ -1761,8 +1818,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The local machine can always be referred to by the + <programlisting><![ CDATA [<para>The local machine can always be referred to by the name <hostid>localhost</hostid>, which will have the IP address <hostid role="ipaddr">127.0.0.1</hostid>.</para> @@ -1823,8 +1879,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>To carry out most system administration functions you + <programlisting><![ CDATA [<para>To carry out most system administration functions you will need to be <username>root</username>.</para>]]></programlisting> <para>Appearance:</para> @@ -1861,8 +1916,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>Two common targets in a <filename>Makefile</filename> + <programlisting><![ CDATA [<para>Two common targets in a <filename>Makefile</filename> are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> <para>Typically, invoking <maketarget>all</maketarget> will rebuild the @@ -1912,8 +1966,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel + <programlisting><![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.</para>]]></programlisting> @@ -1945,8 +1998,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<informalexample> + <programlisting><![ CDATA [<informalexample> <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> </informalexample>]]></programlisting> @@ -1964,8 +2016,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal> + <programlisting><![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal> line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.</para> @@ -2015,8 +2066,7 @@ This is the file called 'foo2'</screen> <example> <title><literal>id on chapters and sections</literal></title> - <programlisting> -<![ CDATA [<chapter id="chapter1"> + <programlisting><![ CDATA [<chapter id="chapter1"> <title>Introduction</title> <para>This is the introduction. It contains a subsection, @@ -2045,8 +2095,7 @@ This is the file called 'foo2'</screen> <example> <title><sgmltag>anchor</sgmltag></title> - <programlisting> -<![ CDATA [<para>This paragraph has an embedded + <programlisting><![ CDATA [<para>This paragraph has an embedded <anchor id="para1">link target in it. It won't show up in the document.</para>]]></programlisting> </example> @@ -2071,8 +2120,7 @@ This is the file called 'foo2'</screen> <para>Assume that this fragment appears somewhere in a document that includes the <literal>id</literal> example;</para> - <programlisting> -<![ CDATA [<para>More information can be found + <programlisting><![ CDATA [<para>More information can be found in <xref linkend="chapter1">.</para> <para>More specific information can be found @@ -2113,8 +2161,7 @@ This is the file called 'foo2'</screen> <para>Assume that this fragment appears somewhere in a document that includes the <literal>id</literal> example.</para> - <programlisting> -<![ CDATA [<para>More information can be found in + <programlisting><![ CDATA [<para>More information can be found in <link linkend="chapter1">the first chapter</link>.</para> <para>More specific information can be found in @@ -2164,8 +2211,7 @@ This is the file called 'foo2'</screen> <para>Use:</para> - <programlisting> -<![ CDATA [<para>Of course, you could stop reading this document and + <programlisting><![ CDATA [<para>Of course, you could stop reading this document and go to the <ulink url="http://www.FreeBSD.org/">FreeBSD home page</ulink> instead.</para>]]></programlisting> |