Include check for untranslated text

[geeqie.git] / CODING.md

diff --git a/CODING.md b/CODING.md
index ac999c8..4f4d492 100644 (file)
--- a/CODING.md
+++ b/CODING.md
@@ -4,11 +4,13 @@
 [GPL header](#gpl-header)  
 [Git change log](#git-change-log)  
 [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)  
 
 ---
@@ -40,6 +42,22 @@ For use with the [GTKInspector](https://wiki.gnome.org/action/show/Projects/GTK/
 Sample command line call:  
 `GTK_DEBUG=interactive src/geeqie`
 
+### DEBUG_BT()
+
+Prints a backtrace.
+Use only for temporary debugging i.e. not in code in the repository
+
+### DEBUG_FD()
+
+Prints a dump of the FileData hash list as a ref. count followed by the full path of the item.
+Use only for temporary debugging i.e. not in code in the repository
+
+### Log Window
+
+When the Log Window has focus, the F1 key executes the action specified in `Edit/Preferences/Behavior/Log Window F1 Command` with the selected text as a parameter.
+If no text is selected, the entire line is passed to the command.
+This feature may be used to open an editor at a file location in the text string.
+
 ---
 
 ## GPL header
@@ -81,7 +99,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:
 
@@ -185,6 +203,8 @@ Headers:
 #ifndef _FILENAME_H
 ```
 
+Use [Names and Order of Includes](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) for headers include order.
+
 Use spaces around every operator (except `.`, `->`, `++` and `--`).  
 Unary operator `*` and `&` are missing the space from right, (and also unary `-`).
 
@@ -195,9 +215,29 @@ Variables declarations should be followed by a blank line and should always be a
 
 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.  
 
 ---
+
+## 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
@@ -263,6 +303,36 @@ Shell scripts may also be validated, e.g.
 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`.
@@ -280,6 +350,8 @@ See the shell scripts section in the Doxygen documentation (`File List`, `detail
 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 avoid confusion between American and British date formats, use ISO format (YYYY-MM-DD) where possible.
+
 To document the code use the following rules to allow extraction with Doxygen.  
 Not all comments have to be Doxygen comments.
 
@@ -342,6 +414,10 @@ Doxygen comments should start each line with `##`, and each file should contain:
 ##
 ```
 
+### 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).