Documentation changed to source INSTALL file for instructions

INSTALL

@@ -1,17 +1,11 @@
 
-Stage v.3 build using CMake instructions
-Author: Richard Vaughan, 2008.4.11 $Id$
-
-* Purpose *
-
-As an alternative to the GNU autotools build chain, Stage can also be
-buily with CMake. This has two main advantages: (i) it is much faster;
-(ii) CMake can create native build files for Windows and Mac OS X,
-which will help Stage become more portable.
+Build system
+------------
+Stage is now built using the CMake build system (version 2.4.7 or newer).  This has two main advantages: (i) it is much faster; (ii) CMake can create native build files for Windows and Mac OS X, which will help Stage become more portable.
 
 
-* Configuring the build *
-
+Configuring the build
+---------------------
 Unpack the distribution or check it out from SVN. Change directory to
 the top level of the Stage source tree.
 
@@ -21,99 +15,99 @@ usually installed in /opt/local, which is not in CMake's default
 system search path. Add your non-standard software directories to
 CMake's search paths by setting environment variables, e.g. in bash:
 
-export CMAKE_INCLUDE_PATH=/opt/local/include
-export CMAKE_LIBRARY_PATH=/opt/local/lib
+	$ export CMAKE_INCLUDE_PATH=/opt/local/include
+	$ export CMAKE_LIBRARY_PATH=/opt/local/lib
 
 If you want to use Player with Stage, install Player first, then make
 sure that pkg-config can find it. Test it like so:
 
-pkg-config --modversion playercore
+	$ pkg-config --modversion playercore
 
 This should output the version number of the Player installation
 (probably 2.2.0 or later). If not, add the location of Player's
 pkg-config file to your PKG_CONFIG_PATH, eg. in bash:
 
-export PKG_CONFIG_PATH+=<Player installation prefix>/lib/pkgconfig
+	$ export PKG_CONFIG_PATH+=<Player installation prefix>/lib/pkgconfig
 
 Now that the supporting software is set up, you can decide where you
 want to install Stage. The default installation directory varies by
 system, but is often /usr/local on Unix variants. This is easy and is
 often a good choice, but has the disadvantage that installation needs
 root/sudo priviliges. To install in the default location, do:
 
-  $ cmake .
+	$ cmake .
 
 If you wish to install Stage elsewhere, define the CMAKE_INSTALL_PATH
 path variable when invoking cmake. To do this, use this command,
 substituting <prefix> with your chosen installation
 directory.
 
-  $ cmake -DCMAKE_INSTALL_PREFIX=<prefix> .
+	$ cmake -DCMAKE_INSTALL_PREFIX=<prefix> .
 
 For example to install in $HOME/playerstage, do:
 
-  $ cmake -DCMAKE_INSTALL_PREFIX=$HOME/playerstage .
+	$ cmake -DCMAKE_INSTALL_PREFIX=$HOME/playerstage .
 
 Cmake will generate makefiles specifically for your machine. When this
 is done, you can inspect and edit the build settings using ccmake, or
 by editing the file CMakeCache.txt. 
 
-* Building *
-
+Building
+--------
 In the top level directory of the source tree, do:
 
- $ make
-
-* Installing *
+	$ make
 
+Installing
+----------
 In the top level directory of the source tree, do:
 
- $ make install
+	$ make install
 
 (You may need to run this command as root or sudo, depending on the
 install location).
 
 Stage will install its components in various directories, for example:
 
-<prefix>/bin    (executables, including the 'stage' program)
-<prefix>/lib    (libraries, including libstage)
+<prefix>/bin    (executables, including the 'stage' program)  
+<prefix>/lib    (libraries, including libstage)  
 <prefix>/share  (contains data resources, such as images)
 
-* Setup *
-
+Setup
+-----
 You must ensure that the dynamic library libstage.so (or
 libstage.dylib, or libstage.dll, depending on your platform) can be
 found by your system's library loader. The method for doing this
 varies by platform.
 
 On Linux, using BASH:
 
