Update coding documentation

Include section on tools which might be used to check sources in
CODING.md, plus reformatting of file.
Include check-compiles.sh script.

diff --git a/CODING.md b/CODING.md
index 7a517e9..9e6bec0 100644 (file)
--- a/CODING.md
+++ b/CODING.md
@@ -1,238 +1,323 @@
+# Coding and Documentation Style
+

 [Error Logging](#error-logging)  
 [GPL header](#gpl-header)  
 [Git change log](#git-change-log)  
 [Sources](#sources)  
 [Error Logging](#error-logging)  
 [GPL header](#gpl-header)  
 [Git change log](#git-change-log)  
 [Sources](#sources)  

+[Software Tools](#software-tools)  

 [Documentation](#documentation)  
 
 [Documentation](#documentation)  
 

------------
+---

 
 

+## Error Logging

 
 

-# <a name='error-logging'>
-# Error Logging
+### DEBUG_0()

 
 

-`DEBUG_0()`  

 Use `DEBUG_0()` only for temporary debugging i.e. not in code in the repository.
 The user will then not see irrelevant debug output when the default
 `debug level = 0` is used.
 
 Use `DEBUG_0()` only for temporary debugging i.e. not in code in the repository.
 The user will then not see irrelevant debug output when the default
 `debug level = 0` is used.
 

-`log_printf()`  
+### log_printf()
+

 If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
 
 If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
 

- - Note that these messages are output in the idle loop.
+- Note that these messages are output in the idle loop.
+
+### print_term()

 
 `print_term(gboolean err, const gchar *text_utf8)`
 
 - If `err` is TRUE output is to STDERR, otherwise to STDOUT
 
 
 `print_term(gboolean err, const gchar *text_utf8)`
 
 - If `err` is TRUE output is to STDERR, otherwise to STDOUT
 

+### DEBUG_NAME(widget)

 
 

-`DEBUG_NAME(widget)`  

 For use with the [GTKInspector](https://wiki.gnome.org/action/show/Projects/GTK/Inspector?action=show&redirect=Projects%2FGTK%2B%2FInspector) to provide a visual indication of where objects are declared.
 
 Sample command line call:  
 `GTK_DEBUG=interactive src/geeqie`
 
 For use with the [GTKInspector](https://wiki.gnome.org/action/show/Projects/GTK/Inspector?action=show&redirect=Projects%2FGTK%2B%2FInspector) to provide a visual indication of where objects are declared.
 
 Sample command line call:  
 `GTK_DEBUG=interactive src/geeqie`
 

---------------------------------------------------------------------------------
+---

 
 

-# <a name='gpl-header'>
-# GPL header
+## GPL header

 
 Include a header in every file, like this:  
 
 
 Include a header in every file, like this:  
 

-    /** @file  
-    * @brief Short description of this file.  
-    * @author Author1  
-    * @author Author2  
-    *  
-    * Optionally detailed description of this file    
-    * on more lines.    
-    */    
-
-    /*  
-    *  This file is a part of Geeqie project (http://www.geeqie.org/).  
-    *  Copyright (C) 2008 - 2021 The Geeqie Team  
-    *  
-    *  This program is free software; you can redistribute it and/or modify it  
-    *  under the terms of the GNU General Public License as published by the Free  
-    *  Software Foundation; either version 2 of the License, or (at your option)  
-    *  any later version.  
-    *  
-    *  This program is distributed in the hope that it will be useful, but WITHOUT  
-    *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or  
-    *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for  
-    *  more details.  
-    */  
-
--------------
-
-# <a name='git-change-log'>
-# git change-log
-
-If referencing a Geeqie GitHub issue, include the issue number in the summary line. Start with a short summary in the first line (without a dot at the end) followed by a empty line.
-
-If referencing a Geeqie GitHub issue, include a hyperlink to the GitHub issue webpage in the message body. Use whole sentences beginning with Capital letter. For each modification use a new line. Or you can write the theme, colon and then every change on new line, begin with "- ".
+```c
+/*
+ * Copyright (C) <year> The Geeqie Team
+ *
+ * Author: Author1  
+ * Author: Author2  
+ *  
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ *
+ * Optional description of purpose of file.
+ *
+*/  
+```
+
+---
+
+## git change-log
+
+If referencing a Geeqie GitHub issue, include the issue number in the summary line and a hyperlink to the GitHub issue webpage in the message body. Start with a short summary in the first line (without a dot at the end) followed by a empty line.
+
+Use whole sentences beginning with Capital letter. For each modification use a new line. Or you can write the theme, colon and then every change on new line, begin with "- ".

 
 See also [A Note About Git Commit Messages](http://www.tpope.net/node/106)
 
 Example:
 
 
 See also [A Note About Git Commit Messages](http://www.tpope.net/node/106)
 
 Example:
 

-   `I did some bugfixes`
+```text
+I did some bugfixes

 
 

-   `There was the bug that something was wrong. I fixed it.`
+There was the bug that something was wrong. I fixed it.

 
 

-  ` Library:`  
-   `- the interface was modified`  
-  `- new functions were added`
+Library:
+- the interface was modified
+- new functions were added`
+```

 
 Also please use your full name and a working e-mail address as author for any contribution.
 
 
 Also please use your full name and a working e-mail address as author for any contribution.
 

---------------------------------------------------------------------------------
+---

 
 

-# <a name='sources'>
-# Sources
+## Sources

 
 Indentation: tabs at 4 spaces
 
 Indentation: tabs at 4 spaces

-       
-       
+

 Names:
 
 Names:
 

-- of variables & functions:     small\_letters  
-- of defines:           CAPITAL\_LETTERS
+- of variables & functions: small\_letters  
+- of defines: CAPITAL\_LETTERS

 
 Try to use explicit variable and function names.  
 Try not to use macros.  
 
 Try to use explicit variable and function names.  
 Try not to use macros.  

-Use EITHER "struct foo" OR "foo"; never both
-
+Use **either** "struct foo" OR "foo"; never both

 
 Conditions, cycles:  
 
 
 Conditions, cycles:  
 

-    if (<cond>)
-       {
-       <command>;
-       ...
-       <command>;
-       }
-    else
-       {
-       <command>;
-       ...
-       <command>;
-       }
-
-    if (<cond_very_very_very_very_very_very_very_very_very_long> &&
-    <cond2very_very_very_very_very_very_very_very_very_long>)
-    <the_only_command>;
-
-    switch (<var>)
-       {
-       case 0:
-               <command>;
-                   <command>;
-                   break;
-       case 1:
-               <command>; break;
-       }
-
-    for (i = 0; i <= 10; i++)
-       {
-       <command>;
-       ...
-       <command>;
-       }
+```c
+if (<cond>)
+       {
+       <command>;
+       ...
+       <command>;
+       }
+else
+       {
+       <command>;
+       ...
+       <command>;
+       }
+
+if (<cond_very_very_very_very_very_very_very_very_very_long> &&
+<cond2very_very_very_very_very_very_very_very_very_long>)
+<the_only_command>;
+
+switch (<var>)
+       {
+       case 0:
+               <command>;
+               <command>;
+               break;
+       case 1:
+               <command>; break;
+       }
+
+for (i = 0; i <= 10; i++)
+       {
+       <command>;
+       ...
+       <command>;
+       }
+```

 
 Functions:
 
 
 Functions:
 

-    gint bar(<var_def>, <var_def>, <var_def>)
-    {
-       <command>;
-       ...
-       <command>;
+```c
+gint bar(<var_def>, <var_def>, <var_def>)
+{
+       <command>;
+       ...
+       <command>;

 
 

-       return 0; // i.e. SUCCESS; if error, you must return minus <err_no>
-    }
+       return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
+}

 
 

-    void bar2(void)
-    {
-       <command>;
-       ...
-       <command>;
-    }
+void bar2(void)
+{
+       <command>;
+       ...
+       <command>;
+}
+```

 
 Pragma: (Indentation 2 spaces)
 
 
 Pragma: (Indentation 2 spaces)
 

-    #ifdef ENABLE_NLS
-    #  undef _
-    #  define _(String) (String)
-    #endif /* ENABLE_NLS */
+```c
+#ifdef ENABLE_NLS
+#  undef _
+#  define _(String) (String)
+#endif /* ENABLE_NLS */
+```

 
 Headers:
 
 
 Headers:
 

-    #ifndef _FILENAME_H
+```c
+#ifndef _FILENAME_H
+```

 
 

+Use spaces around every operator (except `.`, `->`, `++` and `--`).  
+Unary operator `*` and `&` are missing the space from right, (and also unary `-`).

 
 

-Use spaces around every operator (except ".", "->", "++" and "--").   
-Unary operator '*' and '&' are missing the space from right, (and also unary '-').
-
-As you can see above, parentheses are closed to inside, i.e. " (blah blah) "  
-In "`function(<var>)`" there is no space before the '('.  
-You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if it makes your code nicer in being vertically indented.  
+As you can see above, parentheses are closed to inside, i.e. ` (blah blah) `  
+In `function(<var>)` there is no space before the `(`.  
+You *may* use more tabs/spaces than you *ought to* (according to this CodingStyle), if it makes your code nicer in being vertically indented.  

 Variables declarations should be followed by a blank line and should always be at the start of the block.  
 
 Variables declarations should be followed by a blank line and should always be at the start of the block.  
 

-
-Use glib types when possible (ie. gint and gchar instead of int and char).
-Use glib functions when possible (ie. `g_ascii_isspace()` instead of `isspace()`).
+Use glib types when possible (ie. gint and gchar instead of int and char).  
+Use glib functions when possible (i.e. `g_ascii_isspace()` instead of `isspace()`).  

 Check if used functions are not deprecated.
 
 Check if used functions are not deprecated.
 

---------------------------------------------------------------------------------
+---
+## Software Tools
+
+### astyle
+
+There is no code format program that exactly matches the above style, but if you are writing new code the following command line program formats code to a fairly close level:
+
+```sh
+astyle --options=<options file>
+```
+
+Where the options file might contain:
+
+```text
+style=vtk
+indent=force-tab
+pad-oper
+pad-header
+unpad-paren
+align-pointer=name
+align-reference=name
+```
+
+### cppcheck
+
+A lint-style program may be used, e.g.
+
+```sh
+cppcheck --language=c --library=gtk --enable=all --force  -USA_SIGINFO -UZD_EXPORT -Ugettext_noop -DG_KEY_FILE_DESKTOP_GROUP --template=gcc -I. --quiet --suppressions-list=<suppressions file>
+```
+
+Where the suppressions file might contain:
+
+```text
+missingIncludeSystem
+variableScope
+unusedFunction
+unmatchedSuppression
+```
+
+### shellcheck

 
 

-# <a name='documentation'>
-# Documentation
+Shell scripts may also be validated, e.g.
+
+```sh
+shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
+```
+
+### markdownlint
+
+Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).  
+`mdl --style <style file>`
+
+Where the style file might be:
+
+```text
+all
+rule 'MD009', :br_spaces => 2
+rule 'MD010', :code_blocks => true
+exclude_rule 'MD013'
+```
+
+### xmllint
+
+The .xml Help files may be validated with e.g. `xmllint`.
+
+### check-compiles.sh
+
+This shell script is part of the Geeqie project and will compile Geeqie with various options.
+
+---
+
+## Documentation

 
 Use American, rather than British English, spelling. This will facilitate consistent
 text searches. User text may be translated via the en_GB.po file.
 
 
 Use American, rather than British English, spelling. This will facilitate consistent
 text searches. User text may be translated via the en_GB.po file.
 

-To document the code use the following rules to allow extraction with doxygen.
-Do not save with comments. Not all comments have to be doxygen comments.
+To document the code use the following rules to allow extraction with Doxygen.  
+Not all comments have to be Doxygen comments.

 
 

-- Use C comments in plain C files and use C++ comments in C++ files for one line
-  comments.
-- Use '/**' (note the two asterisks) to start comments to be extracted by
-  doxygen and start every following line with " *".
-- Use '@' to indicate doxygen keywords/commands (see below).
-- Use the '@deprecated' command to tell if the function is subject to be deleted
-  or to a  complete rewrite.
-
-Example:
+- Use C comments in plain C files and use C++ comments in C++ files for one line comments.
+- Use `/**` (note the two asterisks) to start comments to be extracted by Doxygen and start every following line with ` *` as shown below.
+- Use `@` to indicate Doxygen keywords/commands (see below).
+- Use the `@deprecated` command to indicate the function is subject to be deleted or to a  complete rewrite.

 
 To document functions or big structures:
 
 
 To document functions or big structures:
 

-    /**
-     * @brief This is a short description of the function.
-     *
-     * This function does ...
-     *
-     * @param x1 This is the first parameter named x1
-     * @param y1 This is the second parameter named y1
-     * @return What the function returns
-     *    You can extend that return description (or anything else) by indenting the
-     *    following lines until the next empty line or the next keyword/command.
-     * @see Cross reference
-     */
+```c
+/**
+ * @brief This is a short description of the function.
+ *
+ * This function does ...
+ *
+ * @param x1 This is the first parameter named x1
+ * @param y1 This is the second parameter named y1
+ * @return What the function returns
+ *    You can extend that return description (or anything else) by indenting the
+ *    following lines until the next empty line or the next keyword/command.
+ * @see Cross reference
+ */
+```

 
 To document members of a structure that have to be documented (use it at least
 for big structures) use the `/**<` format:  
 
 To document members of a structure that have to be documented (use it at least
 for big structures) use the `/**<` format:  

-`int counter; /**< This counter counts images */`
+
+```c
+gint counter; /**< This counter counts images */
+
+```

 
 Document TODO or FIXME comments as:  
 
 
 Document TODO or FIXME comments as:  
 

-    /**  
-    * @todo
-   
-or 
- 
-    /**  
-    * @FIXME   
+```c
+/**  
+* @todo
+```
+
+or
+
+```c
+/**  
+* @FIXME
+```

 
 

-For further documentation about doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).  
+For further documentation about Doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).  

 For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
 
 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
 For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
 
 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.


@@ -249,12 +334,12 @@ The following environment variables may be set to personalize the Doxygen output
 Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)  
 Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
 
 Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)  
 Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
 

-To include diagrams (if any) in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:  
+To include diagrams in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:  

 [The PlantUML jar](https://plantuml.com/download)  
 `sudo apt install default-jre`  
 `sudo apt install texlive-font-utils`
 
 [The PlantUML jar](https://plantuml.com/download)  
 `sudo apt install default-jre`  
 `sudo apt install texlive-font-utils`
 

--------------
+---

 
 But in case just think about that the documentation is for other developers not
 for the end user. So keep the focus.
 
 But in case just think about that the documentation is for other developers not
 for the end user. So keep the focus.

diff --git a/scripts/check-compiles.sh b/scripts/check-compiles.sh
new file mode 100755 (executable)
index 0000000..3fa2ee7
--- /dev/null
+++ b/scripts/check-compiles.sh
@@ -0,0 +1,76 @@
+#!/bin/bash
+
+#/*
+# * Copyright (C) 2021 The Geeqie Team
+# *
+# * Author: Colin Clark  
+# *  
+# * This program is free software; you can redistribute it and/or modify
+# * it under the terms of the GNU General Public License as published by
+# * the Free Software Foundation; either version 2 of the License, or
+# * (at your option) any later version.
+# *
+# * This program is distributed in the hope that it will be useful,
+# * but WITHOUT ANY WARRANTY; without even the implied warranty of
+# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# * GNU General Public License for more details.
+# *
+# * You should have received a copy of the GNU General Public License along
+# * with this program; if not, write to the Free Software Foundation, Inc.,
+# * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+# *
+# *
+# * Check that Geeqie compiles with both gcc and clang,
+# * for both GTK2 and GTK3, and with and without optional modules.
+#*/  
+
+compile()
+{
+       # Cannot have --enable-debug-flags with --disable-gtk3
+
+       declare -A variant
+       variant[0]="$disable_list --disable-gtk3"
+       variant[1]="--disable-gtk3"
+       variant[2]="--enable-debug-flags $disable_list"
+       variant[3]="--enable-debug-flags"
+       variant[4]="$disable_list"
+       variant[5]=""
+
+       for ((i = 0; i <= 5; i++))
+       do
+               if [[ "${variant[$i]}" =~ "gtk3" ]]; then
+                       gtk="GTK2"
+               else
+                       gtk="GTK3"
+               fi
+               if [[ "${variant[$i]}" =~ "disable-threads" ]]; then
+                       disabled="all disabled"
+               else
+                       disabled="none disabled"
+               fi
+               if [[ "${variant[$i]}" =~ "--enable-debug-flags" ]]; then
+                       debug_flags="enable-debug-flags"
+               else
+                       debug_flags=""
+               fi
+
+               echo -e " \e[32m $1 $gtk $debug_flags $disabled "
+               sudo make maintainer-clean > /dev/null 2>&1
+               ./autogen.sh " ${variant[$i]}" > /dev/null 2>&1
+               make -j > /dev/null
+       done
+}
+
+disable_list=" "$(awk -F'[\[\]]' '/AC_HELP_STRING\(\[--disable-/ {if ($2 != "gtk3") print $2}' configure.ac | tr '\n' ' ')
+
+echo "Disabled list: :$disable_list"
+
+export CFLAGS="-Wno-deprecated-declarations"
+
+export CC=clang
+export CXX=clang++
+compile "clang"
+
+export CC=
+export CXX=
+compile "gcc"