[Feature]: Install Info files from README.org

[progfolio]

Feature Description

Several projects use org export to generate an Info file for their package.
It would be nice to detect this case and generate the Info file as part of the standard build steps.

Originally requested here:

#300 (comment)

Confirmation

• The feature I'm proposing does not already exist in Elpaca

[progfolio]

Implemented as an optional build step for now:

Test Case

How to run this test?

(elpaca-test
  :early-init (setq elpaca-menu-functions '(elpaca-menu-declarations))
  :init (push (elpaca-defscript +elpaca-readme-to-info (:type elisp :dir repo)
                (when (file-exists-p "./README.org")
                  (with-temp-buffer
                    (insert-file-contents (expand-file-name "./README.org"))
                    (goto-char (point-min))
                    (when (re-search-forward "texinfo_filename:" nil t)
                      (require 'ox-texinfo)
                      (org-texinfo-export-to-info)))))
              (cdr (nthcdr (cl-position 'elpaca--check-version elpaca-build-steps)
                           elpaca-build-steps)))
  (elpaca (denote :repo ("https://github.com/protesilaos/denote" . "denote") :wait t))
  (info "Denote")
  (princ (buffer-substring-no-properties (point-min) (point-max))))

Host Env

elpaca	09ae3a4 HEAD -> feat/refactor, origin/feat/refactor
installer	0.11
emacs	GNU Emacs 31.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.51, cairo version 1.18.4) of 2025-11-08
git	git version 2.51.2

Output

  INFO     Scraping 15 files for loaddefs... 
  INFO     Scraping 15 files for loaddefs...done
  GEN      ../elpaca-autoloads.el
Cloning into '/tmp/elpaca.Rp3KAR/elpaca/repos/elpaca'...
Your branch is up to date with 'origin/master'.
Checking /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-info.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-log.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-manager.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-menu-elpa.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-menu-melpa.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-menu-org.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-process.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-test.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca-ui.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/elpaca.el...
Checking /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/doc...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/doc/early-init.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/doc/init.el...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/doc/installer.el...
Checking /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/extensions...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/extensions/elpaca-use-package.el...
Checking /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/images...
Checking /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/test...
Compiling /tmp/elpaca.Rp3KAR/elpaca/repos/elpaca/test/elpaca-tests.el...
Done (Total of 12 files compiled, 3 skipped in 4 directories)

File: denote.info,  Node: Top,  Next: Installation,  Up: (dir)

denote: Simple notes with an efficient file-naming scheme
*********************************************************

Copyright (C) 2022-2025 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover Texts
     being “A GNU Manual,” and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     “GNU Free Documentation License.”

     (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
     modify this GNU manual.”

   This manual, written by Protesilaos Stavrou, describes the
customization options for the Emacs package called ‘denote’ (or
‘denote.el’), and provides every other piece of information pertinent to
it.

   The documentation furnished herein corresponds to stable version
4.1.0, released on 2025-10-17.  Any reference to a newer feature which
does not yet form part of the latest tagged commit, is explicitly marked
as such.

   Current development target is 4.2.0-dev.

   • Package name (GNU ELPA): ‘denote’
   • Official manual: <https://protesilaos.com/emacs/denote>
   • Change log: <https://protesilaos.com/emacs/denote-changelog>
   • Git repositories:
        • GitHub: <https://github.com/protesilaos/denote>
        • GitLab: <https://gitlab.com/protesilaos/denote>
   • Video demo:
     <https://protesilaos.com/codelog/2022-06-18-denote-demo/>
   • Backronyms: Denote Everything Neatly; Omit The Excesses.  Don't
     Ever Note Only The Epiphenomenal.

   If you are viewing the README.org version of this file, please note
that the GNU ELPA machinery automatically generates an Info manual out
of it.

* Menu:

* Installation::
* Sample configuration::
* Getting started with Denote::
* Overview::
* Points of entry::
* Renaming files::
* The file-naming scheme::
* Front matter::
* Linking notes::
* Choose which commands to prompt for::
* Fontification in Dired::
* Set the prefix of all Denote buffers::
* Automatically rename Denote file buffers::
* Use Org dynamic blocks::
* Display filtered and sorted files with denote-sort-dired or denote-dired::
* Use denote-grep to search inside files::
* Interact with the links buffer::
* Minibuffer histories::
* Packages that build on Denote::
* Extending Denote::
* For developers or advanced users::
* Troubleshoot Denote in a pristine environment::
* Contributing::
* Publications about Denote::
* Alternatives to Denote::
* Frequently Asked Questions::
* Acknowledgements::
* GNU Free Documentation License::
* Indices::

-- The Detailed Node Listing --

Installation

* GNU ELPA package::
* Manual installation::

Sample configuration

* Get started with this sample configuration::
* More comprehensive sample configuration::

Points of entry

* Standard note creation::
* Create note using Org capture::
* Create note with specific prompts using Org capture::
* Create note with specific values using Org capture::
* Create a note with the region's contents::
* Open an existing note or create it if missing::
* Maintain separate directory silos for notes::
* Exclude certain files from file prompts::
* Exclude certain directories from all operations::
* Exclude certain keywords from being inferred::
* Create a controlled vocabulary for keywords::
* Use Denote commands from the menu bar or context menu::

Standard note creation

* The denote-directory option::
* The denote-prompts option::
* The denote-history-completion-in-prompts option::
* The denote-templates option::
* Convenience commands for note creation::
* The denote-save-buffers option::
* The denote-kill-buffers option::
* The denote-date-prompt-use-org-read-date option::

Create a note with the region's contents

* A custom denote-region that references the source::

Maintain separate directory silos for notes

* Make Org export work with silos::

Renaming files

* Rename a single file::
* Rename a single file based on its front matter::
* Rename multiple files interactively::
* Rename multiple files at once by asking only for keywords::
* Rename multiple files based on their front matter::
* Rename a file by changing only its file type::
* Rename a file by adding or removing a title interactively::
* Rename a file by adding or removing keywords interactively::
* Rename a file by adding or removing a signature interactively::
* Find duplicate identifiers and put them in a Dired buffer::
* Faces used by rename commands::

Rename a single file

* The denote-rename-confirmations option::

The file-naming scheme

* Change the order of file name components::
* Sluggification of file name components::
* User-defined sluggification of file name components::
* Features of the file-naming scheme for searching or filtering::
* Define a completely custom identifier scheme::

Change the order of file name components

* Retroactively reorder the components of Denote file names::

User-defined sluggification of file name components

* Custom sluggification to remove non-ASCII characters::

Define a completely custom identifier scheme

* A custom identifier that is a simple incrementing number scheme::
* A custom identifier that is a simple string given at the prompt each time::
* A custom identifier to include the day of the week as a capital letter::
* A custom identifier to encode publisher data::

Front matter

* Change the front matter format::
* Regenerate front matter::

Linking notes

* Add a single direct link using a file name prompt::
* Add a direct link to a file whose contents include the given query::
* Add a query link::
* Insert links to all files matching a query in their file name::
* Insert links to all files matching a query in their contents::
* The denote-open-link-function user option::
* The denote-org-store-link-to-heading user option::
* Adding direct links to files matching contents::
* Insert links from marked files in Dired::
* Link to an existing note or create a new one::
* The backlinks' buffer::
* Writing metanotes::
* Visiting linked files via the minibuffer::
* Fontify links in non-Org buffers::
* The denote-link-description-format to format link descriptions::

Automatically rename Denote file buffers

* The denote-rename-buffer-format option::

Display filtered and sorted files with ‘denote-sort-dired’ or ‘denote-dired’

* Configure what extra prompts denote-sort-dired issues::
* Define a sorting function per component::

Define a sorting function per component

* Sort signatures that include Luhmann-style sequences::

Interact with the links buffer

* Control the default sort of a query buffer::

Packages that build on Denote

* Use the consult-denote package for enhanced minibuffer interactions::
* Sequence notes::
* Use the denote-markdown package to better integrate Markdown with Denote::
* Use the ‘denote-journal’ package which was formerly ‘denote-journal-extras.el’: Use the denote-journal package which was formerly denote-journal-extrasel.
* Use the ‘denote-silo’ package which formerly was ‘denote-silo-extras.el’: Use the denote-silo package which formerly was denote-silo-extrasel.
* Use the denote-search package as a search interface::
* Use the denote-explore package to explore your notes::
* Use the citar-denote package for bibliography notes::
* Use the consult-notes package::
* Use the denote-menu package::
* Use the denote-zettel-interface package::

Extending Denote

* Access the data of the latest note::
* Create a new note in any directory::
* Find empty notes and put them in a Dired buffer::
* Automatically rename the note after saving it::
* Narrow the list of files in Dired::
* Use dired-virtual-mode for arbitrary file listings::
* Use Embark to collect minibuffer candidates::
* Search file contents::
* Bookmark the directory with the notes::
* Treat your notes as a project::
* Use the tree-based file prompt for select commands::
* Rename files with Denote in the Image Dired thumbnails buffer::
* Rename files with Denote using dired-preview::
* Avoid duplicate identifiers when exporting Denote notes::
* Set up your workflow for daily or weekly meeting notes::

Avoid duplicate identifiers when exporting Denote notes

* Export Denote notes with Org Mode::
* Export Denote notes with Markdown::

For developers or advanced users

* Common building blocks for developers or advanced users::
* Predefined note values for developers or advanced users::
* File path interface for developers or advanced users::
* Data retrieval interface for developers or advanced users::
* Prompt interface for developers or advanced users::
* Front matter interface for developers or advanced users::
* Link interface for developers or advanced users::
* Xref interface for developers or advanced users::
* Renaming files interface for developers or advanced users::

Contributing

* Wishlist of what we can do to extend Denote::

Alternatives to Denote

* Alternative implementations and further reading::

Frequently Asked Questions

* Why develop Denote when PACKAGE already exists?::
* Why not rely exclusively on Org?::
* Why care about Unix tools when you use Emacs?::
* Why many small files instead of few large ones?::
* Does Denote perform well at scale?::
* I add TODOs to my notes; will many files slow down the Org agenda?::
* I want to sort by last modified in Dired, why won't Denote let me?: I want to sort by last modified in Dired why won't Denote let me?.
* How do you handle the last modified case?::
* Why are some Org links opening outside Emacs?::
* Speed up backlinks' or query links' buffer creation?::
* Why do I get ``Search failed with status 1'' when I search for backlinks?::
* Why do I get a double #+title in Doom Emacs?::

Indices

* Function index::
* Variable index::
* Concept index::

[meedstrom]

This will be cool if & when all common package.el repos (GNU, NonGNU and MELPA) do this automatically!

Currently I manually build and commit a .texi in my packages, since MELPA won't build one from just .org last I checked.

I note that the above build step searches for #+TEXINFO_FILENAME:. I've been using #+EXPORT_FILE_NAME:, and I'm gonna switch, but probably the build step should cope with either usage, right?

If the readme uses #+EXPORT_FILE_NAME:, I guess just search again for the presence of at least one other #+TEXINFO... line. Very unlikely there wouldn't be at least one #+TEXINFO_DIR_... line. Example from one of my readmes:

#+TITLE: org-node
#+AUTHOR: Martin Edström
#+EMAIL: meedstrom91@gmail.com
#+STARTUP: content
#+EXPORT_FILE_NAME: org-node
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Org-node: (org-node).
#+TEXINFO_DIR_DESC: Link org-id entries into a network.

Actually, should be enough to just search for #+TEXINFO anything, period.

[lua-vr]

@meedstrom what is the criteria used in ELPA to build info nodes? My suggestion is that the same heuristic could be used here.

Edit: from ELPA's readme and source, I gather this is an opt-in where the packager needs to specify :doc "README.org" in their package spec. So Elpaca would need to fetch this information from the elpa-packages file itself when building its menu.

[progfolio]

@lua-vr We can use the heuristic approach for now (@meedstrom I agree that a "TEXINFO" keyword search should be enough) and if the :doc recipe keyword gains widespread adoption outside of GNU's ELPAs we can formally check for it.

[lua-vr]

@progfolio the build step seems to hang forever for taxy (dependency of magit)

(elpaca-test
  :early-init (setq elpaca-menu-functions '(elpaca-menu-declarations))
  :init (push (elpaca-defscript +elpaca-readme-to-info (:type elisp :dir repo)
                (when (file-exists-p "./README.org")
                  (with-temp-buffer
                    (insert-file-contents (expand-file-name "./README.org"))
                    (goto-char (point-min))
                    (when (re-search-forward "texinfo_filename:" nil t)
                      (require 'ox-texinfo)
                      (org-texinfo-export-to-info)))))
              (cdr (nthcdr (cl-position 'elpaca--check-version elpaca-build-steps)
                           elpaca-build-steps)))
  (elpaca (taxy :repo "https://github.com/alphapapa/taxy.el" :wait t))
  (info "taxy")
  (princ (buffer-substring-no-properties (point-min) (point-max))))

[lua-vr]

can be fixed by ensuring that the commented texinfo_filename line is not considered:

(elpaca-test
  :early-init (setq elpaca-menu-functions '(elpaca-menu-declarations))
  :init (push (elpaca-defscript +elpaca-readme-to-info (:type elisp :dir repo)
                (when (file-exists-p "./README.org")
                  (with-temp-buffer
                    (insert-file-contents (expand-file-name "./README.org"))
                    (goto-char (point-min))
-                    (when (re-search-forward "texinfo_filename:" nil t)
+                    (when (re-search-forward "^[ \t]*#\\+texinfo_filename:" nil t)
                      (require 'ox-texinfo)
                      (org-texinfo-export-to-info)))))
              (cdr (nthcdr (cl-position 'elpaca--check-version elpaca-build-steps)
                           elpaca-build-steps)))
  (elpaca (taxy :repo "https://github.com/alphapapa/taxy.el" :wait t))
  (info "taxy")
  (princ (buffer-substring-no-properties (point-min) (point-max))))

[meedstrom]

That regexp would basically never match, so it's equivalent to (when nil).

 \\`

should be ^, and

\\s

should be \s.