[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)
---
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
+
+```text
+When the LogWindow has focus, the F1 key executes the following action as a command line program:
+<options->log_window.action> <selected text>
+The log_window.action value must be set by editing the geeqierc.xml file manually.
+If no text is selected when the F1 key is pressed, the text either side of the cursor delimited by a space character or the beginning or end of the line is selected.
+This feature may be used to open an editor at a file location listed in the backtrace.
+```
+
+### 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
+
---
## GPL header
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:
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.
+Use UNUSED() for unused function parameters.
+
+---
+
+## 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
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`.
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.
##
```
+### 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).