-  $ export LD_LIBRARY_PATH=<prefix>/lib
+	$ export LD_LIBRARY_PATH=<prefix>/lib
 
 On OS X, using BASH:
 
-  $ export DYLD_LIBRARY_PATH=<prefix>/lib
+	$ export DYLD_LIBRARY_PATH=<prefix>/lib
 
 If you plan to use Stage plugins, you also need to set the STAGEPATH
 environment variable to include the directory that contains your
 plugins. E.g. in BASH, do:
 
-  $ export STAGEPATH=/usr/local/lib
+	$ export STAGEPATH=/usr/local/lib
 
 If you installed Stage somewhere other than /usr/local, substitute
 your install prefix:
 
-  $ export STAGEPATH=<stage install prefix>/lib
+	$ export STAGEPATH=<stage install prefix>/lib
 
 If you are using Stage with Player, you probably don't need to set the
 STAGEPATH. However, you may need to set the PLAYERPATH to include
 Stage's installed lib directory instead.
 
-* Testing *
-
+Testing
+-------
 To test your Stage installation, do:
 
-<prefix>/bin/stage worlds/simple.world
+	$ <prefix>/bin/stage worlds/simple.world
 
 You should see a window appear, showing some robots. You can change
 the camera point of view by holding down the 'ctrl' key and moving the
@@ -123,14 +117,14 @@ simulations using libstage.
 If you plan to use Stage plugins, you can test that plugins are
 working:
 
-<prefix>/bin/stage worlds/fasr.world
+	$ <prefix>/bin/stage worlds/fasr.world
 
 You should see a window appear, showing some robots. Try pressing the
 'p' key to pause and un-pause the simulation, to check that the robots
 are working. If this works, you are ready to write Stage plugins.
 
-* Next steps *
-
+Next steps
+----------
 - read the Stage manual, available from the Player Project website
   (also buildable from the docsrc directory in the source tree
   (requires doxygen)).
@@ -141,6 +135,8 @@ are working. If this works, you are ready to write Stage plugins.
 
 Enjoy using Stage -- rtv
 
-"All the world's a stage, and all the women merely players"
+"All the world's a stage, and all the women merely players"  
   Wm. Shakespeare - "As you like it"
 
+Stage v.3 build using CMake instructions  
+Author: Richard Vaughan, 2008.4.11 $Id$

docsrc/installpage.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 
-echo "/** \page installnew"
+echo "/** \page install Installation"
 ./Markdown.pl ../INSTALL
 echo "**/"

docsrc/stage.txt

@@ -3,6 +3,7 @@
  * $Id: stage.txt,v 1.20 2008-02-24 23:24:40 rtv Exp $
 */
 
