Documentation Style in Practice

This Section shows in detail an example of what we expect your XML to be.

Images Examples

Here's how to insert images in your doc

Floating Images

Figure 1. A demo float image, with its appropriate caption

The Figure 1 figure is included with the code in Example 1. Please pay attention to the Float="1" attribute. This is strongly encouraged, since it produces much better output in Hard Copy printout.

Example 1. How to include a Float Figure

<figure id="BSG.F.001" float="1">
  <title>A demo float image, with its appropriate caption</title>
  <graphic fileref="gfx/appendix_documentation_project/demoimage1.png"/>

Inline Images

Inline Images like are obtained via Example 2

Example 2. How to include an Inline Figure

  <inlinegraphic fileref="gfx/appendix_documentation_project/demoimage2.png"></inlinegraphic>


Tables as in Table 1 in the Section called Floating Images (see.. crossreferences across pages!) are obtained via Example 3

Example 3. How to include a Table

<table frame="all" id="BSG.T.001"><title>Sample Table</title>
  <tgroup cols="3" align="center" colsep="1" rowsep="1">
        <entry>Width [pixels]</entry>
        <entry>Height [pixels]</entry>
        <entry>Resolution [dpi]</entry>


Yeah! I've seen easier things... (even LaTeX!)


All the above examples of XML code where printed out by encapsulating them as shown in Example 4

Example 4. How to include Code

<example id="BSG.L.004"><title>How to include Code</title>
    ****YOUR CODE HERE****

The <![CDATA[ and ]]> pair disable the XML interpretation of anything in between, it is necessary only if you actually key in XML code (like I'm doing) and is superfluous for other programming languages.

If you want to have inline code like this and the ones above you should use a <literal>text</literal> pair, with or without a CDATA wrapper.

Cross references

If you noticed those id="TheObjectLabel" attributes in Figures, tables and code listings, you have already understood half of how cross-referencing works.

Those id="something" attributes are unique labels identifying those objects. The other half of the task is understand how to use them for actual referencing.

This is done via a plain <xref linkend="TheObjectLabel"/>.

Since labels are to be UNIQUE it is advisable to follow the guidelines provided in the relative appendix the Section called Cross Reference Labelling Guidelines.


Keywords are an essential tool for categorizing and efficient searching. The following list is of course not static. if you feel something is missing please warn the authors.

Cross Reference Labelling Guidelines

Labels are a delicate matter inasmuch they must be unique throughout all the Blender Documentation Project to allow for cross referencing from one chapter to another etc.

It is thus highly advisable to stick to a given standard:

For Core documentation


For Tutorials



PID and CID are provided by the DocBoard.

TID and AID are to be agreed between the author and the DocBoard in a preliminary phase.

The userdefined is completely up to the author, who is responsible for keeping the whole label unique.