* HACKING: Minor updates and corrections.

ChangeLog

@@ -1,3 +1,7 @@
+2012-02-04  Alexandre Duret-Lutz  <adl@lrde.epita.fr>
+
+	* HACKING: Minor updates and corrections.
+
 2012-02-15  Alexandre Duret-Lutz  <adl@lrde.epita.fr>
 
 	Fix a race condition on the CGI script.

HACKING

@@ -13,7 +13,7 @@ since the generated files they produce are distributed.)
 
   GNU Autoconf >= 2.61
   GNU Automake >= 1.11
-  GNU Libtool >= 2.2
+  GNU Libtool >= 2.4
   GNU Flex (the version seems to matters, we used 2.5.35)
   GNU Bison >= 2.4.2
   SWIG >= 1.3.31
@@ -54,14 +54,14 @@ documentation has just been built.
 Debugging Libtool executables
 -----------------------------
 
-The executable generated in the various testsuite directories of Spot,
+The executables generated in the various testsuite directories of Spot
 are not real binaries.  Because we use libtool to compile the spot
-library in a portable manner, these executable are just script that
+library in a portable manner, these executables are just scripts that
-run the actual binary after setting some environment variable so that
+run the actual binary after setting some environment variables so that
 the OS can find the library in the build tree.
 
-A consequence is that tools like gdb or valgrind, that expect to
+A consequence is that tools like gdb or valgrind, that expect to work
-work on a binary, will be confused by the script.  Example:
+on a binary, will be confused by the script.  Example:
 
   % cd src/tgbatest
   % file ltl2tgba
@@ -70,8 +70,8 @@ work on a binary, will be confused by the script.  Example:
   "/home/adl/git/spot/src/tgbatest/ltl2tgba": not in executable format: File format not recognized
   (gdb) quit
 
-The proper way to work on these libtool scripts is via the libtool
+The proper way to run any command on these fake binaries is via
-command:
+libtool:
 
   % ../../libtool --mode=execute file ltl2tgba
   /home/adl/git/spot/src/tgbatest/.libs/lt-ltl2tgba: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.18, not stripped
@@ -79,17 +79,25 @@ command:
   Reading symbols from /home/adl/git/spot/src/tgbatest/.libs/lt-ltl2tgba...done.
   (gdb) quit
 
-If you are building Spot from the GIT repository the libtool script
+You can see that libtool turns ltl2tgba into .libs/lt-ltl2tgba, but it
+also sets environment variables so that the dependent shared libraries
+will be found.
+
+If you are building Spot from the GIT repository, the libtool script
 generated the root of the build tree should be the same as the libtool
 script that is installed on your system.  So you can simply run
 libtool instead of ../../libtool.
 
-You might also find conveniant to define a alias, a function, or a
+There is an undocumented feature of libtool that allows you to
-script to shorten the invocation of "libtool --mode=execute".
-
-Also there is an undocumented feature of libtool that allows you to
 shorthand "libtool --mode=execute" as "libtool execute" or even
-"libtool e".
+"libtool e".  But you might also find convenient to define an alias, a
+function, or a script to make that invocation even shorter.
+For instance:
+
+  alias le='libtool --mode=execute '
+
+(The trailing space makes it possible to follow this command by
+another aliased command.)
 
 
 Profiling with callgrind
@@ -154,7 +162,7 @@ Here are example options to pass to configure:
               CFLAGS='-flto' CXXFLAGS='-flto' LDFLAGS='-fuse-linker-plugin' \
               --disable-shared --enable-static
 
-Using --disable-debug prevents the '-g' flag to be passed to the
+Using --disable-debug prevents the -g flag to be passed to the
 compiler, which seems to help avoiding some internal compiler errors.
 
 Some binaries (like ltl2tgba) currently fail to compile (internal
@@ -173,6 +181,15 @@ conventions are derived from the GNU Coding Standards
 that we do not put a space before the opening parenthesis in function
 calls (this is hardly readable when chaining method calls).
 
+
+Encoding
+--------
+
+  * Use UTF-8 for non-ASCII characters.
+
+  * If you edit files encoded in Latin-1 (the original default
+    encoding for the project), feel free to convert them to UTF-8.
+
 Comments
 --------
 
@@ -248,7 +265,7 @@ Formating
 
   * No space before parentheses in function calls.
     (`some()->foo()->bar()' is far more readable than
-    `some ()->foo ()->bar ()' is)
+    `some ()->foo ()->bar ()')
 
   * No space after opening or before closing parentheses, however
     put a space after commas (as in english).
@@ -288,6 +305,15 @@ Formating
   * No line should be larger than 80 columns.
     If a line takes more than 80 columns, split it or rethink it.
 
+    This makes it easier to print the code, allow people to work on
+    small screens, makes it possible to display two files (or an
+    editor and a terminal) side-by-side, ...
+
+    This also puts some pressure on the programmer who writes code
+    that has too much nested blocks: if you find yourself having to
+    code between columns 60 and 80 because of identation, consider
+    writing helper functions to simplify the structure of your code.
+
   * Labels or case statements are back-indented by two spaces,
     without space before the `:'.
 
@@ -321,14 +347,13 @@ Formating
       int* q;
     instead of
       int *p, *q;
-    The former declarations also allow you to describe each variable.
+    The former declarations also allow you to comment each variable.
 
   * The include guard for src/somedir/foo.hh is
     SPOT_SOMEDIR_FOO_HH
 
-
 Naming
-======
+------
 
   * Functions, methods, types, classes, etc. are named with lowercase
     letters, using an underscore to separate words.
@@ -367,11 +392,11 @@ Naming
 
   * C Macros are all uppercase.
 
-  * Use *.hxx for the implementation of templates that are private
+  * Use *.hxx for the implementation of templates that are private to
-    to Spot (i.e. not installed) and need to be included multiple times.
+    Spot (i.e., not installed) and need to be included multiple times.
 
 Other style recommandations
-===========================
+---------------------------
 
   * Do not use the NULL macro, it is not always implemented in a way
     which is compatible with all pointer types.  Always use 0 instead.
@@ -392,3 +417,6 @@ Other style recommandations
     otherwise is to declare two classes with the same name: the linker
     will ignore one of the two silently.  The resulting bugs are often
     difficult to understand.)
+
+  * Always code as if the person who ends up maintaining your code is
+    a violent psychopath who knows where you live.