unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
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


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