Import XaoS r489 (trunk after version 3.5)

1 files changed, 63 insertions, 0 deletions

diff --git a/help/rest/writehelp.txt b/help/rest/writehelp.txt
new file mode 100644
index 0000000..9ea7ac6
--- /dev/null
+++ b/help/rest/writehelp.txt
@@ -0,0 +1,63 @@
+.. _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.