+
 /**
 \mainpage The Stage Robot Simulator
 
@@ -239,91 +240,6 @@ reply to you. <b>Remember that these mails go to hundreds of people</b>, so
 please be polite and give as much information as you can in your
 email.
 
-
-\page install Installation
-
-<b>Important: If you plan to use Stage with Player, Player must be
-properly installed before you install Stage.</b>
-
-<h2>Quick start</h2>
-
-Install Stage using the CMake build tools: download and extract the tarball, then 
-<tt>cmake .; make install</tt>.
-
-<h2>Standard install procedure</h2>
-
-<p>To install Stage in the default location, follow these steps:
-
-<ol>
-
-<li>If you plan to use Player with Stage, make sure Player is
- installed and working. See the Player documentation for instructions.
-
-<li>Download the latest Stage source tarball (Stage-\<version\>-Source.tgz)
-from <a href="http://sourceforge.net/projects/playerstage">http://sourceforge.net/projects/playerstage</a>
-
-<li>Uncompress and expand the tarball: <br>
-    <tt>$ tar xzvf Stage-\<version\>-Source.tgz</tt>
-
-<li>`cd' into Stage's source directory:<br>
-     <tt>$ cd Stage-\<version\>-Source</tt>
-
-<li>To configure Stage with default settings:<br>
-<tt>$ cmake .</tt><br>
-
-<li>Compile Stage:<br>
-<tt>$ make</tt>
-
-<li>Test to see if Stage works by running the stest program:<br>
-<tt>libstage/stest worlds/simple.world robot1</tt><br>
-If you see a robot running around, your build was successful. If not,
-you need to debug. See the <a href="http://playerstage.sf.net">website
-and user groups for debugging help</a>.
-
-<li>Install Stage. By default, Stage will be installed in
-<tt>/usr/local</tt> so you need to become root for this step. Remember
-to return to your normal user ID afterwards. <br> 
-<tt>$ make install</tt>
-
-</ol>
-
-
-<h2>Player/Stage</h2>
-
-Stage can provide a population of simulated devices for the Player
-robot server. Player client programs can use the virtual Stage devices
-as if they were real Player robots. To do this, Stage provides the
-dynamically-loadable Player plugin driver "libstageplugin". Player
-using libstageplugin is known as "the Player/Stage system", or
-"Player/Stage", and often abbreviated to "P/S".
-
-To use Player/Stage, you run the "player" program with appropriate
-configuration files.  See the documentation [@ref player] for details
-and examples.
-
-<h2>Stage program</h2>
-
-Stage also provides the executable program "stage", which allows you
-to run Stage simulations without Player. There are pros and cons of
-using Player, so be sure to read the documentation [@ref stage] and
-[@ref player] to determine what's best for your project.
-
-<h2>libstage C++ library</h2>
-
-You can also create your own custom robot simulations independently of
-Player by using the libstage C++ library directly in your code. See
-the documentation [@ref libstage] for details.
-
-<h2>Customized installations</h2>
-
-<p> todo
-
-<p> export CMAKE_INSTALL_PREFIX=<prefix>
-
-<p> Prefixes must be absolute, expanded paths, i.e. a complete path starting with a '/' (not stage or $HOME/stage).
-
-<p> todo: finding player
-
 \section References
 
 [1] Brian Gerkey, Richard Vaughan, Kasper Stoy, Andrew Howard, Gaurav

libstage/model.cc

@@ -17,21 +17,19 @@ model
 (
   pose [ 0 0 ]
   size [ 1.0 1.0 ]
-  origin [ 0 0 0]
-  velocity [0 0 0]
+  origin [ 0 0 0 ]
+  velocity [ 0 0 0 ]
 
   # body color
   color "red" 
 
   # determine how the model appears in various sensors
-
   obstacle_return 1
   laser_return 1
   ranger_return 1
   blobfinder_return 1
   fiducial_return 1
   gripper_return 0
-
   fiducial_key 0
 
   # GUI properties
@@ -44,12 +42,10 @@ model
 )
 @endverbatim
 
-TODO PLAN: single array of all polygon vertices - model just keeps an index
-
 @par Details
-- pose [x_pos:float y_pos:float heading:float]
-- specify the pose of the model in its parent's coordinate system
-- size [x_size:float ysize:float]
+- pose [x_pos:float y_pos:float heading:float]\n
+specify the pose of the model in its parent's coordinate system
+- size [x_size:float y_size:float]
 - specify the size of the model
 - origin [x_pos:float y_pos:float heading:float]
 - specify the position of the object's center, relative to its pose
@@ -85,7 +81,7 @@ TODO PLAN: single array of all polygon vertices - model just keeps an index
 - ranger_return [bool]
 - iff 1, this model can be detected by a ranger.
 - gripper_return [bool]
-- iff 1, this model can be gripped by a gripper and can be pushed around by collisions with anything that has moa non-zero obstacle_return.
+- iff 1, this model can be gripped by a gripper and can be pushed around by collisions with anything that has a non-zero obstacle_return.
 
 */