From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Adam Porter Newsgroups: gmane.emacs.devel Subject: [ELPA/elpa-admin] Render README.org as ASCII with ox-ascii Date: Sun, 29 Aug 2021 17:52:42 -0500 Message-ID: <87h7f7zww5.fsf@alphapapa.net> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="36409"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Aug 30 00:54:01 2021 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 1mKTgd-0009Em-Aa for ged-emacs-devel@m.gmane-mx.org; Mon, 30 Aug 2021 00:53:59 +0200 Original-Received: from localhost ([::1]:46798 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mKTgc-0002sJ-CS for ged-emacs-devel@m.gmane-mx.org; Sun, 29 Aug 2021 18:53:58 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:51634) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mKTfh-0001es-Rd for emacs-devel@gnu.org; Sun, 29 Aug 2021 18:53:01 -0400 Original-Received: from ciao.gmane.io ([116.202.254.214]:50800) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mKTff-0001EV-RL for emacs-devel@gnu.org; Sun, 29 Aug 2021 18:53:01 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1mKTfW-0007rm-EZ for emacs-devel@gnu.org; Mon, 30 Aug 2021 00:52:50 +0200 X-Injected-Via-Gmane: http://gmane.org/ Received-SPF: pass client-ip=116.202.254.214; envelope-from=ged-emacs-devel@m.gmane-mx.org; helo=ciao.gmane.io X-Spam_score_int: -15 X-Spam_score: -1.6 X-Spam_bar: - X-Spam_report: (-1.6 / 5.0 requ) BAYES_00=-1.9, HEADER_FROM_DIFFERENT_DOMAINS=0.25, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no 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:273438 Archived-At: --=-=-= Content-Type: text/plain Hi Stefan, et al, Having added taxy.el to ELPA, I noticed that its README.org file isn't very readable on the ELPA site, because it's rendered as a raw file, including long lines that extend beyond the edge of the HTML PRE block, raw Org-syntax, etc. Thankfully, Org has an ASCII/UTF-8 export backend that cleanly renders Org to plain text. It only took a few lines of to make use of it. Please see the attached patches. (While I was at it, I took the liberty of adding a couple of docstrings and renaming a few variables to help me understand the code.) Please note, I haven't built the whole ELPA repo to test this change, but I tested the code on my taxy.el readme, and it returns a string like the old function did, so it "should work." :) In the long run, as the TODO in the commentary says, it would be good to render as HTML, but this is a big improvement for a very small change in the code, so a step in the right direction. Thanks, Adam --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-elpa-admin.el-elpaa-get-section-Add-docstring-rename.patch >From 85c9d3070c6d87695f57613ed51a43e7ebd5bafa Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Sun, 29 Aug 2021 17:35:59 -0500 Subject: [PATCH 1/2] * elpa-admin.el (elpaa--get-section): Add docstring, rename vars --- elpa-admin.el | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/elpa-admin.el b/elpa-admin.el index 4c84360..ac72f2f 100644 --- a/elpa-admin.el +++ b/elpa-admin.el @@ -1167,25 +1167,28 @@ Rename DIR/ to PKG-VERS/, and return the descriptor." (insert-file-contents mainsrcfile) (lm-header prop)))))) -(defun elpaa--get-section (hsection fsection srcdir pkg-spec) - (when (consp fsection) - (while (cdr-safe fsection) - (setq fsection - (if (file-readable-p (expand-file-name (car fsection) srcdir)) - (car fsection) - (cdr fsection)))) - (when (consp fsection) (setq fsection (car fsection)))) +(defun elpaa--get-section (header file srcdir pkg-spec) + "Return specified section as a string from SRCDIR for PKG-SPEC. +If FILE is readable in SRCDIR, return its contents. Otherwise +return section under HEADER in package's main file." + (when (consp file) + (while (cdr-safe file) + (setq file + (if (file-readable-p (expand-file-name (car file) srcdir)) + (car file) + (cdr file)))) + (when (consp file) (setq file (car file)))) (cond - ((file-readable-p (expand-file-name fsection srcdir)) + ((file-readable-p (expand-file-name file srcdir)) (with-temp-buffer - (insert-file-contents (expand-file-name fsection srcdir)) + (insert-file-contents (expand-file-name file srcdir)) (buffer-string))) ((file-readable-p (expand-file-name (elpaa--main-file pkg-spec) srcdir)) (with-temp-buffer (insert-file-contents (expand-file-name (elpaa--main-file pkg-spec) srcdir)) - (emacs-lisp-mode) ;lm-section-start needs the outline-mode setting. - (let ((start (lm-section-start hsection))) + (emacs-lisp-mode) ;lm-section-start needs the outline-mode setting. + (let ((start (lm-section-start header))) (when start ;; FIXME: Emacs<28 had a bug in `lm-section-end', so cook up ;; our own ad-hoc replacement. -- 2.7.4 --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0002-elpa-admin.el-elpaa-get-README-Docstring-export-Org-.patch >From 7e34b7fb6396513560ea7e2994ee73d3e2a9820a Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Sun, 29 Aug 2021 17:45:22 -0500 Subject: [PATCH 2/2] * elpa-admin.el (elpaa--get-README): Docstring, export Org readmes Exports "README.org" files using ox-ascii.el, which is more readable on the ELPA Web site. --- elpa-admin.el | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/elpa-admin.el b/elpa-admin.el index ac72f2f..dfe56f0 100644 --- a/elpa-admin.el +++ b/elpa-admin.el @@ -1210,14 +1210,27 @@ return section under HEADER in package's main file." (buffer-string))))))) (defun elpaa--get-README (pkg-spec dir) - (elpaa--get-section - "Commentary" (elpaa--spec-get pkg-spec :readme - '("README" "README.rst" - ;; Most README.md files seem to be currently - ;; worse than the Commentary: section :-( - ;; "README.md" - "README.org")) - dir pkg-spec)) + "Return readme for PKG-SPEC in DIR as a string. +If readme is an Org file, render it to plain-text using Org +Export." + (let ((readme-file + (elpaa--spec-get pkg-spec :readme + '("README" "README.rst" + ;; Most README.md files seem to be currently + ;; worse than the Commentary: section :-( + ;; "README.md" + "README.org")))) + (pcase readme-file + ("README.org" + (require 'org) + (require 'ox) + (with-temp-buffer + (insert-file-contents readme-file) + (org-export-as 'ascii nil nil nil (:ascii-charset utf-8 :with-broken-links t))) + ) + (_ (elpaa--get-section + "Commentary" readme-file + dir pkg-spec))))) (defun elpaa--get-NEWS (pkg-spec dir) (let ((text -- 2.7.4 --=-=-=--