summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@lukeshu.com>2017-05-24 13:16:59 -0400
committerLuke Shumaker <lukeshu@lukeshu.com>2017-05-24 13:16:59 -0400
commit59ab5f0d42872e08cbd721321a3f526c395b9d14 (patch)
treefcbc3eff5ee1479480436ed747f5f75b6044c8fd
parent5b417dd20f576ce36fe9150f03b16aeca1bfbf95 (diff)
Tidy the HACKING documentation.
-rw-r--r--HACKING/code-quality.md25
-rw-r--r--HACKING/code-style.md2
-rw-r--r--HACKING/contributing.md2
3 files changed, 14 insertions, 15 deletions
diff --git a/HACKING/code-quality.md b/HACKING/code-quality.md
index 8efd561..f296621 100644
--- a/HACKING/code-quality.md
+++ b/HACKING/code-quality.md
@@ -1,7 +1,7 @@
Code content
============
-Be aware of the `librelib(7)` library suite, which lives `src/lib`.
+Be aware of the `librelib(7)` library suite, which lives in `src/lib`.
It is a suite of Bash libraries that will help you out. Most of the
people looking at the libretools code are familiar with the `messages`
part of it, which actually contains a bunch of utility routines, not
@@ -16,14 +16,13 @@ Message printing: All of the message printing routines, except for
of that; don't use string interpolation (don't do `"foo ${var}
bar"`). The reason for this is that if you don't do string
interpolation, messages can be automatically internationalized.
-(Internationalization is incomplete at the momement)
Message printing: The in `--help`/`-h` text, use `print` to print
lines that should not wrap, `echo` to print blank lines, `prose` to
print paragraphs, `bullet` to print bullet points, and `flag` to print
option flags. The text should follow this general format:
- print "Usage: %s [OPTIONS] VARS_ARE_UNDERSCORE_AND_CAPITAL" "${program_name}"
+ print "Usage: %s [OPTIONS] VARS_ARE_UNDERSCORE_AND_CAPITAL" "${program_name}"
print "One line description of program, no period"
echo
prose "More details. This is a paragraph."
@@ -34,10 +33,6 @@ option flags. The text should follow this general format:
In the "Usage:" line, use printf `%s` and the value `"${0##*/}"` to
determine the program name at runtime.
-There used to be guidelines for how to align the option flags and
-descriptions, but now the `flag` command exists takes care of it for
-you. Yay for things being easier!
-
When using `set -u`, `set -e`, or `trap`, you should also use `set -E`
to have the error handling be passed down to subshells.
@@ -54,6 +49,9 @@ Use `set -u` if you can; it makes using an unset variable an error.
- The reason for this is that a normal string variable is basically
an array with length=1; an unset variable looks like an array
with length=0. Weird stuff.
+ - Actually, that was only true in Bash <4.4; but since the change
+ wasn't mentioned in the NEWS, I suspect that a subsequent version
+ will revert to the pre-4.4 behavior.
In the shebang, use `#!/usr/bin/env bash`. This allows us to not
hardcode the location of bash (I'm not sure why this is useful for
@@ -62,8 +60,8 @@ use-case for it).
In the shebang, don't pass flags to bash, besides breaking `env`
(above), it means people will make mistakes when debugging, and
-running things with `bash FILENAME`. Instead, use `set` to adjust the
-flags inside of the program.
+running things with `bash -x FILENAME`. Instead, use `set` to adjust
+the flags inside of the program.
Obey `$TMPDIR`. It's usually as easy as passing `--tmpdir` to
`mktemp`.
@@ -81,12 +79,13 @@ A lot of people look at the "Advanced Bash Scripting" ebook--DO NOT do
that, it is trash... though it contains a "reference card" page that
may be useful and isn't trash.
-Take a look at Gentoo's Bash guidelines
+Take a look at Gentoo's Bash
+guidelines
<http://devmanual.gentoo.org/tools-reference/bash/index.html>.
They're pretty good, and cover most of the "gotcha's" about Bash
-syntax. It mentions but discourages the use of Bash 3
-features... why? Who still uses Bash 2? Feel free to use Bash 4
-features!
+syntax. Though, it mentions but discourages the use of Bash 3
+features... why? Who still uses Bash 2? For libretools, you should
+feel free to use Bash 4 features!
I wrote an article on Bash arrays
<https://lukeshu.com/blog/bash-arrays.html>. A lot of people think
diff --git a/HACKING/code-style.md b/HACKING/code-style.md
index 077bc49..601ead1 100644
--- a/HACKING/code-style.md
+++ b/HACKING/code-style.md
@@ -35,7 +35,7 @@ should be
Of course, if the upper bound is a variable, the C-like syntax is
the better option, as otherwise you would have to use `seq` (calling
-an external), or `eval` (gross, easy to mess up royally).
+an external), or `eval` (gross, easy to mess up).
Indent comments like you would code; don't leave them at the beginning
of the line. Example:
diff --git a/HACKING/contributing.md b/HACKING/contributing.md
index 65066b5..3a9d083 100644
--- a/HACKING/contributing.md
+++ b/HACKING/contributing.md
@@ -5,7 +5,7 @@ I'd love to have your patches! Code should be hackable; if you want
to modify something, but can't figure out how: 1) ping me for help, 2)
it probably means the code was too complicated in the first place.
-Patches should be sent to <dev@lists.parabolagnulinux.org>; please put
+Patches should be sent to <dev@lists.parabola.nu>; please put
"[PATCH]" and "libretools" in the subject line. If you have commit
access, but want me to look over it first, feel free to create a new
branch in git, and I will notice it. Try to avoid pushing to the