[Monotone-commits-diffs] net.venge.monotone.string-sanitization: 0a78ed1be81489b1cfe5245ae21855d47f1ed6ce

[code]

revision:            0a78ed1be81489b1cfe5245ae21855d47f1ed6ce
date:                2011-03-08T09:12:02
author:              Richard Levitte <address@hidden>
branch:              net.venge.monotone.string-sanitization
changelog:
* HACKING: Add a section on how to format messages.

manifest:
format_version "1"

new_manifest [4863a812cfd731a623bd0fc54dde1c5f2b454625]

old_revision [f4059ba00ed84b05a3bafd8ebbc4606b0ea7c9d7]

patch "HACKING"
 from [eec61a4767dee544ad080408e0ebe7757821c66a]
   to [5bd247a6d06d0b45781f765137c45b0f58f8ae5d]
============================================================
--- HACKING	eec61a4767dee544ad080408e0ebe7757821c66a
+++ HACKING	5bd247a6d06d0b45781f765137c45b0f58f8ae5d
@@ -51,6 +51,91 @@ everywhere.
 everywhere.
 
 
+Formatting messages
+-------------------
+
+For short error messages, we follow the GNU coding standards.
+However, those are not quite enough, and we have developed an
+extended set of rules to follow for messages in english:
+
+  - put single quotes ('') aroung file names and paths, option names,
+    tag names and branch names, as well as any %s that would be
+    expanded to one of those.
+
+  - use a Capital first letter in command abstract and description
+    strings.  The following would be very wrong:
+
+        CMD(foo, "foo", "", CMD_REF(foos), "",
+            N_("does the foo thing"),
+            N_("in order to do the foo thing, this allows you to join "
+               "the foo fighters"),
+
+    The following is what it's supposed to look like:
+
+        CMD(foo, "foo", "", CMD_REF(foos), "",
+            N_("Does the foo thing"),
+            N_("In order to do the foo thing, this allows you to join "
+               "the foo fighters"),
+
+  - use a lowercase first letter in descriptions of options.  The
+    following would be wrong:
+
+        SIMPLE_OPTION(bar, "bar", bool,
+                      gettext_noop("Have the remaining figures go to "
+                                   the nearest bar"))
+
+    The following is better:
+
+        SIMPLE_OPTION(bar, "bar", bool,
+                      gettext_noop("have the remaining figures go to "
+                                   the nearest bar"))
+
+  - for multi-sentence error messages, use a lowercase first letter,
+    but have the second sentence and on start with a Capital letter,
+    and punctuate between sentences.  The following is an example that
+    does not follow this rule, and is quite unreadable:
+
+      E(!candidates.empty(), origin::user,
+        F("your request matches no descendents of the current revision\n"
+          "in fact, it doesn't even match the current revision\n"
+          "maybe you want something like --revision=h:%s")
+        % app.opts.branch);
+
+    The proper way to write this message is:
+
+      E(!candidates.empty(), origin::user,
+        F("your request matches no descendents of the current revision.\n"
+          "In fact, it doesn't even match the current revision.\n"
+          "Maybe you want something like --revision=h:%s")
+        % app.opts.branch);
+
+  - "monotone" and "mtn" are proper names with a lower case character,
+    and should always be written with a lower case first character,
+    even though language rules or the rules written here would say
+    otherwise.  If you find that troublesome, you might want to
+    consider rephrasing so the sentence doesn't start with "monotone"
+    or "mtn".
+
+  - Please consider that the user has to understand the messages, even
+    though they might not know all the inner details of how monotone
+    works, and might not have a programmer's mind.  For example, the
+    following message was hard to understand:
+
+        could not query default database locations
+
+    It has been replaced with the following (which will at least make
+    it clear that this is likely to be a configuration problem and not
+    some inner weirdness in monotone):
+
+        no default database location configured
+
+For translators, their language may have a different set of rules for
+things such as quoting (in the french translation, «_ and _» are used
+instead of single quotes, for example) and capitalization.  Please use
+your best judgement and be consistent.  Still, do not capitalize
+"monotone" or "mtn".
+
+
 Dialect issues
 --------------