Make many linters much happpier

filters/_simple-headers.lua

@@ -1,3 +1,5 @@
+-- SPDX-License-Identifier: GPL-3.0-or-later
+
 local header_ids = {}
 
 local function collect_id (header)

org-pandoc-import-transient.el

@@ -1,13 +1,20 @@
-;;; org-pandoc-import-transient.el -*- lexical-binding: t; -*-
+;;; org-pandoc-import-transient.el --- Convert other formats to Org on-the-fly -*- lexical-binding: t; -*-
 
 ;; This file is part of org-pandoc-import.
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 
+;;; Commentary:
+
+;; Utilise the work in `org-pandoc-import' to create a minor mode that enables
+;; on-the-fly conversion to and from Org.
+
+;;; Code:
+
 (require 'org-pandoc-import)
 (require 'org)
 (require 'ox-pandoc nil t)
 
-(defcustom org-import-transient-async-export nil
+(defcustom org-pandoc-import-transient-async-export nil
   "Whether or not to use Org's async export mode.
 This trades a short blocking period for a long non-blocking period."
   :type 'list
@@ -19,12 +26,12 @@ This trades a short blocking period for a long non-blocking period."
      ("odt" . "odt")
      ("csv" . (lambda ()
                 (unless (org-at-table-p)
-                  (user-error "Point is not inside a table."))
+                  (user-error "Point is not inside a table"))
                 (org-table-export (concat (file-name-base (buffer-file-name)) ".csv")
                                   "orgtbl-to-csv")))
      ("tsv" . (lambda ()
                 (unless (org-at-table-p)
-                  (user-error "Point is not inside a table."))
+                  (user-error "Point is not inside a table"))
                 (org-table-export (concat (file-name-base (buffer-file-name)) ".tsv")
                                   "orgtbl-to-tsv"))))
    (when (featurep 'ox-pandoc)
@@ -69,7 +76,8 @@ the handler is called for the right file extensions."
                 file-name-handler-alist)))
 
 (defun org-pandoc-import-transient--file-handler (operation &rest args)
-  "Expand file names through `org-pandoc-import-transient--file-handler' when mode is active."
+  "Expand file names through `org-pandoc-import-transient--file-handler' when
+mode is active.  Argument OPERATION is the file operation being performed."
   (let ((inhibit-file-name-handlers
          (cons 'org-pandoc-import-transient--file-handler
                (and (eq inhibit-file-name-operation operation)
@@ -124,8 +132,8 @@ Returns information on the location and state of the converted file."
 
 (defun org-pandoc-import-transient--maybe-converted-org-file-handler (operation &rest args)
   "When an org file is saved, back-propogate the changes if appropriate.
-This is done by exporting the org file to the target file type, after checking that the
+This is done by exporting the org file to the target file type, after checking
-curret file is indeed a transient conversion."
+that the curret file is indeed a transient conversion."
   (let ((inhibit-file-name-handlers
          (cons 'org-pandoc-import-transient--maybe-converted-org-file-handler
                (and (eq inhibit-file-name-operation operation)
@@ -160,21 +168,27 @@ curret file is indeed a transient conversion."
                         (start-time (time-to-seconds (current-time))))
               (if (functionp exporter)
                   (funcall exporter)
-                (org-export-to-file (intern exporter) source-file org-import-transient-async-export))
+                (org-export-to-file (intern exporter) source-file org-pandoc-import-transient-async-export))
               (message "Updated %s in %2fs." source-file (- (time-to-seconds (current-time)) start-time)))))
          (t (apply operation args)))
       (apply operation args))))
 
 (defun org-pandoc-import-transient--killed ()
-  "When this buffer is closed, we assume that the source file is liable to be modified.
+  "When this buffer is closed, we assume that the source file may be modified.
 Thus, if we re-open the file with `org-pandoc-import-transient-mode' enabled,
 we want to re-create the associated org file."
   (plist-put (cdr (assoc (buffer-file-name) org-pandoc-import-transient--files)) :initialised nil))
 
-(defun org-pandoc-import-transient--cleanup ()
+(defun org-pandoc-import-transient-cleanup (&optional keep-file-handlers)
-  "Deregister file handlers and remove all .opi-transient working dirs, to avoid cluttering.
+  "Remove all .opi-transient working dirs to avoid cluttering.
-Dirs to remove are found from `org-pandoc-import-transient--files'."
+Dirs to remove are found from `org-pandoc-import-transient--files'.
-  (org-pandoc-import-transient--deregister-file-handlers)
+
+Unless KEEP-FILE-HANDLERS is set, the file handlers will be deregistered.
+This KEEP-FILE-HANDLERS is observed when called interactively without
+a prefix argument."
+  (interactive "p")
+  (unless (eq keep-file-handlers 1)
+    (org-pandoc-import-transient--deregister-file-handlers))
   (dolist (transient-dir
            (delete-dups
             (mapcar #'file-name-directory
@@ -185,7 +199,7 @@ Dirs to remove are found from `org-pandoc-import-transient--files'."
   (setq org-pandoc-import-transient--files nil))
 
 (org-pandoc-import-transient--register-file-handlers)
-(add-hook 'kill-emacs-hook #'org-pandoc-import-transient--cleanup)
+(add-hook 'kill-emacs-hook #'org-pandoc-import-transient-cleanup)
 
 (provide 'org-pandoc-import-transient)
 

org-pandoc-import.el

@@ -2,7 +2,7 @@
 
 ;; Copyright (C) 2020 TEC
 
-;; Author: TEC <http://github/tecosaur>
+;; Author: TEC <https://github/tecosaur>
 ;; Maintainer: TEC <tec@tecosaur.com>
 ;; Created: 16 Aug 2020
 ;; Modified: August 29, 2020
@@ -32,9 +32,9 @@
 
 ;;; Commentary:
 
-;; Leverage Pandoc to convert non-org formats to org, and supplies a minor mode
+;; Leverage Pandoc to make convert non-org formats to org trivial.
-;; to do on-the-fly conversion transparently and automatically, exporting
+;; Also supplies a minor mode to do on-the-fly conversion transparently
-;; to the original format on save.
+;; and automatically, exporting to the original format on save.
 
 ;;; Code:
 
@@ -84,9 +84,10 @@ If FITERS/backend.lua exists, it will automatically be used when backend is regi
   (expand-file-name
    "preprocessors" org-pandoc-import-setup-folder)
   "A file to but pre-processors in.
-When a new backend is defined,if PREPROCESSORS/backend.el exists it will be loaded,
+When a new backend is defined, if PREPROCESSORS/backend.el exists it will be
-and if org-pandoc-import-(backend)-preprocessor exists, it will be called
+loaded, and if org-pandoc-import-backend-preprocessor exists (where backend a
-with the input file as the argument, and the result used as the new input file."
+placeholder for the actual backend name), it will be called with the input file
+as the argument, and the result used as the new input file."
   :type 'string
   :group 'org-pandoc-import)
 
@@ -94,8 +95,10 @@ with the input file as the argument, and the result used as the new input file."
   "List of arguments to apply to all backends.
 Accepts three types of atoms:
 - strings, which are passed as-is to `call-process'
-- plist keywords, which have the : replaced with single dash if the word is one charachter, else two dashes
+- plist keywords, which have the : replaced with single dash if the word
-- functions, which are evaluated and have the result passed as one of the arguments"
+  is one charachter, else two dashes
+- functions, which are evaluated and have the result passed as one
+  of the arguments"
   :type 'list
   :group 'org-pandoc-import)
 
@@ -115,10 +118,13 @@ By default, all files starting with '_' in `org-pandoc-import-filters-folder' ar
 
 ;;;###autoload
 (defmacro org-pandoc-import-backend (name &optional recognised-extensions pandoc-type filters pandoc-args)
-  "Create an export backend named NAME which is applied by default on RECOGNISED-EXTENSIONS.
+  "Create an export backend named NAME.
-This calls pandoc, specifying the input format to be PANDOC-TYPE. PANDOC-ARGS is a list of args passed to
+The backend is applied by default on files which end in a RECOGNISED-EXTENSIONS.
-the pandoc command in the same manner as `org-pandoc-import-global-args'.
+This calls pandoc, specifying the input format to be PANDOC-TYPE.
-Filters can be either absolute paths to pandoc filters, or names of files within `org-pandoc-import-filters-folder'.
+PANDOC-ARGS is a list of args passed to the pandoc command in the same manner
+as `org-pandoc-import-global-args'.
+Filters can be either absolute paths to pandoc filters, or names of files
+within `org-pandoc-import-filters-folder'.
 
 RECOGNISED-EXTENSIONS defaults to '(\"NAME\"), and PANDOC-TYPE to \"NAME\"."
   (let* ((s-name (symbol-name name))
@@ -171,19 +177,24 @@ Calls pandoc with arguments listed in `org-pandoc-import-%s-args', and filters `
 
 (defun org-pandoc-import-convert (prompty out-file pandoc-type &optional in-file expected-extensions args filters syncronous-p preprocessor)
   "Call pandoc on an IN-FILE.
-Determines the relevant paramaters to convert IN-FILE of type PANDOC-TYPE to either OUT-FILE, or a buffer (when OUT-FILE is nil).
+Determines the relevant paramaters to convert IN-FILE of type PANDOC-TYPE to
+either OUT-FILE, or a buffer (when OUT-FILE is nil).
 
-If PROMPTY is non-nill, then the value of IN-FILE and (if applicable) OUT-FILE will be always prompted for.
+If PROMPTY is non-nill, then the value of IN-FILE and (if applicable) OUT-FILE
-A prompt for IN-FILE is also triggered when IN-FILE is nil, or its extension is not a member of EXPECTED-EXTENSIONS.
+will be always prompted for.  A prompt for IN-FILE is also triggered when
-A prompt for OUT-FILE is triggered when OUT-FILE is t, or the name of a pre-existing file.
+IN-FILE is nil, or its extension is not a member of EXPECTED-EXTENSIONS.
-Pandoc is then called with arguments from the list ARGS - as described in `org-pandoc-import-global-args',
+A prompt for OUT-FILE is triggered when OUT-FILE is t, or the name of a
-and filters named in the list FILTERS - which can be either absolute paths to pandoc filters, or names of files within `org-pandoc-import-filters-folder'.
+pre-existing file.  Pandoc is then called with arguments from the list ARGS,
+as described in `org-pandoc-import-global-args', and filters named in the list
+FILTERS --- which can be either absolute paths to pandoc filters, or names of
+files within `org-pandoc-import-filters-folder'.
 
-If preprocessor is given, and a function, it is run with the value of IN-FILE. The value returned is used as the new IN-FILE."
+If preprocessor is given, and a function, it is run with the value of IN-FILE.
+The value returned is used as the new IN-FILE."
 
   (let* ((in-file (or in-file
                       (if (and (not prompty)
-                               (not (null (buffer-file-name)))
+                               (buffer-file-name)
                                (if expected-extensions
                                    (member (file-name-extension (buffer-file-name))
                                            expected-extensions))
@@ -254,7 +265,10 @@ If preprocessor is given, and a function, it is run with the value of IN-FILE. T
       (set-process-sentinel process (org-pandoc-import-process-sentinel pandoc-buffer out-file (time-to-seconds (current-time)))))))
 
 (defun org-pandoc-import-process-sentinel (process-buffer &optional out-file start-time-seconds)
-  "Creats a lambda sentinel for a pandoc process."
+  "Creats a lambda sentinel for a pandoc process, outputing to PROCESS-BUFFER.
+If OUT-FILE is given, kill the PROCESS-BUFFER and use the file in its place.
+When START-TIME-SECONDS is given, a messege is generated indicating the total
+time elapsed."
   (lambda (process _signal)
     (pcase (process-status process)
       ('exit (if out-file
@@ -266,13 +280,13 @@ If preprocessor is given, and a function, it is run with the value of IN-FILE. T
                (message "Converted docunent in %3fs" (- (time-to-seconds (current-time)) start-time-seconds)))
              (org-mode))
       ((or 'stop 'signal 'failed)
-       (user-error (format "The pandoc process to create %s has exited unexpectedly." out-file))
+       (user-error "The pandoc process to create %s has exited unexpectedly." out-file)
        (switch-to-buffer process-buffer)))))
 
 (defun org-pandoc-import-generate-convert-arguments (in-file target-format &optional out-file arguments-list)
   "Format the provided arguments to be passed to pandoc.
-Have pandoc convert IN-FILE of pandoc type TARGET-FORMAT to the org file OUT-FILE (if given),
+Have pandoc convert IN-FILE of pandoc type TARGET-FORMAT to the org file
-with arguments given by ARGUMENTS-LIST."
+OUT-FILE (if given), with arguments given by ARGUMENTS-LIST."
   (let (arguments)
     (dolist (element (reverse (append arguments-list org-pandoc-import-global-args)))
       (push
@@ -294,12 +308,15 @@ with arguments given by ARGUMENTS-LIST."
 
 ;;;###autoload
 (defun org-pandoc-import-as-org (prompty &optional in-file syncronous-p)
-  "Parse the provided file to org-mode, and open in a new buffer.
+  "Parse the provided file to `org-mode', and open in a new buffer.
-With PROMPTY (given by the universal argument), always prompt for the IN-FILE to act on.
+With PROMPTY (given by the universal argument), always prompt for the IN-FILE
+to act on.
 
-This only works so long as these is backend registered in `org-pandoc-import-backends'
+This only works so long as these is backend registered in
-associated with the extension of the selected file. See 'org-pandoc-import-{backend}-as-org'
+`org-pandoc-import-backends' associated with the extension of the selected file.
-for more information on a particular backend."
+See org-pandoc-import-{backend}-as-org for information on a particular backend.
+
+When syncronous-p is set, the pandoc process is run in a blocking manner."
   (interactive "P")
   (if-let ((backend (org-pandoc-import-find-associated-backend (or in-file (buffer-file-name)))))
       (funcall (intern (format "org-pandoc-import-%s-as-org" (symbol-name backend)))
@@ -308,13 +325,17 @@ for more information on a particular backend."
 
 ;;;###autoload
 (defun org-pandoc-import-to-org (prompty &optional in-file out-file syncronous-p)
-  "Parse the provided file to an org-mode file, and open.
+  "Parse the provided file to an `org-mode' file, and open.
-With PROMPTY (given by the universal argument), always prompt for the IN-FILE to act on,
+With PROMPTY (given by the universal argument), always prompt for the IN-FILE to
-and the where to save the new Org file.
+act on, and the where to save the new Org file.
+The result is saved to OUT-FILE, which defaults to IN-FILE but with the .org
+extension.
 
-This only works so long as these is backend registered in `org-pandoc-import-backends'
+This only works so long as these is backend registered in
-associated with the extension of the selected file. See 'org-pandoc-import-{backend}-as-org'
+`org-pandoc-import-backends' associated with the extension of the selected file.
-for more information on a particular backend."
+See org-pandoc-import-{backend}-as-org for information on a particular backend.
+
+When syncronous-p is set, the pandoc process is run in a blocking manner."
   (interactive "P")
   (if-let ((backend (org-pandoc-import-find-associated-backend (or in-file (buffer-file-name)))))
       (funcall (intern (format "org-pandoc-import-%s-to-org" (symbol-name backend)))
@@ -323,8 +344,9 @@ for more information on a particular backend."
 
 
 (defun org-pandoc-import-find-associated-backend (file)
-  "Find the backend symbol from `org-pandoc-import-backends' associated with FILE's extension.
+  "Find the backend symbol from associated with FILE's extension.
-nil if no such association could be found."
+The backend is found from searching `org-pandoc-import-backends', and is nil
+if no such match could be found."
   (when file
     (let ((ext (file-name-extension file))
           the-backend)

preprocessors/rmarkdown.el

@@ -1,4 +1,5 @@
-;;; org-pandoc-import/preprocessors/rmarkdown.el -*- lexical-binding: t; -*-
+;;; org-pandoc-import/preprocessors/rmarkdown.el --- Pre-process Rmarkdown files before importing -*- lexical-binding: t; -*-
+;;; SPDX-License-Identifier: GPL-3.0-or-later
 
 (defun org-pandoc-import-rmarkdown-preprocessor (in-file)
   (let ((processed-file (make-temp-file "opif" nil ".Rmd")))

preprocessors/tsv.el

@@ -1,4 +1,5 @@
-;;; org-pandoc-import/preprocessors/tsv.el -*- lexical-binding: t; -*-
+;;; org-pandoc-import/preprocessors/tsv.el --- Pre-process tsv files before importing -*- lexical-binding: t; -*-
+;;; SPDX-License-Identifier: GPL-3.0-or-later
 
 (defun org-pandoc-import-tsv-preprocessor (in-file)
   (let ((processed-file (make-temp-file "opif" nil ".csv")))