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: [email protected] -- Shaun _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
