Help and guidance needed creating gnome help

["Vic Jones" <jones victor gmail com>]

Help!!

Firstly I apologize for probably breaking various list protocols by sending this email – please overlook that.

I am trying to do some very basic documentation for a gnome program and I'm looking for an idiots guide. I've found some tutorials on the web, but they dive into great detail. I've spent several hours looking over them but they are too detailed or may just be out of date.

I've tried Ref[1] http://developer.gnome.org/projects/gdp/resources.html which has some templates that helped somewhat, but I really need something simpler.

Another source I found was
http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/gettingstarted.html but as well as giving too mch detail, also refers to the GDP DocBook DTD for PNG support  (this link is out of date & I can't find see any png support files. )

I need (and I think that most starters to gnome documentation/docbook would also benefit from it) a set of very simple Howto examples – showing the code and how it affects the look of the output document.

I'll give some specific examples of what I have in mind at the end.

One thing that is confusing me is how to create sub-sections. I realize that they can be nested, but there seem to be 3 types of tag and I cant find anything that tells me how the different tags should work.

e.g. there's <sectN> & <section>, which seem to number the sections, and <secN> (without the 't'), which doesn't. When I mix the different section tags, YELP seems to put <secN> tags before <sectN> tags. Is this a bug or deliberate?

You can see from the attached xml file how it has moved section SecT2 L3 right to the end. (I'm viewing it with Yelp 2.14.3 on Ubuntu 6.06.)

Is there anywhere that explains sub-sections simply?, when to use sec1,2,3 etc.

OK, as for what I'd like to see in an 'idiots help' would be something like the following (please excuse the actual code as I'm just winging it):

To get the effect, insert text shown in bold:

To Add a line break: <para>text</para>

To Add a subsection with numbering: (I'm guessing here)

<sect1 id="create"><title>Existing Section tiltle</title>

<section>

<title>Sub section title</title>

<para>Some text.</para>

</section>

</sect1>

To Add a subsection without numbering: (still guessing)

<sect1 id="create"><title>Existing Section tiltle</title>

<sec2>

<title>Un-numbered Sub section title</title>

<para>Some text.</para>

</sec2>

</sect1>

To Add a shaded box and indent the text:

<para>

<screen>

-- Text

</screen>

</para>

To Add text without formatting in a shaded box (c.f. 'code' in HTML):

<para>

<programlisting>

Text

goes here

</programlisting>

</para>

To add an image:

<para>

Some text

<!-- ==== Figure ==== -->

<figure id="mainwindow-fig">

<title>Title for image</title>

<screenshot>

<screeninfo>No idea what this is for</screeninfo>

<graphic fileref="./images/Screenshot.png" format="png" srccredit="ME">

</graphic>

</screenshot>

</figure>

<!-- ==== End of Figure ==== -->

</para>

Note that the directory storing the image should be a relative path i.e "./dirname/filename"

Note, to get this to work I had to include the filetype suffix – I wasted ages as I read somewhere that this wasn't required. Incidently, the template in Ref [1] doesn't display an image – a least not with firefox 1.5.0.9 on Ubuntu.

Well, that's about as far as I've fumbled for now.

Thanks very much in advance,

Vic.

<sect1 id="features">
<title>Features</title>
<para>features can be divided into two main categories. Basically, the <emphasis>Create</emphasis> category is used to create 
a CD/DVD repository with packages previously downloaded with apt-get tools while the <emphasis>Restore</emphasis> options perform operations related 
to restoring packages using the previously created media (as a local repository).</para>

<!-- -->
	<sect1 id="create"><title>Sect1 L2 #1 </title>
	
		<section>
			<title>section L3 Action</title>
			<para>Create a removable repository with all packages downloaded with Synaptic, apt-get or aptitude.</para>
		</section>
	
		<sec2>
		<title>Sec2 L3 Features</title>
		</sec2>	

		<sect2>
		<title>SecT2 L3 -Is this moved(should be after Features</title>
		</sect2>	
		
		<sec2>
		<title>Sec2 L3 Features</title>
		</sec2>	
		
		<sect1 id="createx"><title>Sect1 L3 #2 </title>
		</sect1>
		
		<para>(<link linkend="features">back to top</link>)</para>	
	</sect1>



<!-- -->
<!-- 
 -->
</sect1>