I have a large and scattered collection of documentation notes and command recipes (mostly unrelated to Kakoune) which I edit in Kakoune. These are plain text not even asciidoc. I’m looking to upgrade and organize my documentation and I’m drawn to Kakoune’s implementation of asciidoc as opposed to using another tool such as https://discuss.kakoune.com/t/asciidoc-book-editor-for-your-kakoune-readmes-and-more/1851 For example I’d like to use Kakoune’s :doc support to write an asciidoc index page with Kakoune clickable links to plain text notes and recipes.
I would like to be able to specify full paths to the :doc command so I can view my own .asciidoc files under Kakoune. Perhaps a quick and dirty solution would be to add additional paths to the Kakoune documentation search path, but I don’t like the idea of intermingling documentation. Also *doc-doc* says Kakoune searches recursively for .asciidoc, which I take to mean subdirectories which might lead to performance issues in my case.
Kakoune support for asciidoc << >> links seems to be limited to executing :doc, but at the moment I only have plain text notes and would prefer to open them in a new edit session, i.e. I would like to be able to run :e with an absolute path on files in an asciidoc << >> link
I could enter the text “e /full/path/to/recipe.file” in an index file then
select those characters
: to open the Kakoune command prompt
<c-r>. to paste the current selection
enter to open a new edit session
but that is more keystrokes and looks worse than Kakoune asciidoc.
Are there already other solutions? Would it be a major effort to enhance the Kakoune asciidoc logic to process absolute paths? I could see myself eventually using features of asciidoc that Kakoune might not render, but still wanting to edit the asciidocs under Kakoune so support for edit links could be important. If not edit links, then some ability to switch off the asciidoc formatting and edit as plain text.
Never really thought of using doc buffer for personal notes, but this got me curious to experiment with the limitations.
I setup local doc search path via ~/.config/kak/autoload/doc, making sure to link the original rc file in the autoload directory.
Filling the doc directory with 1000 generated .asciidoc files does not slow down :doc command in any noticable way. Though the :doc autocompletion list has an upper limit of 100 items, but it will include omitted items as you start looking for them.
I think this setup could work, if you make sure to:
Prefix all your notes with _, so that they are listed after builtin documentation
Ensure all files have unique basename
So you’ll have to maintain a specific filename schema which you’d also use for categorisation, example _note_somePersonalNote, _man_someManPage.
Perhaps you should solve this by automatically generating symlinks in a dedicated directory under ~/.config/kak/autoload, where the symlink names are generated and validated from your source documentation directory. So the previous example would be generated from doc directory looking like:
doc/
man/
someManPage.asciidoc
note/
somePersonalNote.asciidoc
Though then you have to make sure to keep it up to date by rerunning the script.
Thanks Cipharius. I wasn’t able to get ~/.config/kak/autoload/doc working but did get a symlink to work under /usr/share/kak/doc. However, I quickly found that Kakoune :doc didn’t render an asciidoc include:: directive, even after I also symlinked the included file under /usr/share/kak/doc.
include:: is something that could be handy to consolidate my scattered notes. I think the better solution for me is to set up a kak script to save and regenerate an asciidoc file into html in a separate kitty window using standard tools like asciidoctor and w3m. That effectively replicates the asciidoc editor linked above, except using Kakoune as the editor. Kakoune :doc would also end up requiring a second window tor editing because :doc marks it’s buffer readonly…
Meanwhile, I’ve written a user mapping for :<c-r>.<ret> to easily edit plain text doc files in a plain text documentation index file…
Actually, instead of extending Kakoune’s support for asciidoc, perhaps it would be more strategic to remove it. Before I learned :doc I relied on the help pages on the internet… Why not just ship the asciidoc pages rendered into html in a Kakoune directory and have :doc open up a browser? I typically need a second window for docs and it doesn’t matter that much to me if the docs window is Kakoune or a browser. In my case I’d like to be able to configure :doc to open in a second kitty terminal window running w3m or lynx. If necessary :doc could handle searching all the potential doc directory paths, but I would prefer to leave this to the browser too.
That would give full access to all asciidoc capabilities. Even further, it would remove the dependency on asciidoc and allow full html/svg function. The keymap could be in svg for example. It would relax the doc file naming restrictions.
Am I going one orthogonality too far? Kakoune doesn’t do clipboard, why render asciidoc?