Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Outstanding Concerns #32

Open
psionic-k opened this issue Oct 24, 2023 · 0 comments
Open

Documentation Outstanding Concerns #32

psionic-k opened this issue Oct 24, 2023 · 0 comments

Comments

@psionic-k
Copy link
Member

psionic-k commented Oct 24, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant