jcs090218
commented
5 days ago Thanks for opening this issue! The community usually needs more interest in discussing document-related topics. 🤔
There has yet to be a standard way to build documents for packages in Eask. However, I've implemented the docs command in #82, but that isn't intended to be the "standard". In case you are curious about the docs command, it uses el2org and generates both Org and HTML formats from Elisp source files.
Ideally, I would support as many modern documentation standards as possible so users can choose according to their tastes. I would also make Texinfo the default option.
What is the EAsk standard for building Info documentation for your Emacs package??
It seems the standard for packages built by Eask is to use README files in Markdown style. This is not the standard for Emacs which has used Texinfo for decades. As such, for new people to Emacs, package documentation will be hidden in the package directory. Providing a .info file and a dir file will integrate the documentation into the Info tree automatically on package installation which will make the documentation readily available to new Emacs users.
Perhaps rules should be included in EAsk to generate an Info file from a Markdown file using Pandoc. Of course, this is simplistic and does nothing to ensure that the style of the document is in keeping with the Emacs style guide. In fact, I would suggest making Org files the standard for documentation as there is a Texinfo export backend included in Org as well as a Markdown export backend. Pandoc could also convert your Markdown files to Org files.
What do you think?