[ELPA] :doc with "README.org" doesn't rename exported texi file correctly

[ELPA] :doc with "README.org" doesn't rename exported texi file correctly

[Adam Porter]

Hi Stefan, Philip, et al,

I noticed that, even though the `ement' recipe in `elpa-packages' has 
the same :doc setting as some other packages:

   ("ement" :url "https://github.com/alphapapa/ement.el.git"
     :doc "README.org"
     :auto-sync t)

...the Info manual generated from its readme is not available for 
viewing in Emacs after the package is installed.  To solve that, I had 
to add this line to the readme (learning from other packages in ELPA):

   #+EXPORT_FILE_NAME: ement.texi

It would seem like this file naming ought to be handled automatically by 
the build scripts.  Or, at least, it should be documented that this is 
required, otherwise package authors are left to trial-and-error and 
releasing new versions until it works.  :)

What do you think?

Thanks,
Adam

Re: [ELPA] :doc with "README.org" doesn't rename exported texi file correctly

[Stefan Monnier]

Adam Porter [2022-09-22 10:16:24] wrote:
> I noticed that, even though the `ement' recipe in `elpa-packages' has the
> same :doc setting as some other packages:
>
>   ("ement" :url "https://github.com/alphapapa/ement.el.git"
>     :doc "README.org"
>     :auto-sync t)
>
> ...the Info manual generated from its readme is not available for viewing in
>  Emacs after the package is installed.  To solve that, I had to add this
> line to the readme (learning from other packages in ELPA):
>
>   #+EXPORT_FILE_NAME: ement.texi

Hmm... I must say that I don't know why that is nor do I know at which
level it fails (whether it's in the .org => .texi or .texi => .info or
in the generation of the `dir` file, or yet elsewhere).

The fact that the above line seems to fix it suggests that the problem
is in the generation of the `.texi`.  `elpa-admin.el` uses the following
code for that:

      (with-temp-buffer
        (elpaa--call-sandboxed
         t "emacs" "--batch" "-l" "ox-texinfo"
         ;; When building :core packages, don't follow the symlink,
         ;; otherwise Org will want to export into the Emacs tree!
         "--eval" "(setq vc-follow-symlinks nil)"
         docfile
         "--eval" "(setq org-babel-confirm-evaluate-answer-no t)"
         "--eval" "(message \"ELPATEXI=%s\" (org-texinfo-export-to-texinfo))")
        (message "%s" (buffer-string))
        (goto-char (point-max))
        (when (re-search-backward "ELPATEXI=\\(.*\\)\n?" nil t)
          (setq docfile (concat (file-name-directory docfile)
                                (match-string 1)))
          (push docfile tmpfiles)
          (elpaa--temp-file docfile)))

IOW the ELisp code doesn't know before hand which will be the name of
the generated file and uses the `(message \"ELPATEXI=%s\"` trick to
output to stdout the name of the file that Org chose for its
output file.

Which makes me think it would work without an explicit
`EXPORT_FILE_NAME`, but my knowledge of Org is much too limited to
actually know it to be the case.

If someone wants to investigate, the following steps should be able to
reproduce the build:

    git clone --single-branch git://git.sv.gnu.org/emacs/elpa.git
    cd elpa
    make
    make packages/org
    make build/org

Where the last `make` is the one that matters to build the tarball
that's placed in `archive-devel/org-<version>.tar` (and if the file
already exists, nothing is done).


        Stefan