1 files changed, 64 insertions, 18 deletions
diff --git a/doc/world.html b/doc/world.html
index 70c8fbe..ae8ba8a 100644
--- a/doc/world.html
+++ b/doc/world.html
@@ -32,26 +32,21 @@
 	File structure
 </h2>
 <p>
-	A world description files uses the windows ini-file syntax. Every section starts
-	with a section name enclosed in square brackets. For example, a section called
-	<i>planet</i> would look like:
-<pre>
-[planet]
-</pre>
-<p>
-	Every section contains a list of <i>value=key</i> pairs to describe the properties
-	for the current section. A planet would probably have a radius and a texture and the
-	planet section could look like:
+	A world description files uses the windows ini-file syntax. These files contain one or more sections.
+	Every section starts with a section name enclosed in square brackets and contains a list of 
+	<i>value=key</i> pairs to describe the properties for the current section. 
+	Lines starting with a semicolon are considered comments and are ignored.
+<p>	
+	For example, a section <i>planet</i> describing an iceworld:
 <pre>
+; The iceworld, a very dark and cold place
 [planet]
+label=iceworld
+name=The World of Ice
 radius=32
 texture=planets/iceworld
 </pre>
-<p>
-	Lines starting with a semicolon are considered comments and are ignored:
-<pre>
-; The iceworld, a very dark and cold place
-</pre>
+
 <h2>
 	world.ini
 </h2>
@@ -163,20 +158,71 @@ texture=planets/iceworld
 		<td>roll angle, default is 0<td>
 	</tr>
 </table>
+<p>
+	An example of an entity with a basic shape:
+
+<pre>
+; The Galactic origin
+[entity]
+label=origin
+name=Galactic origin
+shape=axis
+radius=1
+location=0 0 0
+; yellow
+color=1 1 0
+</pre>
+
+<p>
+	An example of an entity with a model:
+<pre>
+; Alexandria outpost
+[entity]
+label=alexandria
+name=Alexandria outpost
+model=stations/alexandria
+location=-116 -68 16
+direction=315
+; light brown
+color=222 192 145
+</pre>
+
 <h3>
 	[planet]
 </h3>
 <p>
-	A planet.
+	A planet is spherical entity with a texture. and a default radius of 32. The planet globe will
+	be rendered with lighting enabled.
+<pre>
+; The iceworld, a very dark and cold place
+[planet]
+label=iceworld
+name=The World of Ice
+texture=planets/iceworld
+; a grey-blue colour
+color =0.5 0.5 0.8
+</pre>
+
 <h3>
 	[star]
 </h3>
 <p>
-	A star.
+	A star is a spherical entity without texture and a default radius of 48. The star globe 
+	will be rendered fullbright and serve as the main source of light for the current system. 
+	At the moment only one system light source is supported. If you define multiple stars, 
+	the last one will serve as light source.
+<pre>
+[star]
+label=whitedwarf
+name=White Dwarf
+; a slightly yellow colour
+color=1.0 1.0 0.9
+</pre>
+
 <h2>
 	ships.ini
 </h2>
 <p>
-	Ships that can be purchased go here.
+	Definition of the shopping list.
 </body>
 </html>