.. _documentation:

.. index:: Documentation; Help; Sphinx; reStructuredText

XaoS Documentation
==================

XaoS documentation is generated from reStructuredText__ using the Sphinx__
document processor.  This toolchain allows the documentation to be written
using natural, unobtrusive markup and automatically converted to a number of 
formats including HTML, PDF, Microsoft HTML Help, and Apple Help.  

__ http://docutils.sourceforge.net/rst.html
__ http://sphinx.pocoo.org/

When viewing the HTML version of the documentaiton, you can click the "Show
Source" link in the left sidebar to view the original reST source.  The full
source of the documentation is also available in the `subversion repository`__.

__ http://xaos.svn.sf.net/viewvc/xaos/trunk/help/rest/

If you want to contribute to the documentation, we encourage you to familarize
yourself with the `reStructuredText Primer`__.  Although reStructuredText looks
very much like plain text, it follows certain conventions to enhance formatting.

__ http://docutils.sourceforge.net/docs/user/rst/quickstart.html

If you are only making a small change, feel free to submit it as plain text, 
and the maintainers will be happy to convert it to reST for you.

All changes to the documentation should be submitted via the  `issue tracker`__.

__ http://code.google.com/p/gnuxaos/issues/list


.. highlight:: rest

Context-Sensitive Help
----------------------

XaoS provides context-sensitive help from many areas of the user interface.
If you are writing documentation about some command in the user interface,
you must provide a target in order to make context sensitive help work. 
Place an internal hyperlink target in front of the section describing the 
command using the name of the command in the XaoS function registry, like so::

	.. _command-name:

	About My Hypothetical Command
	=============================

	This command allows you to...
	

Tutorials
---------

XaoS's documentation introduces an interpreted text role to reference 
tutorials.  To reference a tutorial from the documentation, write 
``:tutor:`title <filename.xaf>```.  This will refer to the tutorial 
*filename.xaf* using the text *title*. Depending on the format of the
output, this may generate a link that will launch the referenced tutorial
in XaoS, or it may just format the title in a different font.
