Documentation work

1 files changed, 40 insertions, 0 deletions

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.