sampleChapter.xml

File contents

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.7//EN" "docbookx.dtd">
<chapter>  
  <!-- the docinfo element contains information about
       about the chapter. -->
  <docinfo> 

    <!-- you can include as many authors as you wish -->
	 <author> 
		<firstname>Amos</firstname> 
		<surname>Latteier</surname> 
	 </author> 
	 <author> 
		<firstname>Someone</firstname> 
		<surname>Else</surname> 
	 </author> 
	 
	 <!-- releaseinfo contains cvs information, this
	      is automatically updated when you check
			the file in to cvs. -->
	 <releaseinfo> $Id: sampleChapter.xml,v 1.2 1999/12/21 23:26:00 docsamos Exp$ </releaseinfo> 
  </docinfo> 
  <title>Example Chapter</title> 
 
  <para> This is a sample DocBook chapter. Each chapter should be a separate
	 file. Since the DocBook DTD is large, I recommend using a subset of DocBook for
	 most purposes. This chapter will demonstrate recommended usage. </para>

  <section> 
	 <title>Block organization</title> 
 
	 <section> 
		<title>Basic blocks</title> 
 
		<para>The main levels of document organization are:</para>

		<orderedlist> 
		  <listitem> 
 
			 <para>book</para>

		  </listitem> 
		  <listitem> 
 
			 <para>chapter</para>

		  </listitem> 
		  <listitem> 
 
			 <para>section</para>

		  </listitem> 
		  <listitem> 
 
			 <para>para</para>

		  </listitem> 
		</orderedlist> 
 
		<para>A <literal>book</literal> represents a complete piece of
		  documentation, for example, the ZCMG would be a book. A
		  <literal>chapter</literal> represents a chapter of the book. Chapters normally
		  should be separate files. Each chapter can contain multiple
		  <literal>sections</literal>. Each section can contain additional
		  <literal>sections</literal> nested arbitrarily deep. Finally each section
		  contains paragraphs which are marked by the <literal>para</literal> tag.
		  </para>

	 </section>

	 <section> 
		<title>Other blocks</title> 
 
		<para>Other common blocks include <literal>programlistings</literal> and
		  inline images such as <literal>screenshoots</literal>. </para>

		<para>Program listings should be used for snippets of Python and DTML
		  code. For example: </para>

		<programlisting>class FooBar:
    """A sample class"""
	 def __init__(self, id):
	     self.id=id
	
	 def foo(self):
	     "do foo"
		  return "foo %s" % self.id</programlisting> 
 
		<para>In xml you need to escape &gt; and &lt; and &amp;. You can do this
		  is entities or by using CDATA sections. If the programlisting is used for DTML
		  you should probably include the content in a CDATA section to escape the DTML
		  tags. For example: </para>

		<programlisting><![CDATA[<dtml in objectValues>
<a href="&absolute_url;"><dtml-var id></a><br>
</dtml-in>]]></programlisting> 
 
		<para>Screenshots should be indicated like this: </para>

		<figure> 
		  <title>A sample screen shot title.</title> 
		  <screenshot> 
			 <mediaobject> 
				<imageobject> <imagedata fileref="sample.gif" format="GIF"/> 
				</imageobject> 
			 </mediaobject> 
		  </screenshot> 
		</figure> 
 
		<para>Screenshots are one of the most complex things you'll have to deal
		  with in DocBook. Note, you can use the same method for displaying
		  non-screenshot graphics. Simply don't wrap the <literal>mediaobject</literal>
		  with a <literal>screenshot</literal> tag.</para>

	 </section>

  </section>

  <section> 
	 <title>Markup</title> 
 
	 <para>In addition to blocks of content, you will need to mark up words and
		phrases to indicate a particular style. </para>

	 <para>For computer names such as names of programs, packages, functions,
		classes, and the like, use the <literal>literal</literal> tag. </para>

	 <para> Occasionally you may want to emphasize something such as a word
		which should be stressed in a sentence. Use the <literal>emphasis</literal>
		tag. <emphasis>Like this.</emphasis> Don't use emphasis for titles. Instead you
		<literal>citetitle</literal> if you are referring to the title of a book or
		article. </para>

	 <section> 
		<title>Lists</title> 
 
		<para>DocBook provides several types of lists, along the same lines as
		  HTML. All lists are composed of a collection of <literal>listitems</literal>.
		  Here are two examples: </para>

		<itemizedlist> 
		  <listitem> 
 
			 <para>One thing.</para>

		  </listitem> 
		  <listitem> 
 
			 <para>Another thing.</para>

		  </listitem> 
		</itemizedlist> 
		<orderedlist> 
		  <listitem> 
 
			 <para>First thing.</para>

		  </listitem> 
		  <listitem> 
 
			 <para>Second thing.</para>

		  </listitem> 
		</orderedlist> 
	 </section>

	 <section> 
		<title>Tables</title> 
 
		<para>DocBook tables are similar to HTML tables. They are rather verbose.
		  Here's an example: </para>

		<table> 
		<title>A sample table.</title> 
		<tgroup cols="2"> 
		  <thead> 
			 <row> 
				<entry>Header 1</entry> 
				<entry>Header 2</entry> 
			 </row> 
		  </thead> 
		  <tbody> 
			 <row> 
				<entry>foo</entry> 
				<entry>foo is like food.</entry> 
			 </row> 
			 <row> 
				<entry>bar</entry> 
				<entry>bar is like bark.</entry> 
			 </row> 
		  </tbody> 
		</tgroup> 
		</table> 
	 </section>

	 <section id="my_id"> 
		<title>Cross References</title> 
 
		<para>DocBook handles cross references easily. The basic way to do this
		  is to create an <literal>id</literal> attribute on the object you want to link
		  to and then create an <literal>xref</literal> tag to link to it. For
		  example:</para>

		<para>In <xref linkend="my_id"/> you can find information on cross
		  references. Note that it is up to DocBook to include appropriate link text
		  identifying to linked to object.</para>

		<para>If you want to create hyperlinks to web resources use the
		  <literal>ulink</literal>tag. For example, the 
		  <ulink
			url="http://www.nwalsh.com/docbook/xml/index.html">DocBook</ulink>DTD is
		  available on-line.</para>

	 </section>

  </section>

</chapter>