Documentation work

2 files changed, 43 insertions, 2 deletions

diff --git a/README b/README
index 61cc9664..9a27d9c3 100644
--- a/README
+++ b/README
@@ -137,8 +137,7 @@ the journal capitalises them at the proof stage. It's as if they think it
 somehow makes the name look more "computery", or perhaps "trademark-y".
 
 Well, it's not 1970 any more, and programs are no longer input on punched cards.
-That means we can have capitalisation any way we choose.  I hope you can forgive
-me for being fussy about how my work is referred to in publications and talks.
+That means we can have capitalisation any way we choose.
 
 The name for the overall software suite is "CrystFEL", with this being the only
 acceptable capitalisation.  The individual programs should always be referred to
@@ -158,3 +157,5 @@ eat you.
 In addition, CrystFEL is made up of "programs", not "routines" nor "procedures".
 (The "programs" in turn are made up from "routines" and "procedures", but unless
 you are exploring the source code, there's no need for you to know about that).
+
+I hope you can forgive the fussiness.
diff --git a/doc/man/crystfel.7 b/doc/man/crystfel.7
index d0a8cd59..b96fb958 100644
--- a/doc/man/crystfel.7
+++ b/doc/man/crystfel.7
@@ -71,6 +71,46 @@ files.
 .PP
 Please see the individual manual pages for the CrystFEL programs for detailed information.
 
+.SH CITING CRYSTFEL
+If CrystFEL was important for your research, please consider citing the
+following article:
+.IP
+T. A. White, R. A. Kirian, A. V. Martin, A. Aquila, K. Nass, A. Barty and
+H. N. Chapman. "CrystFEL: a software suite for snapshot serial crystallography". J. Appl. Cryst. 45 pXXX-XXX. doi:10.1107/S0021889812002312
+.PP
+Please let us know (see below) about your publication, so we can include it in
+the list of examples on the CrystFEL website.
+
+.SH PROGRAM NAME
+There seems to be a tendency to capitalise all the letters in the names of
+programs in scientific publications.  Sometimes the authors do this, other times
+the journal capitalises them at the proof stage. It's as if they think it
+somehow makes the name look more "computery", or perhaps "trademark-y".
+
+Well, it's not 1970 any more, and programs are no longer input on punched cards.
+That means we can have capitalisation any way we choose.
+
+The name for the overall software suite is "CrystFEL", with this being the only
+acceptable capitalisation.  The individual programs should always be referred to
+with all letters in lower case, exactly the same as the names of the binaries.
+Put the names in quotes or italics if this sounds strange to you.  The only
+exception is if the name of the program comes at the start of a sentence, or in
+a title, or similar position where a word would normally be capitalised.
+
+In most cases, it will be more appropriate to refer to the overall suite than to
+one of its constituent programs.
+
+The following are NOT acceptable forms: "CRYSTFEL", "crystFEL", "Crystfel",
+"INDEXAMAJIG" and "PATTERN_SIM".  If you use any of these (particularly the
+first one and the last two), the Capitalisation Monster will hunt you down and
+eat you.
+
+In addition, CrystFEL is made up of "programs", not "routines" nor "procedures".
+(The "programs" in turn are made up from "routines" and "procedures", but unless
+you are exploring the source code, there's no need for you to know about that).
+
+I hope you can forgive the fussiness.
+
 .SH AUTHOR
 This page was written by Thomas White.