10.5 Tutorial Meta-Tutorial

by Martin Grimme

10.5.1 Introduction

You can contribute to the tutorials chapter by writing new tutorials. This meta-tutorial shows you how to write compliant tutorials for this book.

10.5.2 DocBook

DocBook is a widely used standard for writing documentation. It is a semantic markup language based on SGML. Recently, DocBook has been ported to XSLT stylesheets, so that any XSLT processor can process DocBook sources. The XSLT stylesheets we are using for generating HTML pages are those of the yelp project, because they are fast and produce good output.

It's not the purpose of this tutorial to teach you DocBook. There are plenty of other tutorials available, which do a much better job at that. Here is a collection of resources to get you started with DocBook:

http://www.docbook.org - The home of DocBook. You can find lots of information and documentation there.
http://docbook.sourceforge.net - The DocBook Open Repository is the official home of the DocBook stylesheets.
http://www.docbook.org/tdg/en/html/docbook.html - DocBook: The Definitive Guide. The name says it all. This is the online version of the most comprehensive DocBook book out there by Norman Walsh and Leonard Muellner.
http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/index.html - GNOME Handbook of Writing Software Documentation. This online book is a good source of information for writing software documentation with DocBook.
http://www.bartleby.com/141/ - The Elements of Style. This book is about good writing style.

10.5.3 Template

To make stuff look uniform, please use the provided template for writing tutorials. You can copy and paste it into a new file from below:

<section id="tutor-TEMPLATE"  xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Title of the Tutorial</title>

<para>by Your Name</para>


<section><title>Introduction</title>

  <para>Some introductory text about what the reader will find in the tutorial.
    </para>
     
</section>



<section><title>Section 1</title>

  <para>blah blah blah...</para>

</section>



<section><title>Another Section</title>

  <para>Some more blah blah blah...</para>

</section>


</section>

The filename must start with "tutor-" and have the extension ".xml". After the hyphen, you include the (abbreviated) name of your tutorial. This name must be unique within the whole book. The same name with the "tutor-" prefix goes into the id attribute in the section tag in the first line of the document.

10.5.4 Screenshots

A picture is worth a thousand words. Screenshots (and diagrams) help you illustrate what you're talking about. Please make good use of them because the reader will appreciate it.

Screenshots can be included in DocBook like this:

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="gfx/my-image" format="PNG"/>
    </imageobject>
  </mediaobject>
</screenshot>

Please note that the filename does not get the suffix here. The file itself has the .png suffix, of course. The included files have to be in the PNG format (GIF used to be non-free and is now deprecated, and JPEG isn't free either).

The filename of the screenshot must be unique within the book, too. It is recommended to start all filenames with the (abbreviated) name of your tutorial.

10.5.5 Showing XML

In a tutorial for gDesklets, it's often necessary to show example code which is XML. Example code can be displayed with the <programlisting> tag:

<programlisting>

  ...

</programlisting>

A problem, however, is that the XML code of course uses characters which are reserved by XML, such as "<" and ">". You can get around this limitation by putting the example into a CDATA section:

<programlisting><![CDATA[

  ...

]]></programlisting>

There remains only one problem: CDATA sections cannot be nested. So, what if your example contains CDATA sections as well?

The solution is to split the CDATA section into two CDATA sections at the point where the CDATA section in the example code ends:

<programlisting><![CDATA[

  <![CDATA[ ... ]]>

]]></programlisting>

must be written as

<programlisting><![CDATA[

  ...
  <![CDATA[ ... ]]>]]&gt;<![CDATA[
  
]]></programlisting>

This might look confusing at first, but the simple rule is that every occurrence of "]]>" has just to be extended with "]]><![CDATA[".

10.5.6 Previewing Your Work

To preview the new tutorial file, you have to embed it into a valid DocBook file. The tutorial file is just a section and not a complete DocBook file.

The easiest way to embed it into a DocBook file is by getting the DocBook sources of this book from CVS and include your file in the tutorials chapter.

You can retrieve the DocBook sources like this:

    $> export CVSROOT=:pserver:anonymous@anoncvs.gnome.org/cvs/gnome
    $> cvs login
    (press Enter when asked for a password)
    $> cvs co gdesklets/doc/book

Then you can include your tutorial in the file tutor.xml using XInclude like this:

...

  <xi:include href="tutor-xml.xml"/>
  <xi:include href="tutor-hello.xml"/>
  <xi:include href="tutor-canvas.xml"/>
  ...
  <xi:include href="tutor-mytutorial.xml"/>

...

The book can be previewed with the yelp tool of the GNOME desktop:

    $> yelp ghelp://$PWD/book.xml

The script make-html.sh can be called to convert the DocBook files to HTML using the yelp stylesheets (yelp must be installed):

    $> ./make-html.sh book.xml output

The book can then be found in output/index.html.