From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Boruch Baum Newsgroups: gmane.emacs.devel Subject: ~Make emacs friendlier: package documentation [POC CODE INCLUDED] Date: Thu, 15 Oct 2020 15:09:29 -0400 Message-ID: <20201015190929.gdvx7j2yukcdcoaw@E15-2016.optimum.net> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="hzp6zcl554gbgf3d" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="38043"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: NeoMutt/20180716 To: Emacs-Devel List Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Oct 15 21:13:54 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kT8hF-0009n5-I7 for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Oct 2020 21:13:53 +0200 Original-Received: from localhost ([::1]:48746 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kT8hE-0006VO-Cu for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Oct 2020 15:13:52 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:48428) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kT8d6-00056O-Qp for emacs-devel@gnu.org; Thu, 15 Oct 2020 15:09:36 -0400 Original-Received: from mout.gmx.net ([212.227.17.21]:46219) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kT8d4-00022Z-Gj for emacs-devel@gnu.org; Thu, 15 Oct 2020 15:09:36 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1602788972; bh=Qf2aK5ZiltShrNnGuZp8LyjY4g6umuQEDWJxwEMp3w8=; h=X-UI-Sender-Class:Date:From:To:Subject; b=AcZhr+rpQNJaqWz2FdKjZVBF2epm3ouZWgf/jp6D5ub0FosA+F8qPeSb+LpkYmDia DEPaDD9P8Gn6JDQmSs0I2jyLqXrUk4Idr+c+hndFnYVnrbvSY0TSizIyRNFmtm99AI FAcxFsVkvn/rJFIC+69A8PlIMBeTT8NJSLtl8BdA= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from E15-2016.optimum.net ([72.89.170.172]) by mail.gmx.com (mrgmx105 [212.227.17.174]) with ESMTPSA (Nemesis) id 1MZkpb-1kzwQG44Qx-00Wkg3 for ; Thu, 15 Oct 2020 21:09:32 +0200 Content-Disposition: inline X-Provags-ID: V03:K1:M8LZMZBQnHNOB2XOcWdtmSg3ZKlL3eAJyvyvNgLdXnCx/WJy8rv Xh/GCsFbJw/nSr4ycRcysOIkKjyWe+E4zr3Q0bM8ocBRAb83qMA9+IC0V/TaYLeRLNpk1WI K1b6ClIjVPXoGHIg0ox0y1na1o/L2UA4hQZIngV1NGfIBh+yirrxdhn6Nk0qR43+GCjTD0O cfFu0ky03V7+WYEiCfRXw== X-UI-Out-Filterresults: notjunk:1;V03:K0:6YaKDV/istI=:0P7YP5lAfSujJ+Shqf5pug RSJSMzXJ5vQvwzlyrJG3r9mTC7uIsXB0UxJ/ko24qyCMCVj+FxsvK7B2fYl62K4AluFHouMWm QxUfKm2TthVUD+32CdTtTvn42iox7KNJbcS+lifkWy8Mqv5mg3pWHhX3f+c50MeFSi/vLGZUH gIZGle27FwC5TSvKOoHSBj7UTJF2I7064TpJKnMbwk2rZusxMoYin9jNPNUAxV8+rZ90Sq2Qg YteS+OaOWZd/u7KCUkB1rBuNn1Qt18U0TrYjuqUuBArFue7ThHqSdYm0f9jAEFt2aFhLMLUZs k48oYrqiFpTasAafHOcI3/21IkrdySGqYujeXiYkgj2JhRQbtDVtr7fIM+CNRjaLGqkJWMgY8 L0vY/UJ3whYiWwJnW3R/MHNkQhLYNvDxhB2R5EszeyxQMZ1IKg/YhDXXi65KEoJe3Xi9fetyr qsgA5aa8IUvkDN18bgEaBlpsZGsjtz81VKnLd+bAXQR4UlFCM8+ZwagxbCHDmqHThsIX1suCA 6ufx8OfRnA5iVMwCye2xggIudVSXqQ6c3Yv2izV8wM04Eq+QSXXLYjIASRd322eORTWqLrw/J XlBww5p+iIMPHW1d8kbUml5hYHOVy8nlQMMlDKtxa+Z5L2wpU2xwjUwiu+8ri4D3NY8se7Zdr bYh5vAdDcBV4PC77QlP1DXiP1Sys1t63m/J2IHyubYG9AaBc93b4KvHbHDywDgT5QVC3pU2aH GgXqoFPSRhmqSjCy59IzpIV/SuG7krnbcY5YlRaZDNFgkBpEQiKlw7yDialYEcVHI/Yl/mbY Received-SPF: pass client-ip=212.227.17.21; envelope-from=boruch_baum@gmx.com; helo=mout.gmx.net X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/15 14:54:02 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:257759 Archived-At: --hzp6zcl554gbgf3d Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 --hzp6zcl554gbgf3d Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="pack-doc.el" ;;; 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)) --hzp6zcl554gbgf3d--