Re: Help and guidance needed creating gnome help

[Shaun McCance <shaunm gnome org>]

On Mon, 2007-01-15 at 21:35 -0600, Vic Jones wrote:
> Help!!
> 
> Firstly I apologize for probably breaking various list protocols by
> sending this email – please overlook that.

Please don't CC the others individually.  This mailing list
is perfectly sufficient.

> 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. )

Unfortunately, much of our documentation about documentation
is out of date.  And DocBook itself isn't exactly easy.  So
it's understandable that you're having some difficulty.

Also, don't use the old GDP customized DTD for PNG.  The PNG
problem is long long gone.  Use standard DocBook 4.

> 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.

There is no such thing as <secN> (without the 't') tags in DocBook.
I'm not sure where you got the idea that there are.  The fact that
you see them rendered in Yelp without section numbers is just an
artifact of how Yelp processes DocBook.  For efficiency's sake, it
does not validate documents, and simply passes through elements it
doesn't understand.

There are effectively two different ways to do sections in DocBook:
the sectN elements and the section element.  The sectN elements are
designed to specify the level of the section explicitly.  That is,
a sect1 element can contain sect2 elemeents, a sect2 element can
contain sect3 elements, and so on.  In your example file, you've
placed a sect1 element inside a sect1 element.  This is not valid
DocBook.  Think of sect1 as a section, sect2 as a subsection, and
sect3 as a subsubsection.

The section element, on the other hand, does away with the need
for explicitly identifying the level of the section.  You can
nest section elements arbitrarily deep.  So a subsection is just
a section element inside a section element, etc.  A subsubsection
is a section element inside a section element inside a section
element.

The existence of the sectN elements is a historical artifact.
Many older document processing tools couldn't ascertain the
context of an element in a document, so the section level had
to be explicitly codified.  Newer processing technologies don't
have this problem, so the section element was introduced to
simplify things.  But since DocBook's design generally errs
on the side of backwards compatibility, we're stuck with both
types of elements.

In short, forget the sectN elements exist, and simply use
the section element.  (You might one day stumble across the
simplesect element.  Ignore it.)

> 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>

Effectively, yes.  More correctly, DocBook does not allow you
to simply insert line breaks.  Instead, you wrap your paragraphs
in para elements.  Processing tools are expected to manage the
amount of spacing between paragraphs.

The para element, incidentally, functions exactly like HTML's
p element is supposed to.  But because HTML is so lax, people
just started putting blank <p> tags between paragraphs to
create some vertical space.  It was never supposed to be like
that.  XHTML is much stricter about this.

> 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>

There is no standard way to control whether sections are
numbered.  Section numbering is the choice of the tools
that process your DocBook.  In Yelp, we don't provide any
means of toggling section numbers, and I don't have any
plans to introduce that.

> To Add a shaded box and indent the text: 
> 
> <para>
> 
> <screen>
> 
> -- Text
> 
> </screen>
> 
> </para>

The screen element is not defined to be a shaded box.
The screen element is a pre-formatted element (i.e. all
whitespace is significant) that contains the input and
output of what you would type in an interactive command
line session.

The fact that you see a gray box is just because I happen
to have liked that design when I wrote the code.  DocBook
does not strictly specify how everything should look.  I
could easily change screen elements to have a dashed blue
border and drop shadow in the next release.  I have, in
fact, experimented with adding something like the terminal
icon as a watermark on screen elements.  And I just might
implement it some day if I can get a good designer to make
me a decent image.

> To Add text without formatting in a shaded box (c.f. 'code' in HTML):
> 
> <para>
> 
> <programlisting>
> 
> Text
> 
> goes here
> 
> </programlisting>
> 
> </para>

Again, programlisting is not defined as "pre-formatted
without a gray box".  It's defined to be snippet of code
in some programming language or other syntax.  I could
change the formatting of programlisting any day.  And
again, I've experimented with watermarks.

> 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>

There's no need to place figure inside a para, although
it's valid DocBook either way.  I tend to prefer not to
nest block content, because it creates problems with
translation tools.

As for screeninfo, don't bother.  It's just a place to
list some metadata about the screenshot.  Yelp doesn't
even do anything with it.

Don't use the graphic element.  It's deprecated.  This is
another case of DocBook providing multiple ways of doing
things because of backwards compatibility.  The problem
with the graphic element is that it doesn't provide an
effective means of providing fallback content.  Think of
an embedded video (not yet supported by Yelp) that has
a fallback image for printed content.  More importantly,
all images should have fallback text content for blind
and low-vision users.

Here's the correct mediaobject construction to replace
your graphic element:

<mediaobject>
<imageobject>
<imagedata fileref="images/Screenshot.png" format="PNG"/>
</imageobject>
<textobject>A description of the screenshot</textobject>
</mediaobject>

I know it's obtuse, but that's DocBook.

> 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.

The "no suffix required" thing shouldn't be used.  I added
support for it to Yelp for compatibility with some existing
documents.  Use the actual file name.

You shouldn't have to specify the leading "./" on the fileref
attribute.  Any DocBook processor (including Yelp) understands
relative paths as being relative to ".".

And the value of the format attribute should be "PNG", not
"png".  There is a difference.  And that difference is why
the automatic suffix thing didn't work for you (which, again,
you shouldn't use anyway).

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

If you have more problems, please feel free to ask them on
this list: gnome-doc-list gnome org

--
Shaun