From: Adam Porter <adam@alphapapa.net>
To: emacs-devel@gnu.org
Subject: [ELPA/elpa-admin] Render README.org as ASCII with ox-ascii
Date: Sun, 29 Aug 2021 17:52:42 -0500 [thread overview]
Message-ID: <87h7f7zww5.fsf@alphapapa.net> (raw)
[-- Attachment #1: Type: text/plain, Size: 955 bytes --]
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
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-elpa-admin.el-elpaa-get-section-Add-docstring-rename.patch --]
[-- Type: text/x-diff, Size: 2331 bytes --]
From 85c9d3070c6d87695f57613ed51a43e7ebd5bafa Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
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
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-elpa-admin.el-elpaa-get-README-Docstring-export-Org-.patch --]
[-- Type: text/x-diff, Size: 2009 bytes --]
From 7e34b7fb6396513560ea7e2994ee73d3e2a9820a Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
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
next reply other threads:[~2021-08-29 22:52 UTC|newest]
Thread overview: 29+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-08-29 22:52 Adam Porter [this message]
2021-08-29 23:28 ` [ELPA/elpa-admin] Render README.org as ASCII with ox-ascii Adam Porter
2021-08-29 23:38 ` Clément Pit-Claudel
2021-08-30 0:01 ` Adam Porter
2021-08-30 1:49 ` Clément Pit-Claudel
2021-08-30 2:15 ` Adam Porter
2021-08-30 0:48 ` Stefan Monnier
2021-08-30 1:29 ` Adam Porter
2021-08-30 2:13 ` [ELPA/elpa-admin] Render README.org as HTML with ox-html Adam Porter
2021-09-03 2:01 ` Adam Porter
2021-09-07 3:31 ` Stefan Monnier
2021-09-07 8:12 ` Philip Kaludercic
2021-09-07 10:26 ` Adam Porter
2021-09-10 20:58 ` Stefan Monnier
2021-09-12 13:03 ` Adam Porter
2021-09-20 4:29 ` Stefan Monnier
2021-09-20 6:41 ` Stefan Kangas
2021-09-20 13:40 ` Basil L. Contovounesios
2021-09-20 19:57 ` Adam Porter
2021-09-20 23:26 ` Adam Porter
2021-10-09 15:08 ` Stefan Monnier
2021-10-09 16:39 ` Eric Abrahamsen
2021-10-10 3:37 ` Stefan Monnier
2021-10-10 3:54 ` Corwin Brust
2021-10-10 13:27 ` Stefan Monnier
2021-10-10 4:32 ` Eric Abrahamsen
2021-10-10 14:50 ` Adam Porter
2021-10-10 15:30 ` Stefan Monnier
2021-08-30 17:49 ` [ELPA/elpa-admin] Render README.org as ASCII with ox-ascii Philip Kaludercic
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87h7f7zww5.fsf@alphapapa.net \
--to=adam@alphapapa.net \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).