1
<section id="tutor-tutor" xmlns:xi="http://www.w3.org/2001/XInclude">
2
<title>Tutorial Meta-Tutorial</title>
4
<para>by Martin Grimme</para>
7
<section><title>Introduction</title>
9
<para>You can contribute to the tutorials chapter by writing new tutorials.
10
This meta-tutorial shows you how to write compliant tutorials for this
17
<section><title>DocBook</title>
19
<para>DocBook is a widely used standard for writing documentation. It is a
20
semantic markup language based on SGML. Recently, DocBook has been ported
21
to XSLT stylesheets, so that any XSLT processor can process DocBook sources.
22
The XSLT stylesheets we are using for generating HTML pages are those of
23
the <application>yelp</application> project, because they are fast and
24
produce good output.</para>
26
<para>It's not the purpose of this tutorial to teach you DocBook. There are
27
plenty of other tutorials available, which do a much better job at that.
28
Here is a collection of resources to get you started with DocBook:</para>
31
<listitem><ulink url="http://www.docbook.org"/> - The home of DocBook. You
32
can find lots of information and documentation there.</listitem>
33
<listitem><ulink url="http://docbook.sourceforge.net"/> - The DocBook Open
34
Repository is the official home of the DocBook stylesheets.</listitem>
35
<listitem><ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/> -
36
DocBook: The Definitive Guide. The name says it all. This is the online
37
version of the most comprehensive DocBook book out there by
38
Norman Walsh and Leonard Muellner.</listitem>
39
<listitem><ulink url="http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/index.html"/> -
40
GNOME Handbook of Writing Software Documentation. This online book is a
41
good source of information for writing software documentation with
43
<listitem><ulink url="http://www.bartleby.com/141/"/> - The Elements of
44
Style. This book is about good writing style.</listitem>
51
<section><title>Template</title>
53
<para>To make stuff look uniform, please use the provided template for
54
writing tutorials. You can copy and paste it into a new file from below:
57
<literallayout><xi:include href="tutor-TEMPLATE.xml" parse="text"/></literallayout>
59
<para>The filename must start with "<filename>tutor-</filename>" and have the
60
extension "<filename>.xml</filename>". After the hyphen, you include the
61
(abbreviated) name of your tutorial. This name must be unique within the
62
whole book. The same name with the "<literal>tutor-</literal>" prefix goes
63
into the <property>id</property> attribute in the <command>section</command>
64
tag in the first line of the document.</para>
70
<section><title>Screenshots</title>
72
<para>A picture is worth a thousand words. Screenshots (and diagrams) help you
73
illustrate what you're talking about. Please make good use of them because
74
the reader will appreciate it.</para>
76
<para>Screenshots can be included in DocBook like this:</para>
78
<programlisting><![CDATA[
82
<imagedata fileref="gfx/my-image" format="PNG"/>
88
<para>Please note that the filename does not get the suffix here. The file
89
itself has the <filename>.png</filename> suffix, of course. The included
90
files have to be in the PNG format (GIF used to be non-free and is now
91
deprecated, and JPEG isn't free either).</para>
93
<para>The filename of the screenshot must be unique within the book, too.
94
It is recommended to start all filenames with the (abbreviated) name of
101
<section><title>Showing XML</title>
103
<para>In a tutorial for <application>gDesklets</application>, it's often
104
necessary to show example code which is XML. Example code can be
105
displayed with the <command><programlisting></command> tag:</para>
107
<programlisting><![CDATA[
115
<para>A problem, however, is that the XML code of course uses characters
116
which are reserved by XML, such as "<" and ">". You can get around
117
this limitation by putting the example into a CDATA section:</para>
119
<programlisting><![CDATA[
120
<programlisting><![CDATA[
124
]]>]]><![CDATA[</programlisting>
127
<para>There remains only one problem: CDATA sections cannot be nested. So,
128
what if your example contains CDATA sections as well?</para>
130
<para>The solution is to split the CDATA section into two CDATA sections
131
at the point where the CDATA section in the example code ends:</para>
133
<programlisting><![CDATA[
134
<programlisting><![CDATA[
136
<![CDATA[ ... ]]>]]><![CDATA[
138
]]>]]><![CDATA[</programlisting>
141
<para>must be written as</para>
143
<programlisting><![CDATA[
144
<programlisting><![CDATA[
147
<![CDATA[ ... ]]>]]>]]&gt;<![CDATA[<![CDATA[
149
]]>]]><![CDATA[</programlisting>
152
<para>This might look confusing at first, but the simple rule is that every
153
occurrence of "<literal>]]></literal>" has just to be extended with
154
"<literal>]]&gt;<
added
removed
doc/book/tutor-tutor.xml
