X-Git-Url: http://geeqie.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=CODING.md;h=e33bcdf53dd52ddae66a2f46b29463cd1e17de92;hb=b7618ec7c525acd94cbf31ee70afbee2342e90c9;hp=9e6bec02fd3b1c096984e0ad26a2e73e3060c0eb;hpb=31197b3d4f2ee55c84a2ae5c71995e2c5dad91c8;p=geeqie.git

diff --git a/CODING.md b/CODING.md
index 9e6bec02..e33bcdf5 100644
--- a/CODING.md
+++ b/CODING.md
@@ -3,9 +3,15 @@
 [Error Logging](#error-logging)  
 [GPL header](#gpl-header)  
 [Git change log](#git-change-log)  
-[Sources](#sources)  
-[Software Tools](#software-tools)  
+[Source Code Style](#source-code-style)  
+[Shell Script Style](#shell-script-style)  
+[External Software Tools](#external-software-tools)  
+[Geeqie Software Tools](#geeqie-software-tools)  
 [Documentation](#documentation)  
+[Documentation - C code](#c-code)  
+[Documentation - Script files](#script-files)  
+[Documentation - Markdown](#markdown)  
+[Doxygen](#doxygen)  
 
 ---
 
@@ -77,7 +83,7 @@ If referencing a Geeqie GitHub issue, include the issue number in the summary li
 
 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)
+See also [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
 
 Example:
 
@@ -95,7 +101,7 @@ Also please use your full name and a working e-mail address as author for any co
 
 ---
 
-## Sources
+## Source Code Style
 
 Indentation: tabs at 4 spaces
 
@@ -112,38 +118,38 @@ Conditions, cycles:
 
 ```c
 if (<cond>)
-	{
-	<command>;
-	...
-	<command>;
-	}
+    {
+    <command>;
+    ...
+    <command>;
+    }
 else
-	{
-	<command>;
-	...
-	<command>;
-	}
+    {
+    <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;
-	}
+    {
+    case 0:
+        <command>;
+        <command>;
+        break;
+    case 1:
+        <command>; break;
+    }
 
 for (i = 0; i <= 10; i++)
-	{
-	<command>;
-	...
-	<command>;
-	}
+    {
+    <command>;
+    ...
+    <command>;
+    }
 ```
 
 Functions:
@@ -151,18 +157,18 @@ Functions:
 ```c
 gint bar(<var_def>, <var_def>, <var_def>)
 {
-	<command>;
-	...
-	<command>;
+    <command>;
+    ...
+    <command>;
 
-	return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
+    return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
 }
 
 void bar2(void)
 {
-	<command>;
-	...
-	<command>;
+    <command>;
+    ...
+    <command>;
 }
 ```
 
@@ -194,7 +200,26 @@ Use glib functions when possible (i.e. `g_ascii_isspace()` instead of `isspace()
 Check if used functions are not deprecated.
 
 ---
-## Software Tools
+
+## Shell Script Style
+
+Use `/bin/sh` as the interpreter directive.  
+Ensure the script is POSIX compliant.  
+Use `printf` rather than `echo` except for plain text.  
+There are several versions of `mktemp`. Using the following definition helps portability (note that `template` is not optional):
+
+```sh
+mktemp [-d] [-q] template ...
+```
+
+and use for example this style:
+
+```sh
+mktemp  "${TMPDIR:-/tmp}/geeqie.XXXXXXXXXX"
+```
+
+---
+## External Software Tools
 
 ### astyle
 
@@ -221,7 +246,7 @@ align-reference=name
 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>
+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:
@@ -233,35 +258,71 @@ unusedFunction
 unmatchedSuppression
 ```
 
-### shellcheck
+### markdownlint
 
-Shell scripts may also be validated, e.g.
+Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
 
 ```sh
-shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
+mdl --style <style file>`
 ```
 
-### 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:
+Where the style file might contain:
 
 ```text
 all
+rule 'MD007', :indent => 4
 rule 'MD009', :br_spaces => 2
 rule 'MD010', :code_blocks => true
 exclude_rule 'MD013'
 ```
 
+### shellcheck
+
+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
+```
+
+### shfmt
+
+Shell scripts may formatted to some extent with [shfmt](https://github.com/mvdan/sh). At the time of writing it does not format `if`, `for` or `while` statements in the style used by Geeqie.  
+However the following script can be used to achieve that:
+
+```sh
+#!/bin/sh
+
+shfmt -s -p -ci -sr -fn | awk '
+    {if ($0 ~ /; then/)
+        {
+        match($0, /^\t*/);
+        printf('%s\n', substr($0, 0, length($0) - 6));
+        printf('%s, substr("\t\t\t\t\t\t\t\t\t\t", 1, RLENGTH))
+        print("then")
+        }
+    else if ($0 ~ /; do/)
+        {
+        match($0, /^\t*/);
+        printf('%s\n', substr($0, 0, length($0) - 4));
+        printf('%s', substr("\t\t\t\t\t\t\t\t\t\t", 1, RLENGTH))
+        print("do")
+        }
+    else
+        {
+        print
+        }
+    }'
+```
+
 ### xmllint
 
 The .xml Help files may be validated with e.g. `xmllint`.
 
-### check-compiles.sh
+---
+
+## Geeqie Software Tools
 
-This shell script is part of the Geeqie project and will compile Geeqie with various options.
+See the shell scripts section in the Doxygen documentation (`File List`, `detail level 3`, except the `src` sublist).
 
 ---
 
@@ -273,6 +334,8 @@ 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.  
 Not all comments have to be Doxygen comments.
 
+### C code
+
 - 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).
@@ -317,27 +380,61 @@ or
 * @FIXME
 ```
 
+### Script files
+
+Script files such as .sh, .pl, and .awk should have the file relevant file extension or be symlinked as so.
+
+Doxygen comments should start each line with `##`, and each file should contain:
+
+```sh
+## @file
+## @brief <one line description>
+## <contents description>
+##
+```
+
+### Markdown
+
+For a newline use two spaces (a backslash is not interpreted correctly by Doxygen).
+
+## Doxygen
+
 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.
 
-The following environment variables may be set to personalize the Doxygen output:  
-`DOCDIR=<output folder>`  
-`SRCDIR=<the folder above ./src>`  
-`PROJECT=`  
-`VERSION=`  
-`PLANTUML_JAR_PATH=`  
-`INLINE_SOURCES=<YES|NO>`  
-`STRIP_CODE_COMMENTS=<YES|NO>`  
+The following environment variables may be set to personalize the Doxygen output:
+
+```sh
+DOCDIR=<output folder>
+SRCDIR=<the top level directory of the project>
+PROJECT=
+VERSION=
+PLANTUML_JAR_PATH=
+INLINE_SOURCES=<YES|NO>
+STRIP_CODE_COMMENTS=<YES|NO>
+```
 
 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 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`
+For shell scripts to be documented, the file `doxygen-bash.sed` must be in the `$PATH` environment variable.  
+It can be download from here:
+
+```sh
+wget https://raw.githubusercontent.com/Anvil/bash-doxygen/master/doxygen-bash.sed
+chmod +x doxygen-bash.sed
+```
+
+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)
+
+```sh
+sudo apt install default-jre
+sudo apt install texlive-font-utils
+```
 
 ---