Images and Examples<screenshot>Wrapper around screenshots. Use this when you are including a screenshot in your document.
-
<screeninfo> Screeninfo is a description of the screenshot. It's common (but not required) to reuse this text in the textobject element, as it saves translation time.
<mediaobject>and<inlinemediaobject>Use
inlinemediaobjectto insert an inline image (that is, one that is inside a paragraph of text, or is the only item in a table entry. Usemediaobjectfor all other images. If the image is a screenshot, themediaobjectshould be wrapped with ascreenshotelement. mediaobjects contain the following items:<imageobject>Imageobject contains information about one specific image. DocBook allows you to add more than one imageobject, in order to provide alternatives if the user is unable to see the preferred image. We don't currently use this functionality in KDE Documentation, but may do at some time in the future.
<imagedata fileref="" format=""/>This element holds the actual image reference. The fileref indicates the location of the image. You should always keep images in the same directory as the document itself, so you need only put the filename into the fileref attribute. The format indicates the type of image you are including. For KDE this should be
PNG. Do not use gif format images for KDE documents.This is one of few “empty” elements in use in KDE Documentation. This means there is no </imagedata>, but you should always close the element as shown above, with a final “/”.
Keep the images in the same directory as your
index.docbook, don't create a separate directory to store them in.<textobject>Encloses the text part of a screenshot, which for KDE Documentation means it contains a
<phrase>element.<phrase>A short descriptive phrase about the image contents, this element is contained in the
<textobject>element.<caption>If you want the image to have a caption when displayed, you can add this. It's not required for KDE documents, but recommended, especially if there are several images near each other and there could be confusion as to which you are referring in the text.
<informalexample>Use this element to enclose any informal examples you use in your document. There are no attributes. An informal example can contain almost any markup, so feel free to use them liberally. They should generally not be part of a paragraph.
<example>An example is a more formal example, which has a title and an entry in the table of contents. Use sparingly, because having a hundred examples listed in the contents of a 5 page document lessens their usefulness. However, don't hesitate to use when you think it's necessary.
I've used them in this document to make it easy to quickly go to the small “template” examples for complex markup, because you can find them directly from the table of contents. Less difficult examples in this document have
<informalexample>instead. Use your best judgement. As with<informalexample>, they can contain almost any markup.