Re: Convert README.org to plain text README while installing package

[Philip Kaludercic]

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

>> From 9d973044a346860d3fc6164fe75ad8cd9721a595 Mon Sep 17 00:00:00 2001
>> From: Philip Kaludercic <philipk@posteo.net>
>> Date: Mon, 6 Jun 2022 12:34:40 +0200
>> Subject: [PATCH] Render Org documentation in a plain-text README-elpa file
>>
>> * elpa-admin.el (elpaa--make-one-tarball-1): Call elpaa--write-plain-readme.
>> (elpaa--write-plain-readme): Add new function.
>
> That looks OK, feel free to push that to `elpa-admin`.
> Comments:

The following should address most of your points, just one question,

>From c60903f5e916b22678c43c0fba0aa73a9e0bf471 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Mon, 6 Jun 2022 12:34:40 +0200
Subject: [PATCH] Render Org documentation in a plain-text README-elpa file

* elpa-admin.el (elpaa--make-one-tarball-1): Call elpaa--write-plain-readme.
(elpaa--write-plain-readme): Add new function.
(elpaa--html-make-pkg): Reuse the rendered plaintext from
`elpaa--write-plain-readme'.
---
 elpa-admin.el | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/elpa-admin.el b/elpa-admin.el
index 58c0ec2e0a..173d247e87 100644
--- a/elpa-admin.el
+++ b/elpa-admin.el
@@ -610,7 +610,8 @@ auxillary files unless TARBALL-ONLY is non-nil ."
               (lambda (file)
                 (string-match re file)
                 (cons (match-string 1 file) file))
-              (directory-files destdir nil re)))))
+              (directory-files destdir nil re))))
+          rendered)
      (when ldir
        (cl-pushnew (list (file-name-as-directory ldir) "") renames
                    :test #'equal))
@@ -621,6 +622,7 @@ auxillary files unless TARBALL-ONLY is non-nil ."
        (elpaa--make pkg-spec dir)
        (elpaa--build-Info pkg-spec dir destdir))
      (elpaa--write-pkg-file dir pkgname metadata revision)
+     (setq rendered (elpaa--write-plain-readme dir pkg-spec))
      ;; FIXME: Allow renaming files or selecting a subset of the files!
      (cl-assert (not (string-match "[][*\\|?]" pkgname)))
      (cl-assert (not (string-match "[][*\\|?]" vers)))
@@ -677,7 +679,7 @@ auxillary files unless TARBALL-ONLY is non-nil ."
            (elpaa--html-make-pkg pkgdesc pkg-spec
                                  `((,vers . ,(file-name-nondirectory tarball))
                                    . ,oldtarballs)
-                                 dir))))
+                                 dir rendered))))
      'new)))
 
 (defun elpaa--makeenv (version revision)
@@ -1162,6 +1164,22 @@ Rename DIR/ to PKG-VERS/, and return the descriptor."
      nil
      pkg-file)))
 
+(defun elpaa--write-plain-readme (pkg-dir pkg-spec)
+  "Render a plain text readme from PKG-SPEC in PKG-DIR.
+This is only done if necessary, that is if the readme contents
+are not already taken to be formatted in plain text or when the
+readme file has an unconventional name"
+  (let ((readme-file (elpaa--spec-get pkg-spec :readme))
+        (known-readme-names            ;see `package--get-description'
+         '("README-elpa" "README-elpa.md" "README" "README.rst" "README.org"))
+        (readme-content (elpaa--get-README pkg-spec pkg-dir)))
+    (if (or (not (eq (car readme-content) 'text/plain))
+            (not (member readme-file known-readme-names)))
+        (let ((rendered (elpaa--section-to-plain-text readme-content)))
+          (write-region rendered nil (expand-file-name "README-elpa" pkg-dir))
+          rendered)
+      readme-content)))
+
 (defun elpaa-batch-generate-description-file (&rest _)
   "(Re)build the <PKG>-pkg.el file for particular packages."
   (while command-line-args-left
@@ -1489,7 +1507,7 @@ arbitrary code."
          ))
       (insert "</dd>\n"))))
 
-(defun elpaa--html-make-pkg (pkg pkg-spec files srcdir)
+(defun elpaa--html-make-pkg (pkg pkg-spec files srcdir plain-readme)
   (let* ((name (symbol-name (car pkg)))
          (latest (package-version-join (aref (cdr pkg) 0)))
          (mainsrcfile (expand-file-name (elpaa--main-file pkg-spec) srcdir))
@@ -1542,7 +1560,7 @@ arbitrary code."
                        <pre>M-x <span class=\"kw\">package-install</span> RET 
<span class=\"kw\">%s</span> RET</pre>"
                       name))
       (let* ((readme-content (elpaa--get-README pkg-spec srcdir))
-             (readme-text (elpaa--section-to-plain-text readme-content))
+             (readme-text plain-readme)
              (readme-html (elpaa--section-to-html readme-content))
              (readme-output-filename (concat name "-readme.txt")))
         (write-region readme-text nil readme-output-filename)
-- 
2.36.1

> - you'd get more bonus points by arranging for the code
>   to (re)use the existing plain text (which is currently produced later
>   when (re)generating the HTML page, so it would take a fair bit of
>   code reorg to get that.  In the mean time, a FIXME comment seems
>   in order).
> - Your code may end up "rendering" a Markdown file for no obvious benefit
>   since the rendering is a no-op (tho I think this is very hypothetical
>   and likely can't happen because of other constraints).

Why should this be?  Both this and the previous iteration of the patch
check (eq (car readme-content) 'text/plain), and currently there is only
text/plain (which includes markdown) and text/org?

> - We might also add a `README-elpa` file when the readme file has a name
>   not recognized by `package--get-description`.