~Make emacs friendlier: package documentation [POC CODE INCLUDED]

[Boruch Baum <boruch_baum@gmx.com>]

[-- Attachment #1: Type: text/plain, Size: 766 bytes --]

A programmer's idea of a friendly environment might be the opposite of a
user's in that what programmer enjoys writing documentation, and having
to repeat the process with almost identical text in more than place, and
in more than one format. There are docstrings, and then there's the
commentary at the top of the elisp file, and then any info file, and
what else.

Attached is working proof-of-concept code to allow a user to easily get
all a package's in-line documentation, in the format of an org-mode
buffer, to cover cases where there is no info file, or to supplement the
info file.

Evaluate the code, Perform M-x pack-doc, and select an emacs-lisp
package file.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

[-- Attachment #2: pack-doc.el --]
[-- Type: text/plain, Size: 2025 bytes --]

;;; pack-doc.el --- Make org documetation from package source file -*- lexical-binding: t -*-

(defun pack-doc (file)
  "Create documentation in org-mode format from FILE.
FILE is an elisp source file formatted according to the emacs
style. Result is an org mode buffer containing the file's
doumentary comments and docstrings."
  (interactive "f")
  ;; TODO: handle prompt for file if NIL
  (switch-to-buffer (get-buffer-create (concat (file-name-nondirectory file) ".org")))
  (insert-file-contents-literally file nil nil nil 'replace)
  (goto-char (point-min))
  ;; Comment-out docstrings
  (let (p0 p1 p2)
    (while (setq p0 (re-search-forward "^(def" nil t))
      (when (not (re-search-forward "^ +\"" nil t))
        (error "badly formatted file, near %d" p0))
      (setq p1 (match-beginning 0))
      (replace-match "")
      (when (not (re-search-forward "\")?$" nil t))
        (error "badly formatted file, near %d" p0))
      (setq p2 (match-beginning 0))
      (replace-match "")
      (goto-char p1)
      (narrow-to-region p1 p2) ; because p2 moves with every replacement
      (while (re-search-forward "^" nil t)
        (replace-match ";;"))
      (widen)))
  ;; Comment-out def* and adjust pre-existing comments
  (dolist (repl '(("^;;; " ";;;; ")
                  ("^$"    ";;")
                  ("^(def" ";;; (def")))
    (goto-char (point-min))
    (while (re-search-forward (car repl) nil t)
      (replace-match (cadr repl))))
  ;; Remove everything else
  (goto-char (point-min))
  (delete-non-matching-lines  "^;" (point-min) (point-max))
  ;; Create org headings and remove extra blank lines
  (dolist (repl '(("^;;;;" "**")
                  ("^;;; (def[^ ]+" "***")
                  ("^;;;" "***")
                  ("^;;" " ")
                  ("^ +$" "")
                  ("\n\n+" "\n\n")))
    (goto-char (point-min))
    (while (re-search-forward (car repl) nil t)
      (replace-match (cadr repl))))
  ;; Create top heading
  (goto-char 1)
  (delete-char 1)
  ;; Ta-da!
  (org-mode))