Lame newbie DocBook questions (long-ish)



I've never used DocBook before, and have a couple of questions (to which
the answer is probably "RTFM") that have arisen as I've been trying to
convert the GNOME Accessibility Guide to DocBook format from HTML.

First... browsing through the GDP styleguide, it says that the <graphic>
tag should be used for including screenshots.  But I couldn't find any
way to provide an alternate textual description of the screenshot this
way, i.e. something that will be converted to an ALT tag by db2html.  Is
there one?  This is vital for our documentation to be accessible.

Reading the DocBook reference, the only way I could find to do this was
using <mediaobject>, i.e:

<mediaobject>
  <imageobject>
   <imagedata fileref="images/depend1" format="PNG">
  </imageobject>
  <textobject>
    <phrase>ALT text goes here</phrase>
  </textobject>
</mediaobject>

which works perfectly (when converted to HTML at least), but I don't
want to do that if it goes against our recommendations or causes
problems for other formats.  (I also note that <graphic> is disappearing
from DocBook before long anyway...)

Second-- is there a way to insert images into tables without generating
piles of warnings?  Right now I'm doing it like this, to insert an image
in a table with an explanatory paragraph below it in the same cell:

.
.
<entry valign=middle>
  <mediaobject>
    <imageobject>
       <imagedata fileref="images/label_right" format="PNG">
     </imageobject>
     <textobject>
       <phrase>Small toolbar icon with label to its right</phrase>
     </textobject>
   </mediaobject>
   Small toolbar icon with label to its right
</entry>
.
.

Again, this renders into HTML and RTF perfectly (haven't tried any other
formats), but gives me a 'document type does not allow element
"MEDIAOBJECT" here' warning.

And finally, how to insert a list into a table cell?  I'm doing this:

.
.
<entry>State 1
  <itemizedlist>
    <listitem><para><keycap>Tab</keycap> moves to State
2</para></listitem>
    <listitem><para><keycap>Shift+Tab</keycap> moves focus to last
control before radio button group</para></listitem>
    <listitem><para><keycap>Down Arrow</keycap> moves to State
3</para></listitem>
    <listitem><para><keycap>Up Arrow</keycap> beeps and doesn't move
focus</para></listitem>
  </itemizedlist>
</entry>
.
.

And quelle surprise, it renders perfectly but chucks a "document type
does not allow element ITEMIZEDLIST" warning at me.

Any suggestions appreciated...  I suspect I'm probably just trying to be
too clever  :o)  See
http://developer.gnome.org/projects/gap/guide/gad/gad-ui-guidelines.html
for the effects I'm trying to achieve with all this stuff...

Cheeri,
Calum.

---
CALUM BENSON, Usability Engineer       Sun Microsystems Ireland
mailto:calum benson ireland sun com    Desktop Engineering Group
http://www.sun.ie                      +353 1 819 9771

Any opinions are personal and not necessarily those of Sun Microsystems




[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]