Use util_clip_triangle() in pan_item_tri_new()

[geeqie.git] / CODING.md

diff --git a/CODING.md b/CODING.md
index 9a98159..4f4d492 100644 (file)
--- a/CODING.md
+++ b/CODING.md
@@ -4,6 +4,7 @@
 [GPL header](#gpl-header)  
 [Git change log](#git-change-log)  
 [Source Code Style](#source-code-style)  
 [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)  
 [External Software Tools](#external-software-tools)  
 [Geeqie Software Tools](#geeqie-software-tools)  
 [Documentation](#documentation)  


@@ -41,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`
 
 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
 ---
 
 ## GPL header


@@ -82,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 "- ".
 
 
 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:
 
 
 Example:
 


@@ -186,6 +203,8 @@ Headers:
 #ifndef _FILENAME_H
 ```
 
 #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 `-`).
 
 Use spaces around every operator (except `.`, `->`, `++` and `--`).  
 Unary operator `*` and `&` are missing the space from right, (and also unary `-`).
 


@@ -196,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()`).  
 
 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
 ## External Software Tools
 
 ### astyle


@@ -264,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
 ```
 
 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`.
 ### xmllint
 
 The .xml Help files may be validated with e.g. `xmllint`.


@@ -281,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.
 
 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.
 
 To document the code use the following rules to allow extraction with Doxygen.  
 Not all comments have to be Doxygen comments.