Re: [ELPA/elpa-admin] Render README.org as HTML with ox-html

[Adam Porter <adam@alphapapa.net>]

[-- Attachment #1: Type: text/plain, Size: 463 bytes --]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I hope we can generate HTML rather than "clean text", but in the mean
> time, clean text is better than raw source, so: thanks.

Building on the previous patches, here's my attempt at exporting Org to
HTML.  I don't know if it accounts for everything that should be
accounted for (there's much I don't understand about the build process),
so it might need a few changes, but I think it should basically work.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-elpa-admin.el-Export-Org-readmes-to-readable-text.patch --]
[-- Type: text/x-diff, Size: 2600 bytes --]

From d54be5068756e2a4845e866332c82508512e3145 Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sun, 29 Aug 2021 17:45:22 -0500
Subject: [PATCH 1/2] * elpa-admin.el: Export Org readmes to readable text

Exports "README.org" files using ox-ascii.el, which is more readable
on the ELPA Web site.

(elpaa--export-org): New function.
(elpaa--get-README): Add docstring, call new function.
---
 elpa-admin.el | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/elpa-admin.el b/elpa-admin.el
index ac72f2f..3682bec 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1210,14 +1210,36 @@ 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"
+       (elpaa--export-org readme-file 'ascii '(:ascii-charset utf-8 :with-broken-links t)))
+      (_ (elpaa--get-section
+          "Commentary" readme-file
+          dir pkg-spec)))))
+
+(defun elpaa--export-org (file backend &optional ext-plist)
+  "Return Org FILE as an exported string.
+BACKEND and EXT-PLIST are passed to `org-export-as', which see.
+Uses `elpaa--call-sandboxed', since exporting with Org may run
+arbitrary code."
+  (with-temp-buffer
+    (unless (zerop (elpaa--call-sandboxed
+                    t "emacs" "--batch" "-l" "ox-ascii"
+                    file
+                    "--eval" (format "(message \"%%s\" (org-export-as '%s nil nil nil '%S))"
+                                     backend ext-plist)))
+      (error "Unable to export Org file: %S" file))
+    (buffer-string)))
 
 (defun elpaa--get-NEWS (pkg-spec dir)
   (let ((text
-- 
2.7.4


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-elpa-admin.el-Export-Org-to-HTML-content-and-files.patch --]
[-- Type: text/x-diff, Size: 4303 bytes --]

From 4c7d4b5c1de11f80f411f7f2e7e423a0b893f7a5 Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sun, 29 Aug 2021 21:03:37 -0500
Subject: [PATCH 2/2] * elpa-admin.el: Export Org to HTML content and files

(elpaa--export-org): Export to specified backend, optionally with
body-only.

(elpaa--get-README): Use elpaa--export-org to export HTML.

(elpaa--html-make-pkg): Export Org readmes to HTML, and other readme
formats to plain text.
---
 elpa-admin.el | 46 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/elpa-admin.el b/elpa-admin.el
index 3682bec..791bc67 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -1222,22 +1222,27 @@ Export."
                             "README.org"))))
     (pcase readme-file
       ("README.org"
-       (elpaa--export-org readme-file 'ascii '(:ascii-charset utf-8 :with-broken-links t)))
+       (elpaa--export-org
+        readme-file 'html
+        :body-only t :ext-plist '(:ascii-charset utf-8 :with-broken-links t)))
       (_ (elpaa--get-section
           "Commentary" readme-file
           dir pkg-spec)))))
 
-(defun elpaa--export-org (file backend &optional ext-plist)
+(cl-defun elpaa--export-org (file backend &key body-only ext-plist)
   "Return Org FILE as an exported string.
 BACKEND and EXT-PLIST are passed to `org-export-as', which see.
 Uses `elpaa--call-sandboxed', since exporting with Org may run
 arbitrary code."
+  (cl-check-type backend symbol)
+  (cl-assert (memq body-only '(nil t)) t
+             "BODY-ONLY may only be nil or t")
   (with-temp-buffer
     (unless (zerop (elpaa--call-sandboxed
-                    t "emacs" "--batch" "-l" "ox-ascii"
+                    t "emacs" "--batch" "-l" (format "ox-%s" backend)
                     file
-                    "--eval" (format "(message \"%%s\" (org-export-as '%s nil nil nil '%S))"
-                                     backend ext-plist)))
+                    "--eval" (format "(message \"%%s\" (org-export-as '%s nil nil %S '%S))"
+                                     backend body-only ext-plist)))
       (error "Unable to export Org file: %S" file))
     (buffer-string)))
 
@@ -1335,10 +1340,33 @@ arbitrary code."
       (insert (format "<p>To install this package, run in Emacs:</p>
                        <pre>M-x <span class=\"kw\">package-install</span> RET <span class=\"kw\">%s</span> RET</pre>"
                       name))
-      (let ((rm (elpaa--get-README pkg-spec srcdir)))
-        (when rm
-          (write-region rm nil (concat name "-readme.txt"))
-          (insert "<h2>Full description</h2><pre>\n" (elpaa--html-quote rm)
+      (let ((readme-file-name
+             (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")))
+            output-filename readme-content page-content)
+        (pcase readme-file-name
+          ("README.org"
+           (setf output-filename (concat name "-readme.html")
+                 readme-content (elpaa--export-org
+                                 readme-file-name 'html
+                                 :ext-plist '(:with-broken-links t))
+                 page-content (elpaa--export-org
+                               readme-file-name 'html
+                               :body-only t :ext-plist '(:with-broken-links t))))
+          (_ ;; Non-Org readme.
+           (setf output-filename (concat name "-readme.txt")
+                 readme-content (elpaa--get-section
+                                 "Commentary" readme-file-name
+                                 dir pkg-spec)
+                 page-content (when readme-content
+                                (elpaa--html-quote readme-content)))))
+        (when readme-content
+          (write-region readme-content nil output-filename)
+          (insert "<h2>Full description</h2><pre>\n" page-content
                   "\n</pre>\n")))
       ;; (message "latest=%S; files=%S" latest files)
       (unless (< (length files) (if (zerop (length latest)) 1 2))
-- 
2.7.4