PrevKDE DocBook ReferenceNext

Images, Videos, 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 is common (but not required) to reuse this text in the textobject element, as it saves translation time.

<mediaobject> and <inlinemediaobject>

Use inlinemediaobject to insert an inline image (that is, one that is inside a paragraph of text, or is the only item in a table entry. Use mediaobject for all other images and videos. If the image is a screenshot, the mediaobject should be wrapped with a screenshot element. 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 do not 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 the 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, do not create a separate directory to store them in.

<videoobject>

Videoobject contains information about one specific video.

<videodata contentdepth="" contentwidth="" fileref=""/>

This element holds the actual video reference. The fileref indicates the location of the video. You should always use hostings with disabled autoplay, (e.g. YouTube) as DocBook 4.5 does not allow disabling autoplay inline.

This is one of few “empty” elements in use in KDE Documentation. This means there is no </videodata>, but you should always close the element as shown above, with a final “/”.

Keep the video frame ratio close to the original using the contentdepth and contentwidth parameters.

<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 is 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, do not hesitate to use when you think it is 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.

Example A.8. A screenshot example


<screenshot>
<screeninfo>An example image</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="example.png" format="PNG" />
</imageobject>
<textobject>
<phrase>An example image</phrase>
</textobject>
</mediaobject>
</screenshot>

Example A.9. A video example


<mediaobject>
<videoobject>
<videodata contentdepth="315" contentwidth="560" fileref="https://www.youtube.com/embed/abcdefgh" />
</videoobject>
<caption>
<para>An example video</para>
</caption>
</mediaobject>