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

[Stefan Monnier]

Hi Adam,

> Apologies for not noticing that.  I've changed it to write to and read
> from a temp file.

[ No need for apologies, really.  ]

>> [ Also, I haven't yet tried the code on elpa.gnu.org but that's still
>>   running Emacs-26, so there might be compatibility issues for Org.
>>   It should be upgraded to Emacs-27 "real soon now", tho, so maybe it's
>>   not worth the trouble.  ]
>
> Sometimes Org changes can be annoying to compensate for.  Hopefully the
> org-export infrastructure won't change too much.  I tested this on Emacs
> 26.3 and it seems to work.

Great, thanks.

>>> +                 page-content (when readme-content
>>> +                                (concat "<pre>\n"
>>> +                                        (elpaa--html-quote readme-content)
>>> +                                        "\n</pre>\n")))))
>>> +        (when readme-content
>>> +          (write-region readme-content nil output-filename)
>>> +          (insert "<h2>Full description</h2>\n" page-content)))
>>>        ;; (message "latest=%S; files=%S" latest files)
>>>        (unless (< (length files) (if (zerop (length latest)) 1 2))
>>>          (insert (format "<h2>Old versions</h2><table>\n"))
>>
>> Hmm... this function is already too long, so please move this to
>> a separate function.
> I don't disagree, but I'm not sure what you have in mind.

I didn't have anything specific in mind, sorry.

> Since this code also writes to the temp buffer made by the containing
> function, `elpaa--html-make-pkg', it would seem awkward to me to move
> that code as-is to another function that would both write to a file
> and insert into the current buffer, but maybe that's not what you
> meant, or maybe I just haven't learned your preferred style.  :)

Hmm... so now I really have to read and understand your code, eh?  ;-)

OK, I see what you mean now.  Indeed, we need to get both
a plaintext version (for `<pkg>-readme.txt`) and an HTML version (to
insert into the temp buffer).  See below.

> I guess you forgot to attach the patch, but maybe the one I'm attaching
> fixes that problem, anyway.  :)

Thanks, indeed.

>> One other thing.  I think it would make sense to make
>> `elpaa--get-section` return a pair of the string content and some "type"
>> (org, markdown, plaintext, ...) so as to automatically use your HTML
>> renderer for any .org file we find instead of only when the org file is
>> specified explicitly via `:readme "README.org"`.  WDYT?
>
> I'm not sure what you have in mind.  I felt confused by that function's
> signature and it's "overloading", shall we say, in that it may return a
> file's contents or a section's contents.  In the patched version of
> `elpaa--html-make-pkg', I tried to label the logic to make it easier for
> me to follow.

We want to support packages where the "readme" is either inside a file
or inside a `Commentary:` section (and same thing for the news which can
be in a file or in the `News:` section), which is why we have this
function with this kind of "overloading".

Currently regardless of its origin (file or section) the content is
taken to be "plain text".  I'd like to extend this to allow not just
`foo.org` files (as your patch does) but also allow the use of Org
format in sections (maybe by calling it `Commentary.org:`).  It's not
necessary to provide this support right now, but we can keep
`elpaa--get-section` more or less as it is now, just extend it to return
(TYPE . CONTENT).  Currently the TYPE would be `text/plain` in all cases
except when the content comes from a file and the file's name ends in
`.org`.

And we'd add 2 new functions: one that converts (TYPE . CONTENT) to
plain text (i.e. trivial when the type is `text/plain`) and
another that converts it to HTML (using `elpaa--html-quote` for the
`text/plain` case).

Does it make more sense?


        Stefan