Jump to content
  • entries
    940
  • comments
    5,894
  • views
    864,016

XML for Documentation Data


Josh

1,660 views

 Share

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>

 Share

3 Comments


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
Link to comment
Guest
Add a comment...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...