Nice comments for URLs scripts

3 files changed, 42 insertions, 1 deletions

diff --git a/bin/htmlurls b/bin/htmlurls
index b99667de..fc13bac8 100755
--- a/bin/htmlurls
+++ b/bin/htmlurls
@@ -1,6 +1,23 @@
 #!/usr/bin/env bash
+
+#
+# Extract <a href="..."> URLs from an HTML document or documents.
+#
+# Author: Tom Ryder <tom@sanctum.geek.nz>
+# Copyright: 2016
+# License: Public domain
+#
+
+# Check we have the programs we need
 hash pup || exit
+
+# Emit the content of the args, or stdin
 cat -- "${@:-/dev/stdin}" |  ## shellcheck disable=SC2002
+
+# Pipe it through a pup filter to get all the values of the a href elements
 pup 'a attr{href}' |
+
+# Sort it; use a plain locale to force a proper bytewise sort so that
+# punctuation is not ignored
 LANG=C.UTF-8 sort |  # skipping punctuation in a locale sort is unacceptable
 uniq
diff --git a/bin/mdurls b/bin/mdurls
index f4cd281a..e15864aa 100755
--- a/bin/mdurls
+++ b/bin/mdurls
@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+
+#
+# Format markdown and pass it to htmlurls to extract URLs from it.
+#
+# Author: Tom Ryder <tom@sanctum.geek.nz>
+# Copyright: 2016
+# License: Public domain
+#
+
+# Check we have the programs we need
 hash markdown htmlurls || exit
-markdown "${@:-/dev/stdin}" |
+
+# Pipe the output of markdown(1) on our args ...
+markdown -- "${@:-/dev/stdin}" |
+
+# ... into our own htmlurls
 htmlurls
diff --git a/bin/urlcheck b/bin/urlcheck
index 9ecfe0fc..7151b85e 100755
--- a/bin/urlcheck
+++ b/bin/urlcheck
@@ -1,5 +1,15 @@
 #!/usr/bin/env bash
 
+#
+# Given a list of files or stdin containing a newline-separated list of URLs,
+# try to find erroneous, redirecting, or insecure URLs with working secure
+# alternatives.
+#
+# Author: Tom Ryder <tom@sanctum.geek.nz>
+# Copyright: 2016
+# License: Public domain
+#
+
 # Name self
 self=urlcheck