Make Eldev documentation available as an Info manual when installed through MELPA

[suhail-singh]

While the Eldev website has excellent documentation, at times I do wish it was
easier to peruse it offline and especially within Emacs as an Info manual (with
keyboard navigation to navigate sections etc).

If the MELPA package contained the documentation in Info format, it would help
matters.

[doublep]

I certainly don't plan to maintain two sets of documentation, but if you can find an automated converter from Asciidoc, I could try to autoconvert the manual into .info format.

[suhail-singh]

org-pandoc-import can be used
to import from Asciidoc to Org. From there ox-texinfo can be used to export
to Texinfo, from whence it can be exported to Info.

Having not tried this particular path myself (though I have used
org-pandoc-import as well as ox-texinfo in the past), I am not sure how
usable the generated Info manual would be, but it may be worth trying if you're
open to it.

[doublep]

Having not tried this particular path myself (though I have used org-pandoc-import as well as ox-texinfo in the past), I am not sure how usable the generated Info manual would be

M-m, can you at least try that? I don't use Org myself, so I don't want to spend time investigating this if it's not even certain the end result is going to be useful.

It would be great if you could provide some short (Lisp?) code to simply do it. I can then convert it to a GitHub workflow (given that the package needs to be published on MELPA, I doubt I could include any forms to "run before packaging", I can only package files already in the source tree).

[suhail-singh]

I investigated this somewhat. My conclusion is that unless you're willing to
maintain the documentation in Org format (from where you can export to both HTML
and Info formats), this may not really be feasible.

It seems pandoc doesn't directly support asciidoc as an input format. As
such, the path from asciidoc to texinfo goes something like this:

1. asciidoc to docbook (via asciidoctor)
2. docbook to org (via pandoc directly or via pandoc and
   org-pandoc-import)
3. org to texinfo (via builtin ox-texinfo)

Currently, step 3 above fails because the Org file generated in 2 has some
issues (some internal references need to be tweaked). As such this isn't a
viable route while the documentation continues to be maintained in asciidoc
format. However, if the documentation were to be maintained in Org format
(possibly using the Org document generated in step 2 as a starting point),
there's greater hope that automated exports to both HTML and Info formats can be
supported.

Caveats

The above was tested with pandoc version 2.19.2. This is the latest version
in Guix, but is a dated version. It's possible that more recent versions of
podman generate an Org document in step 2 such that step 3 proceeds without
error.

[doublep]

unless you're willing to maintain the documentation in Org format

No, sorry. I don't want to change from Asciidoc. I'll keep the issue open in case someone finds a way to autoconvert that to .info somehow.

[okomestudio]

I was looking to see if the Info version of manual existed for Eldev and came across this ticket. I experimented with creating the .info file, similarly to #110 (comment), and the conversion from Org to Info seems to work so long as the hyperlinks to marked objects within the same Org document is in the correct format.

That conversion process is hard-coded in the PR that I just created.

The Info document is viewable with Emacs, but I'm not sure the generated Info doc is sufficiently well-formatted for immediate use. The original version contains the table of contents, but that looks redundant when rendered. So I'm not sure how that kind of thing should be dealt with.

#112 is more a proof-of-concept PR, so I'm not necessarily requesting it to be merged as is.

I hope this moves things closer for Eldev to actually include the Info version of documentation. The asciidoc version is pretty nice, but not needing to switch between Emacs and the web browser frequently is also nice.