diff options
author | Thien-Thi Nguyen <ttn@gnuvola.org> | 2021-11-24 09:55:48 -0500 |
---|---|---|
committer | Thien-Thi Nguyen <ttn@gnuvola.org> | 2021-11-24 09:55:48 -0500 |
commit | 68eaa84d297d4787fc24b30d56598e259afa5cf8 (patch) | |
tree | 66e58454cb1ec5a063d16f268afcce8aa73f8d9e /manpages/TDM.el | |
parent | 5b7226d7fe53bfef14bb12295bd4eb5b9c466b01 (diff) | |
download | docs-68eaa84d297d4787fc24b30d56598e259afa5cf8.tar.gz docs-68eaa84d297d4787fc24b30d56598e259afa5cf8.tar.bz2 docs-68eaa84d297d4787fc24b30d56598e259afa5cf8.zip |
Add Emacs Lisp library to help with manpages/* editing
Diffstat (limited to 'manpages/TDM.el')
-rw-r--r-- | manpages/TDM.el | 126 |
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 |