Re: figure tagging (was: Re: GNOME Handbook of Writing Software Documentation rough draft)

[Eric Baudais <baudais kkpsi org>]

Eugene-

The caption is used for a description of the image.  The title should be a 
short description, but the caption can be a much longer description including 
some interesting aspects of the image or naming specific preferences which 
were used in order to capture the image.

I'd also like to quote the TDG on the caption tag:
	A Caption is an extended description of a MediaObject. Unlike a TextObject,
	which is an alternative to the other elements in the MediaObject, the 
	Caption augments the object. 

Eric Baudais

On Tue, Jun 04, 2002 at 02:42:07PM +0100, Eugene O'Connor wrote:
> Hi Eric,
> 
> In the Handbook you suggest the following tagging for figures:
> 
> <figure id="shot1">
>  <title>Screenshot</title>
>  <screenshot>
>   <mediaobject>
>    <imageobject>
>     <imagedata fileref="figures/example_screenshot" format="PNG"/>
>    </imageobject>
>    <textobject>
>      <phrase>Shows the application screenshot with several buttons.</phrase>
>    </textobject>
>    <caption>
>     <para>Screenshot of a program</para>
>    </caption>
>   </mediaobject>
>  </screenshot>
> </figure>
> 
> I'm not sure I understand the purpose of the caption tag in this context. Does it not duplicate the title tag? Is the caption tag optional?
> 
> Eugene
> 
> Eric Baudais wrote:
> > 
> > Guys-
> > 
> > The first draft of the newly revised for GNOME 2 edition of the GDP Handbook
> > is completed.  It is in CVS at gnome-docu/gdp/gdp-handbook.xml.  Any comments,
> > suggestions, and critiques are welcome.
> > 
> > There are two sections which I need a developer who knows the help API to
> > write.  One involves the C code for adding help to applications and the
> > other involves the C code for adding help to applets.  Anyone who has had
> > experience in implementing the code is welcome to write those two sections.
> > Contact me if you are interested so we aren't duplicating work.
> > 
> > There is no mention of Scrollkeeper and OMF files.  This was an omission by
> > me and will be added for the second draft when I review the structure of the
> > handbook.  If anyone has any other sections which aren't in the Handbook but
> > need to be just email the list.
> > 
> > Eric Baudais
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list