Update docs

3 files changed, 125 insertions, 0 deletions

diff --git a/README b/README
index e98bcd9b..afea1cb5 100644
--- a/README
+++ b/README
@@ -98,6 +98,16 @@ $ ./configure --with-libtiff=/some/strange/location
 $ ./configure --with-gsl=/some/strange/location
 $ ./configure --disable-gtk
 
+At a minimum, you will need the HDF5 library (version 1.8.0 or later) and the
+GNU Scientific Library (GSL).  For a full installation, you will also need
+libTIFF, libPNG, Cairo and GTK.
+
+You must use an installation of the HDF5 library which is thread safe.  That
+means it must have been configured with the "--enable-threadsafe" option.  Most
+binary distributions appear NOT to be like this.  If you don't have a thread
+safe HDF5 library, just be sure not to use the "-j" option for any of the
+CrystFEL programs.
+
 If you're compiling on Mac OS X, where GTK, libPNG and libTIFF seem to be much
 harder to come by, disable lots of things:
 
diff --git a/doc/reference/CrystFEL-docs.sgml b/doc/reference/CrystFEL-docs.sgml
index fa973b86..ac32b14b 100644
--- a/doc/reference/CrystFEL-docs.sgml
+++ b/doc/reference/CrystFEL-docs.sgml
@@ -47,4 +47,10 @@
     <title>API Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
   </index>
+
+  <chapter>
+    <title>Information for developers</title>
+        <xi:include href="xml/coding-standards.xml"><xi:fallback /></xi:include>
+  </chapter>
+
 </book>
diff --git a/doc/reference/xml/coding-standards.xml b/doc/reference/xml/coding-standards.xml
new file mode 100644
index 00000000..e3d549f4
--- /dev/null
+++ b/doc/reference/xml/coding-standards.xml
@@ -0,0 +1,109 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<refentry id="CrystFEL-coding-standards">
+<refmeta>
+<refentrytitle role="top_of_page" id="CrystFEL-coding-standards.top_of_page">CrystFEL coding standards</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>
+  Coding  standards
+</refmiscinfo>
+</refmeta>
+<refnamediv></refnamediv>
+
+
+<refsect1 id="CrystFEL-coding-standards.description" role="desc">
+<title role="desc.title">Summary</title>
+<para>
+This page documents the coding conventions used within the CrystFEL source code.  Read these to help when reading the code or before making modifications destined to be sent upstream.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.license">
+<title>Licensing and copyright</title>
+<para>
+CrystFEL is distributed under the terms of the GNU General Public License version 3 or higher.  Contributions are very welcome provided they also use this license.
+</para>
+<para>
+Whenever you edit a source file, don't forget to update the copyright dates at the top.  Add your name and email address if they're not there already.  Be sure to add your name to the 'AUTHORS' file in the top level folder, as well.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.formatting">
+<title>Formatting</title>
+<para>
+<emphasis>Indentation</emphasis> is done with <emphasis>tabs</emphasis> and
+<emphasis>alignment</emphasis> is done with spaces.  This way, the code looks
+neat whatever width you configure your editor to display tabs as.
+</para>
+<para>
+However, code must be <emphasis>strictly</emphasis> wrapped at 80 columns, or
+what would be 80 columns if the tabs were displayed as 8 spaces.
+If you think you need more width, you're at too many levels of indentation and
+need to break things down a bit.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.brackets">
+<title>Brackets and so on</title>
+<para>
+Brackets and so on should go like this:
+</para>
+<para>
+<programlisting>
+/* Multiple line comments have stars
+ * down one side */
+void somefunction(int someparam)
+{
+	/* Single line comments use this style (not //) */
+	if ( a &lt; b ) {
+		/* 'if' statements usually have the opening brace on the same
+		 * line as the condition. */
+	} else {
+		/* 'else's are 'cuddled' */
+	}
+
+	if ( some &amp;&amp; very &amp;&amp; long &amp;&amp; condition &amp;&amp; that &amp;&amp; spans
+	     &amp;&amp; two &amp;&amp; lines )
+	{
+		/* Opening brace is on a line by itself in the case of a very
+		 * long condition */
+	}
+}
+
+/* Comments use proper capitalisation to make things look neat */
+</programlisting>
+</para>
+<para>
+'struct' blocks can have the braces like functions or 'if' statements.  Usually
+the former looks nicer if the struct is large.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.cleverness">
+<title>Cleverness</title>
+<para>
+Yes, we all know you can insert a new node into an RB-tree while simultaneously
+calculating Pi to 150 decimal places in one line of code.  You don't need to
+prove it here.  As a general rule, if you think you're about to do something clever, <emphasis>don't do it at all</emphasis>.
+</para>
+</refsect1>
+
+
+<refsect1 id="CrystFEL-coding-standards.evilness">
+<title>Evil dictator</title>
+<para>
+Despite your following all of the above, I will probably still touch up your
+code in some places while (or shortly after) integrating it into mainline
+CrystFEL.  Please try not to take it personally.
+</para>
+</refsect1>
+
+</refentry>