unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* ~Make emacs friendlier: package documentation [POC CODE INCLUDED]
@ 2020-10-15 19:09 Boruch Baum
  2020-10-15 19:24 ` Eli Zaretskii
  0 siblings, 1 reply; 31+ messages in thread
From: Boruch Baum @ 2020-10-15 19:09 UTC (permalink / raw)
  To: Emacs-Devel List

[-- 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))

^ permalink raw reply	[flat|nested] 31+ messages in thread

end of thread, other threads:[~2020-10-21 22:31 UTC | newest]

Thread overview: 31+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-10-15 19:09 ~Make emacs friendlier: package documentation [POC CODE INCLUDED] Boruch Baum
2020-10-15 19:24 ` Eli Zaretskii
2020-10-15 19:41   ` Boruch Baum
2020-10-16  6:39     ` Eli Zaretskii
2020-10-16  7:34       ` Boruch Baum
2020-10-16 10:20         ` Eli Zaretskii
2020-10-18  5:58           ` Boruch Baum
2020-10-18 14:53             ` Eli Zaretskii
2020-10-18 15:05               ` Boruch Baum
2020-10-18 15:12                 ` Eli Zaretskii
2020-10-18 15:28                   ` Boruch Baum
2020-10-18 16:00                     ` Eli Zaretskii
2020-10-18 16:29                       ` Boruch Baum
2020-10-18 17:05                         ` Eli Zaretskii
2020-10-18 13:11         ` Stefan Monnier
2020-10-18 14:43           ` Boruch Baum
2020-10-18 15:50             ` Stefan Kangas
2020-10-18 16:20               ` Boruch Baum
2020-10-18 17:13                 ` Stefan Kangas
2020-10-18 20:40                 ` Kévin Le Gouguec
2020-10-19  2:55                   ` Boruch Baum
2020-10-21  5:52                     ` Kévin Le Gouguec
2020-10-21  6:00                       ` Boruch Baum
2020-10-21 22:31                     ` Stefan Monnier
2020-10-18 15:58             ` Boruch Baum
2020-10-18 20:18           ` Stefan Monnier
2020-10-19  2:24             ` Eli Zaretskii
2020-10-19  2:59               ` Boruch Baum
2020-10-19  3:16                 ` Stefan Monnier
2020-10-20  5:11                   ` Richard Stallman
2020-10-20  5:51                     ` Boruch Baum

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).