XML for Documentation Data
Entry posted by Josh ·
1,899 views
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"?>
<page>
<title>SetPosition</title>
<description>Sets the position of an entity in 3-dimensional space, using local or global coordinates.</description>
<cppsyntax>
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)
</cppsyntax>
<luasyntax>
nil Entity:SetPosition(number x number y, number z, bool global = false)
nil Entity:SetPosition(Vec3 position, bool global = false)
</luasyntax>
<parameters>
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.
</parameters>
<remarks>
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' />
</remarks>
<luaexample>
--Create a window
window = Window:Create()
context = Context:Create(window)
world = World:Create()
local camera = Camera:Create()
camera:SetRotation(35,0,0)
camera:Move(0,0,-6)
local light = DirectionalLight:Create()
light:SetRotation(35,35,0)
--Create a model
model = Model:Box()
while true do
if window:Closed() or window:KeyHit(Key.Escape) then return false end
model:SetPosition(Math:Sin(Time:GetCurrent()/10.0),0,0)
Time:Update()
world:Update()
world:Render()
context:Sync()
end
</luaexample>
<cppexample>
#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);
Leadwerks::Time::Update();
world->Update();
world->Render();
context->SetBlendMode(Blend::Alpha);
context->DrawText(model->GetPosition().ToString(), 2, 2);
context->Sync();
}
return 0;
}
</cppexample>
</page>
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"?>
<contents>
<topics>
<topic>
<title>Tutorials</title>
<openstate>true</openstate>
<topics>
<topic>
<title>1. Editor</title>
<openstate>true</openstate>
<topics>
<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>
</topics>
</topic>
<topic>
<title>2. Games</title>
<topics>
<topic><title>2.1 Marble Platformer</title></topic>
</topics>
</topic>
<topic>
<title>3. Lua Programming</title>
<topics>
<topic><title>3.1 Introduction to Lua</title></topic>
</topics>
</topic>
<topic>
<title>4. C++ Programming</title>
<topics>
<topic><title>4.1 Introduction to C++</title></topic>
</topics>
</topic>
</topics>
</topic>
<topic>
<title>Script Reference</title>
<topics>
<topic><title>AI</title></topic>
<topic><title>Analytics</title></topic>
</topics>
</topic>
<topic>
<title>API Reference</title>
<topics>
<topic>
<title>Object</title>
<openstate>true</openstate>
<topics>
<topic><title>Asset</title></topic>
<topic><title>Analytics</title></topic>
</topics>
</topic>
</topics>
</topic>
</topics>
</contents>
3 Comments
Recommended Comments