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

[Boruch Baum <boruch_baum@gmx.com>]

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



On 2020-10-18 22:40, Kévin Le Gouguec wrote:
> Boruch Baum <boruch_baum@gmx.com> writes:
>
> >> and I'm not exactly sure what using Org-mode buys us in this case.
> >
> > For starters: Navigation, expansion and collapse of sections.
>
> FWIW, outline-mode now features section-cycling commands (TAB and S-TAB)
> that are very similar to org-mode's (cf. bug#41130).

I'm OK with trying to use outline-minor-mode, but didn't see the
features yet in my version of emacs-snapshot. When will the patches for
41130 be committed and merged?

In the meantime, I've responded to the Stefan's (Kangas) feedback with
modified code, and started looking to a better alternative to posting
entire versions to the list. I see that I have an old old account on
savannah that I don't ever remember using, so I set up an ssh key and
have now been toying unsuccessfully to create a git repository there for
this feature (I'm now calling it org-el-file.el; not a great name yet,
but better than pack-doc).

Do I not have permissions to create a repo on my savannah account? If
not, how can one be created? I'd like three, called: 1) org-el-file
(this thread); 2) key-assist (bug #43709); 3) diredc (not yet shared,
but ready).

The attached version:

  + handles compressed source files

  + marks autoloaded functiions

  + identifies symbol definition

  + aligns symbols names (mostly)

  + labels colophon section

  + starts with commentary section open

  + improves definition regexp

  + attempts to perform substitute-command-keys

    + this turned out to be non-trivial, because the keybindings might
      not yet be defined and the keymap for the related mode might not
      yet be loaded.

    + the current attempt is an improvement, but I'm stuck on removing
      the leading back-slash.

It was very useful getting feedback because Stefan chose an el file with
what I'll call 'badly' (ie. unexpectedly) organized symbols, in the
sense that I was expecting all `defcustom's to be listed together in a
section beginning "^;;; Customization variables:", and so on for symbol
categories ";;; Global variables:", ";;; Buffer-local variables", ";;;
Internal functions:", ";;; Hook functions:", ";;; Interactive
functions:", etc. The new code no longer supposes such orderliness and
consequently retains function names that perform the symbol definitions.

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

[-- Attachment #2: org-el-file.el --]
[-- Type: text/plain, Size: 2946 bytes --]

;;; org-el-file.el --- Make org documetation from elisp source file -*- lexical-binding: t -*-

(defun org-el-file (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")
  (switch-to-buffer (get-buffer-create (concat (file-name-nondirectory file) ".org")))
  (insert-file-contents 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))
  ;; Move autoload declarations within their target's definition
  (goto-char (point-min))
  (while (re-search-forward "^;;;###autoload\n" nil t)
    (replace-match "")
    (re-search-forward "\n")
    (replace-match " [autoloaded]\n"))
  ;; substitute command keys
  (goto-char (point-min))
  (while (re-search-forward "\\\\\\[[^]]+]" nil t)
    (replace-match (substitute-command-keys (match-string 0))))
  ;; Create org headings and remove extra blank lines
  (dolist
      (repl '(("^;;;;" "**")
              ("^;;; (def\\([^ ]+\\) \\([^ \n]+\\)\\( ([^)]*)\\)?[^\n]*" "*** def\\1\t\\2\\3")
              ("^;;;" "***")
              ("^;;" " ")
              ("^ +$" "")
              ("\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 (point-min))
  (delete-char 1)
  ;; Create colophon heading
  (forward-line 1)
  (insert "** Colophon:\n")
  ;; Ta-da!
  (goto-char (point-min))
  (org-mode)
  (org-cycle) ; open up first-level headings
  (when (re-search-forward "^\*\* Commentary:" nil t)
    (goto-char (match-beginning 0))
    ;; open up content of anny commentary text
    (org-cycle)))

;; TODO:
;;
;; + The single \t inserted into "(def[^ ]+" headings in insufficient
;;   to vertically align symbol names when the "(def[^ ]+" is
;;   `define-derived-mode' or `define-obsolete-function-alias'