Documentation Style in Practice

Images Examples

Here's how to insert images in your doc

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

<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

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

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

• Lighting

  • 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 referencing from one chapter to another etc.

It is thus highly advisable 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 Publication 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 for the author to define;

• TID is a three letter Tutorial Identifier;

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.