lint(checkdoc): add docstring, edit 2 docstrings

I've named it contrapunctus.mk to avoid getting clobbered by the
autogenerated Makefile. If we do away with the autotools stuff, we
could rename it Makefile.

.dir-locals.el

@@ -0,0 +1,26 @@
+;; `nameless-current-name' cannot be detected in Org mode buffers,
+;; IIRC, and thus has to be defined explicitly. To make use of this,
+;; install `nameless' and enable `nameless-mode' in Org mode buffers.
+((nil . ((nameless-current-name . "jabber")
+         (nameless-aliases . (("jaa" . "jabber-autoaway")
+                              ("ja"  . "jabber-avatar")
+                              ("jac" . "jabber-activity")
+                              ("jc"  . "jabber-chat")
+                              ("jco" . "jabber-console")
+                              ("jcs" . "jabber-chatstates")
+                              ("je"  . "jabber-events")
+                              ("jh"  . "jabber-history")
+                              ("jk"  . "jabber-keepalive")
+                              ("jm"  . "jabber-muc")
+                              ("jml" . "jabber-mode-line")
+                              ("jr"  . "jabber-roster")
+                              ("jp"  . "jabber-private")
+                              ("jrt" . "jabber-rtt")
+                              ("js"  . "jabber-socks5")
+                              ("jv"  . "jabber-vcard")
+                              ("jw"  . "jabber-whitespace")
+                              ("jx"  . "jabber-xml")))))
+ (org-mode . ((org-tags-column . -60)
+              (eval . (progn
+                        (make-local-variable 'before-save-hook)
+                        (add-hook 'before-save-hook #'org-align-all-tags nil t))))))

contrapunctus.mk

@@ -0,0 +1,56 @@
+.phony: all setup tangle compile lint clean
+
+all: setup tangle compile lint
+
+setup:
+	emacs --batch --eval="(package-initialize)" \
+	--eval="(mapcar #'package-install '(indent-lint package-lint relint))"
+
+# No -q or -Q without ORG_PATH - if the user has a newer version of
+# Org, we want to use it.
+jabber.el:
+	if [ -z "${ORG_PATH}" ]; then \
+          echo ; \
+	  echo "[WARNING] ORG_PATH is unset. Org versions older than 9.3.8 have a bug" ; \
+	  echo "which result in them always using absolute paths in comment links in" ; \
+	  echo "tangled source files. If your Org version is older than 9.3.8, please" ; \
+	  echo "upgrade it before tangling." ; \
+          echo ; \
+          emacs --batch \
+          --eval="(require 'ob-tangle)" \
+          --eval='(org-babel-tangle-file "jabber.org")' ; \
+        else \
+          emacs -q -Q --batch \
+          --eval="(add-to-list 'load-path \"${ORG_PATH}\")" \
+          --eval="(require 'ob-tangle)" \
+          --eval='(org-babel-tangle-file "jabber.org")' ; \
+        fi
+
+tangle: jabber.el
+
+compile: tangle
+	emacs -q -Q --batch --eval='(byte-compile-file "jabber.el")' ; \
+
+lint-check-declare: tangle
+	emacs -q -Q --batch --eval='(check-declare-file "jabber.el")'
+
+lint-checkdoc: tangle
+	emacs -q -Q --batch --eval='(checkdoc-file "jabber.el")'
+
+lint-package-lint: setup tangle
+	emacs -Q --batch --eval='(package-initialize)' \
+        --eval="(require 'package-lint)" \
+        -f 'package-lint-batch-and-exit' jabber.el
+
+lint-relint: setup tangle
+	emacs -q -Q --batch --eval='(relint-file "jabber.el")'
+
+lint: lint-check-declare lint-checkdoc lint-package-lint lint-relint
+
+clean-tangle:
+	-rm jabber.el
+
+clean-elc:
+	-rm *.elc
+
+clean: clean-elc

jabber.org

@@ -1,6 +1,6 @@
 #+TITLE: jabber.el
 #+SUBTITLE: XMPP client for Emacs
-#+PROPERTY: header-args :tangle yes :load yes
+#+PROPERTY: header-args :tangle yes :load yes :comments link
 #+TODO: TODO WIP EXTEND CLEANUP FIXME REVIEW |
 
 * README
@@ -46,7 +46,7 @@ Note that only the connection from you to the server is encrypted; there is no g
 
 ** Installation
 jabber.el can be installed using the commands:
-#+BEGIN_SRC shell
+#+BEGIN_SRC shell :tangle no :load no
 ./configure
 make
 make install
@@ -144,11 +144,15 @@ It is possible to make various web browsers pass links starting with "xmpp:" to
   - 2021 resurrection
 + contrapunctus
   - literate Org migration
+  - Makefile
++ tomasino on #team@irc.tilde.chat
+  - helping contrapunctus debug the Makefile
 
 * TODO maintenance [0%]
 1. [ ] Satisfy =M-x checkdoc=
 2. [ ] Use =rx= where regular expressions get hairy
 3. [ ] hexrgb.el is not available on MELPA
+4. [ ] Migrate tests to ERT/Buttercup/etc
 
 * About this file
 jabber.el is an Org literate program. Tangling is done automatically after each save.
@@ -168,10 +172,21 @@ If a source block does not have syntax highlighting, press =M-o M-o= (=font-lock
 7. [ ] "Code" has a lot of direct sub-headings, making it somewhat cumbersome to navigate; someone with a better understanding of the program could organize these better
 8. [X] The tangled file currently does not list all the other authors (currently listed in =:COPYRIGHT:= drawers). We could add them all at once in the library headers section...or something else. 🤔
 * Library headers and commentary
-=:comments no= here, because we do not want the first line of the file to be an Org link comment.
-#+BEGIN_SRC emacs-lisp :comments no
+:PROPERTIES:
+:header-args: :tangle yes :load yes :comments no
+:END:
+
+We don't want comments to be inserted within the package comment structure, and certainly not before the package first line summary, hence the =:comments no= in the header-args.
+#+BEGIN_SRC emacs-lisp
 ;;; jabber.el --- a minimal jabber client
 
+;; Author: Magnus Henoch <mange@freemail.hu>
+;; Maintainer: wgreenhouse <wgreenhouse@tilde.club>
+;; Keywords: comm
+;; Homepage: https://tildegit.org/wgreenhouse/emacs-jabber
+;; Package-Requires: ((hexrgb "0"))
+;; Version: 0.8.92
+
 ;; Copyright (C) 2003-2010, 2013 - Magnus Henoch - mange@freemail.hu
 ;; Copyright (C) 2002-2004 - Tom Berger - object@intelectronica.net
 ;; Copyright (C) 2005 - Georg Lehner - jorge@magma.com.ni
@@ -196,6 +211,10 @@ If a source block does not have syntax highlighting, press =M-o M-o= (=font-lock
 ;; along with this program; if not, write to the Free Software
 ;; Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
+#+END_SRC
+
+"Commentary" is displayed when the user clicks on the package's entry in =M-x list-packages=.
+#+BEGIN_SRC emacs-lisp
 ;;; Commentary:
 ;;
 
@@ -226,7 +245,7 @@ If a source block does not have syntax highlighting, press =M-o M-o= (=font-lock
   (require 'cl))
 
 #+END_SRC
-*** jabber-escape-xml                           :function:
+*** jabber-escape-xml                                 :function:
 #+BEGIN_SRC emacs-lisp
 (defun jabber-escape-xml (string)
   "Escape STRING for XML."
@@ -264,7 +283,7 @@ If a source block does not have syntax highlighting, press =M-o M-o= (=font-lock
     string))
 
 #+END_SRC
-*** jabber-sexp2xml                             :function:
+*** jabber-sexp2xml                                   :function:
 #+BEGIN_SRC emacs-lisp
 (defun jabber-sexp2xml (sexp)
   "Return SEXP as well-formatted XML.
@@ -544,10 +563,10 @@ ATTRIBUTES must be a list of symbols, as present in XML-DATA."
 #+END_SRC
 *** jabber-replace-in-string             :inline:function:
 #+BEGIN_SRC emacs-lisp
-(defsubst jabber-replace-in-string (str regexp newtext)
-  "Replace all matches for REGEXP with NEWTEXT in STR.
+(defsubst jabber-replace-in-string (string regexp newtext)
+  "Return STRING with all matches for REGEXP replaced with NEWTEXT.
 NEWTEXT is inserted literally, without changing its case or treating \\ specially."
-  (replace-regexp-in-string regexp newtext str t t))
+  (replace-regexp-in-string regexp newtext string t t))
 
 #+END_SRC
 *** jabber-propertize                           :function:
@@ -567,6 +586,7 @@ NEWTEXT is inserted literally, without changing its case or treating \\ speciall
 Preserve input method when entering a minibuffer.
 #+BEGIN_SRC emacs-lisp
 (defsubst jabber-read-with-input-method (prompt &optional initial-contents history default-value)
+  "Like `read-string', but always inheriting the current input method."
   (read-string prompt initial-contents history default-value t))
 
 #+END_SRC
@@ -706,9 +726,9 @@ JID must be a string."
 #+END_SRC
 *** jabber-jid-rostername                       :function:
 #+BEGIN_SRC emacs-lisp
-(defun jabber-jid-rostername (string)
-  "Return the name of the user, if given in roster, else nil."
-  (let ((user (jabber-jid-symbol string)))
+(defun jabber-jid-rostername (user)
+  "Return the name of USER if present in roster, or nil."
+  (let ((user (jabber-jid-symbol user)))
     (if (> (length (get user 'name)) 0)
 	(get user 'name))))
 
@@ -749,12 +769,11 @@ JID must be a string."
 #+BEGIN_SRC emacs-lisp
 (defvar jabber-jid-obarray)
 (defun jabber-jid-symbol (jid)
-  "Return the symbol for the given JID.
-JID must be a string."
+  "Return the symbol for JID, which must be a symbol or a string."
   ;; If it's already a symbol, just return it.
   (if (symbolp jid)
       jid
-    ;; XXX: "downcase" is poor man's nodeprep.  See XMPP CORE.
+    ;; XXX: "downcase" is a poor man's nodeprep.  See XMPP CORE.
     (intern (downcase (jabber-jid-user jid)) jabber-jid-obarray)))
 
 #+END_SRC
@@ -16629,9 +16648,3 @@ Contents of process buffers might be useful for debugging."
 ;;; jabber.el ends here
 
 #+END_SRC
-
-* Local variables                                 :noexport:
-# Local Variables:
-# org-tags-column: -60
-# eval: (add-hook 'after-save-hook (lambda nil (interactive) (compile (mapconcat #'shell-quote-argument `("emacs" "-q" "-Q" "--batch" "--eval=(require 'ob-tangle)" ,(format "--eval=(org-babel-tangle-file \"%s\")" (buffer-file-name))) " "))) nil t)
-# End: