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: Re: ~Make emacs friendlier: package documentation [POC CODE INCLUDED] Date: Sun, 18 Oct 2020 22:55:07 -0400 Message-ID: <20201019025507.5s5yq2wnny7dttqm@E15-2016.optimum.net> References: <20201015190929.gdvx7j2yukcdcoaw@E15-2016.optimum.net> <83pn5jwav0.fsf@gnu.org> <20201015194132.jdn3e2v62vfvh7ju@E15-2016.optimum.net> <83imbawu6y.fsf@gnu.org> <20201016073432.4bmahi4jna2xxayl@E15-2016.optimum.net> <20201018144345.wgrbsivvzuuohbj5@E15-2016.optimum.net> <20201018162030.h7s4tqch3sprssxu@E15-2016.optimum.net> <87a6wjnu8f.fsf@gmail.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="5rtup2vfnsr7wvae" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="781"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: NeoMutt/20180716 Cc: Eli Zaretskii , emacs-devel@gnu.org, Stefan Kangas , Stefan Monnier To: =?utf-8?B?S8Opdmlu?= Le Gouguec Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Oct 19 04:58:30 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 1kULNV-000Ae2-1A for ged-emacs-devel@m.gmane-mx.org; Mon, 19 Oct 2020 04:58:29 +0200 Original-Received: from localhost ([::1]:42120 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kULNT-0000ZN-SZ for ged-emacs-devel@m.gmane-mx.org; Sun, 18 Oct 2020 22:58:28 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33470) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kULKS-0008Mo-RP for emacs-devel@gnu.org; Sun, 18 Oct 2020 22:55:20 -0400 Original-Received: from mout.gmx.net ([212.227.17.21]:36027) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kULKQ-0004ao-6o; Sun, 18 Oct 2020 22:55:20 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1603076111; bh=Nj9mE66V+TAG9jCkXzhSYPqqgdo63TvxPfcA4qq192Y=; h=X-UI-Sender-Class:Date:From:To:Cc:Subject:References:In-Reply-To; b=JS4lngM9FIVVPo7gfnX4MUI96rqE3rbQzPiOihX0//ybobrwhylRTVxBDmG36zO0N VfOk1SmtrCwBLND4VIahvj94+xBbxvBxyX1zyr5fVMqz3KiZlQ6V+9gOk0umETTDJ2 g2974ktiDSK4rgrmi+Lmf/FiCOpU1xyY2RCgtzsE= 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 1N4zAy-1kKgo637n2-010qMO; Mon, 19 Oct 2020 04:55:11 +0200 Content-Disposition: inline In-Reply-To: <87a6wjnu8f.fsf@gmail.com> X-Provags-ID: V03:K1:ExIOkqdJv4Ewr03vh19tVkMmg55GTPXSznzEpWxiXmgyijINwaA /caOBd1AXOKzXJmu+AOrFfn8yPWwiCvEKe2sO7gLxIxvq6Sg1xXCZCBJ5ih2MslRYJMkVr/ DIhNCgA+6LSnJnYCYQG08EbAUPoK5GZOOvqBA1SOvKo+l7HHAOvKwO1o+6PPLxnt7DWY53A 1RzPfjsyZ7hFIDVa0g3yQ== X-UI-Out-Filterresults: notjunk:1;V03:K0:Rq9hzRmC8AU=:EoT8yTz9mOz5nL1udwjXfI tpsTUNZzL0nG+bE+8CmRNKM2wolXezvPTVLUZ7gEDpiX87XjFediRvR7D1POp1wZlxEUlOvAd qgWqxxSAMYC9bXlfiBTGv/+3+/1NuHKwxBOCU8rrAD/r13t4ipoSwsRDZnIYXJR7ep20Nm73t ZUaWGd4322nHGXbrH+i1UpRHnPShQycnmdkCmuKJXmcIdih56R3op48QkJQTvnLz3LlzN4S3P y1/RCSteHHJ0QA74A0bfAcwu1Ne+3VEF2ElrnSJRGEu1ji2ZCP5p6oT/uA3EBFiaK2D/YGNPi /jT6ZJfCCpKMTPc5+VKARsPmor6tqiPrnXH4NhxZ0HgtXGerava0VKe+L9jYWBNSlyb3UZO9g 2s+VHEhzgDfAgjFTBD1sjfyZJ70deDczijnakfeubY4jUccLVOmHMm9ER46SN300hXECuiqp9 L8jNlbidD0wxKhzDcDqqVtGm2E4vb2glTvl6wDNlpYbWQ6C26cEgQTy/evP3R4828lzkfTivJ NelCvA72tl8LxUZ2paghikkaMi0Yi5+WjUYoa3wsJV2f3Kdh+uL3iHdxsV67oMwKYFujB4+3B 305h2w6qnJbgBOuAOgyEWtutLJ9O9zb0F8uhlY91giK4tQbFP/5+ZhqWxUIKa+K1Ji4vD9bBh c0/haKNMCH5SvmFRoc8Hfy6h/4EUJxgjfjHkAQJwau6owpMkJOTpmxxNluqd3o0Z1J14sjefg Gv7rZPSfPPaWZLRLixVINNydDUGsp4J5iiFKf01XtriAuqbKzEoMwIVoZYCvfwA+mbiGDitl 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/18 22:55:15 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:258079 Archived-At: --5rtup2vfnsr7wvae Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On 2020-10-18 22:40, K=E9vin Le Gouguec wrote: > Boruch Baum 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. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0 --5rtup2vfnsr7wvae Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="org-el-file.el" ;;; 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' --5rtup2vfnsr7wvae--