Add Emacs Lisp library to help with manpages/* editing

1 files changed, 126 insertions, 0 deletions

diff --git a/manpages/TDM.el b/manpages/TDM.el
new file mode 100644
index 00000000..98a9a462
--- /dev/null
+++ b/manpages/TDM.el
@@ -0,0 +1,126 @@
+;;; TDM.el --- editing Taler docs.git/manpages/*   -*- lexical-binding: t -*-
+
+;; Copyright (C) 2021 Taler Systems SA
+;;
+;; This file is part of GNU TALER.
+;;
+;; TALER is free software; you can redistribute it and/or modify it
+;; under the terms of the GNU Affero General Public License as
+;; published by the Free Software Foundation; either version 2.1,
+;; or (at your option) any later version.
+;;
+;; TALER is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU Affero General Public License for more details.
+;;
+;; You should have received a copy of the GNU Affero General Public
+;; License along with TALER; see the file COPYING.  If not, see
+;; <http://www.gnu.org/licenses/>.
+;;
+;; Author: Thien-Thi Nguyen <ttn@gnu.org>
+
+;;; Commentary:
+
+;; This library currently provides one command: ‘TDM-convert-options’.
+;; The intended workflow is simple:
+;;  - Create a new file from template.
+;;  - Do the <FOO> subtitutions / deletions as necessary.
+;;  - Split the window, one half for Synopsis, one for Description.
+;;  - Do ‘COMMAND --help’ and copy the portion of its output that
+;;    describes the options into the buffer in the Synopsis section.
+;;  + Place point at bol of an option and call ‘TDM-convert-options’.
+;;    (Personally, I locally bind this to ‘C-c C-o’.)
+;;  - Set mark at point and move point to the end of the
+;;    description text (for that option).
+;;  - Kill the region (with ‘C-w’).
+;;  - Switch to the other window, find a suitable place, and
+;;    yank (with ‘C-y’) the text there.
+;;  - Edit the description as necessary.
+;;  - Loop from "+" until finished.
+;;
+;; At the end, you may have to delete some extra blank lines
+;; in the Synopsis section.
+;;
+;; ‘TDM-convert-options’ takes a prefix arg, which inhibits the
+;; deletion of the original (--help output) text.  This can be
+;; useful if you don't trust (yet :-D) the conversion process.
+;;
+;; There are a couple TODO items, which point to situations that
+;; have not yet arisen in practice, but that might theoretically
+;; bother us in the future.
+
+;;; Code:
+
+(require 'cl-lib)
+
+(defun TDM-parse-option-triple ()
+  "Return a triple formed by parsing option text at point.
+The triple has the form (ARG SHORT LONG), where each element
+can be either a string or ‘nil’.
+
+Signal error if parsing fails.
+Leave point after the end of the parsed text."
+  (cl-flet ((peer (regexp)
+                  (re-search-forward regexp (line-end-position) t)))
+    (cond
+     ;; Full form: (ARG SHORT LONG).
+     ((peer " *-\\(.\\), --\\([^=\n]+\\)=\\(\\S +\\)")
+      (mapcar #'match-string-no-properties (list 3 1 2)))
+     ;; No argument: (nil SHORT LONG).
+     ((peer " *-\\(.\\), --\\(\\S +\\)")
+      (list nil
+            (match-string-no-properties 1)
+            (match-string-no-properties 2)))
+     ;; TODO: Handle other combinations.
+     (t
+      (error "Could not parse option text")))))
+
+(defun TDM-insert-options (arg short long)
+  "Insert formatted options, twice (on two lines).
+The first is for the Synopsis section, the second for Description."
+  (unless (zerop (current-column))
+    (open-line 1)
+    (forward-line 1))
+  (cl-flet ((ins (short-space sep)
+                 (cond
+                  ;; Both available.
+                  ((and short long)
+                   (insert "**-" short "**")
+                   (when arg
+                     (insert short-space "*" arg "*"))
+                   (insert sep)
+                   (insert "**--" long (if arg "=" "") "**")
+                   (when arg
+                     (insert "\\ \\ *" arg "*")))
+                  ;; TODO: Handle other combinations.
+                  (t
+                   (error "Could not handle (%S %S %S)"
+                          arg short long)))))
+    ;; First line.
+    (insert "[")
+    (ins " " " | ")
+    (insert "]\n")
+    ;; Second line.  Leave point at its beginning.
+    (save-excursion
+      (ins " " " \\| ")
+      ;; Add a newline only if necessary.
+      (unless (eolp)
+        (insert "\n")))))
+
+(defun TDM-convert-options (&optional keep-orig)
+  "Grok the options at point and insert formatted ones.
+If successful, delete the parsed options as well.
+Prefix arg KEEP-ORIG means don't delete them."
+  (interactive "P")
+  (let* ((p (point))
+         (triple (TDM-parse-option-triple))
+         (q (point)))
+    (apply #'TDM-insert-options triple)
+    (unless keep-orig
+      (save-excursion
+        (delete-region p q)))))
+
+(provide 'TDM)
+
+;;; TDM.el ends here