Documentation Outstanding Concerns

[psionic-k]

Includes indirection

Jumping to an include statement in org mode is kind of annoying, indirection. Can probably make these live links. (org customization)

Org Setup File Probably Needed

I did not use a setup.org or anything like that because it's more indirection, but it's looking more like a better choice. The hooks and macros need to work with or without ERK installed, and that means declaring basic versions of these shortcuts in a setup.org could distribute the functionality for people without ERK. This is the kind of file that would definitely be copy-paste across projects.

Manuals on Installation

After tagging 0.4.0, I found that the manuals were not being installed from docs/manual.texi. The MELPA file filters allow this path, and the tarballs MELPA delivers contain them, but Elpaca and Straight's filters do not pick up these files. It turns out that naming the info file to the same as the directory is necessary for Info to pick it up. I definitely had some issues until figuring out that erk.info works as intended.

Remaining Scattering

A lot of the files were originally written to be self-documenting. There could be little pieces of out-of-date information here and there. Without tangling the manual into elisp or importing sections of wildly different kinds of data, it won't be realistic to go farther. We need AI based document coherence checking to really go farther with automation without adding lots of indirection.

Path Offsets

When reading the manual, it seems written as if paths are off by one. The github readme links are also slightly off. Github docs say it's fine with relative links.

For now I've decided to make the outputs correct at the expense of the inputs. In the end, I think there will be some link translation settings added to an org file that tries as much as possible to automate things independently or not of whether ERK is used for export.

Remove Links to Manual in Readme output

Readme can't link to the manual. So links to info need to be removed in markdown. Not sure how that's working right now.

Version

The package version can update without triggering any documentation update. CI integration would just catch this