• entries
  • comments
  • views

XML for Documentation Data

Sign in to follow this  


I've been getting good results storing documentation data in XML files. This allows me to make changes to the way documenation is displayed, without updating hundreds or thousands of pages. I can also write documentation without as much HTML markup. For example, bullets can automatically be inserted in line breaks for the syntax info. Javascript-based search engines usually require all page contents to be store in an array, so this gives us an easy way to collect that data.


Since XML is a known standard, this makes it a bit easier to outsource the documentation content.


Here is a sample file I am working with.

<?xml version="1.0"?>



<description>Sets the position of an entity in 3-dimensional space, using local or global coordinates.</description>


void Entity::SetPosition(const float x, const float y, const float z, const bool global = false)

void Entity::SetPosition(const Vec3& position, const bool global = false)



nil Entity:SetPosition(number x number y, number z, bool global = false)

nil Entity:SetPosition(Vec3 position, bool global = false)



x: X component of the specified position.

y: Y component of the specified position.

z: Z component of the specified position.

position: the position to set.

global: indicates whether the position should be set in global or local space.



An entity can be positioned in local or global coordinates. Local coordinates are relative to the entity parent's space.


If the entity does not have a parent, local and global coordinates are the same.


<img src='img/552px-Space.png' />


Leadwerks uses a left-handed coordinate system. This means that if you hold your left hand as shown below, your middle finger, index finger, and thumb will point in the directions of the X, Y, and Z axes, respectively.

<img src='img/image2.jpg' />



--Create a window

window = Window:Create()

context = Context:Create(window)

world = World:Create()

local camera = Camera:Create()



local light = DirectionalLight:Create()


--Create a model

model = Model:Box()

while true do

if window:Closed() or window:KeyHit(Key.Escape) then return false end









#include "Leadwerks.h"

using namespace Leadwerks;

int main(int argc, const char *argv[])


Leadwerks::Window* window = Window::Create();

Context* context = Context::Create(window);

World* world = World::Create();

Camera* camera = Camera::Create();

camera->SetRotation(35, 0, 0);

camera->Move(0, 0, -4);

Light* light = DirectionalLight::Create();

light->SetRotation(35, 35, 0);

//Create a model

Model* model = Model::Box();

while (true)


if (window->Closed() || window->KeyDown(Key::Escape)) return false;

model->SetPosition(Math::Sin(Time::GetCurrent() / 10.0), 0, 0);





context->DrawText(model->GetPosition().ToString(), 2, 2);



return 0;





Even the table of contents can be store in XML, which provides a listing of all pages and a way to automatically create the search index and a list of all topics:

<?xml version="1.0"?>








<title>1. Editor</title>



<topic><title>1.1 Editor Interface</title><openstate>true</openstate></topic>

<topic><title>1.2 Scene Panel</title></topic>

<topic><title>1.3 Textures</title></topic>

<topic><title>1.4 Materials</title></topic>

<topic><title>1.5 Models</title></topic>

<topic><title>1.6 Terrain</title></topic>




<title>2. Games</title>


<topic><title>2.1 Marble Platformer</title></topic>




<title>3. Lua Programming</title>


<topic><title>3.1 Introduction to Lua</title></topic>




<title>4. C++ Programming</title>


<topic><title>4.1 Introduction to C++</title></topic>






<title>Script Reference</title>







<title>API Reference</title>














Sign in to follow this  


Recommended Comments

I am using a lot of PHP right now, which does not run on a client web browser, but I guess this format could be turned into anything including local HTML documentation or a PDF.

  • Upvote 1

Share this comment

Link to comment

There's a topic in the programming forum that has a link to a table of contents XML file.

Share this comment

Link to comment

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Create Your Account

Sign in

Already have an account? Sign in here.

Sign In Now