Blender Documentation: Last modified May 16 2003 bv
<<< Previous | About the Blender Documentation Project | Next >>>

# 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"/>
            				</figure>

### Inline Images

Inline Images like are obtained via Example 2

Example 2. How to include an Inline Figure

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

## Tables

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">
            		 <thead>
            		  <row>
            		   <entry>Width [pixels]</entry>
            		   <entry>Height [pixels]</entry>
           			   <entry>Resolution [dpi]</entry>
           			  </row>
          			 </thead>
            		 <tbody>
           			  <row>
             		   <entry>1000</entry>
          			   <entry>768</entry>
          			   <entry>150</entry>
    		          </row>
                              <row>
                               <entry>800</entry>
                               <entry>600</entry>
                               <entry>125</entry>
                              </row>
                              <row>
                               <entry>640</entry>
                               <entry>512</entry>
                               <entry>100</entry>
                              </row>
                             </tbody>
                             </tgroup>
                             </table>

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

## Code

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>
                             <programlisting><![CDATA[
                                 ****YOUR CODE HERE****
                             ]]>
                             </programlisting>
                             </example>

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 listing you have already understood half of how cross-reference 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 adviceable to follow the guidelines provided in the relative appendix the Section called Cross Reference Labelling Guidelines.

## Keywords

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.

- `Animation`

  - `Armatures`

    - `Forward Kinematics`

    - `Inverse Kinematics`

  - `Keyframes Animation`

  - `Path Animation`

  - `Relative Vertex Keys Animation`

  - `Vertex Keys Animation`

- `Interface`

- `Lightning`

  - `Fake Global Illumination`

  - `Radiosity`

- `Modeling`

  - `Bezier Splines`

  - `Meshes`

  - `NURBS`

  - `SubSurfed Meshes`

- `Materials`

- `Realtime`

- `Rendering`

- `Sequence Editor`

- `Texturing`

  - `Built in Procedural`

  - `Plugins`

  - `UV Texturing`

- `World Settings`

## Cross Reference Labelling Guidelines

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

It is thus higly adviceable to stick to a given standard:

For Core documentation

    PID.CID.[F|T|E|D|L].AID.userdefined

For Tutorials

    TID.AID.userdefined

Where

- `PID` is a two letter Pubblication Identifier;

- `CID` is a three letter Chapter identifier;

- `[F|T|E|D|L]` is a letter defining the Type of object labelled, that is:

  - Figure;

  - Table;

  - Equation;

  - Document Data (i.e. a Section, subsection, paragraph etc);

  - Listate;

- `AID` is a three letter author identifier;

- `userdefined` are (up to) ten letters up to the author to define;

- `TID` is a three letter tutorialidentifier;

`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.

<<< Previous | Home | Next >>>
The Blender Documentation Project styleguide | Up | The Documentation Licenses