Repository: mawww/kakoune

Issue #2402: Standardization of plugin file-structure layout
Created: 2018-09-18T19:08:57Z
Hello. I'm developing a plugin manager for Kakoune (for personal use, but if anyone interested, you're welcome). Since there's no currently de facto standard of Kakoune plugin project layout, I'd like to propose Vim-like one (with some exceptions, because of structure), because it works really well.
Vim's plugin structure
Owerall structure of most plugins can be described like this:
.
├── after
│   └── plugin
├── autoload
├── doc
├── ftplugin
├── indent
├── plugin
└── syntax

Not all folders are necessary, it is highly dependent on the plugin's task. However, the possibilities that come with abilities off putting different modules of the plugin to the supported methods of loading via different directories are huge.
In Vim plugin we have essential plugin folder, which stores all the plugin scripts (I'm dropping autoload part, because there's no equivalent in Kakoune for it, which is sort of a shame, but whatever), doc folder, which contains documentation, and sometimes ftplugin folder, which acts the same way as plugin except it allows loading plugin only for a certain filetype (which again isn't implemented in Kakoune, AFAIK).
This sturcture allows easy unified mechanics for all plugins, to be loaded, loaded with specific filetype, parts of plugin can be autoloaded only when really needed, which boosts overall load time, adding syntax as a part of plugins functions (like Rust plugin adds command interface to cargo through Vim, plus adds advanced syntax highlighting on top of Vim's one), indentation settings for this filetipe, and more. All of this leads to ability of developing really great and advanced plugins, that can turn Vim into full featured IDE.
Documentation
One of the most powerful Vim feature is help system, and one of the most powerful feature of vim's help system is that it can be extended easily. As a plugin creator responsible of writing a comprehensive documentation, editor is responsible of making it easy to refer to that documentation.
Plugins tend grow, and it is natural for them to have a documentation. For example, look at the documentation of LanguageClient-Neovim or UltiSnips. It's kinda huge. And it is meaningless to store all that in the README.md, since this file should contain only essential part about a plugin (although some plugin maintainers do that).
The ability to extend Kakoune's doc base with plugin, or user docs will make overall usage and configuration process lot easier already. This can go alongside with already existing ticket #1991
Proposed plugin layout
Currently, most popular plugins have this layout:
.
├── rc
│   └── plugin.kak
...
├── LICENSE
└── README.asciidoc

There's no separation to documentation, syntax, indentation rules right now.
I'm proposing layout similar to Vim's plugins, but simplified a bit:
.
├── rc
│   ├── doc
│   │   └── plugin.asciidoc
│   ├── indent
│   │   └── indent.kak
│   ├── plugin
│   │   └── plugin.kak
│   └── syntax
│       └── syntax.kak
...
├── LICENSE
└── README.asciidoc

With rc folder being a root of meaningful to kakoune part of a plugin, plugin managers will have easy mechanisms of detecting various parts of plugin, and using dedicated mechanism of loading those files. Kakoune's goal is to support this kind of separation, which is not an issue as I can see right now.
The different method of working currently is needed only for documentation and colorschemes, as former must be located at /installation/path/kak/doc, and latter at the in the $XDG_CONFIG_HOME/kak/colors. The simple solution of loading user or plugin docs will be extension of current doc command making it search docs at user's config folder in a doc folder

Duplicate issue #4342: `declare-colorscheme` command
Created: 2021-09-10T21:52:13Z
Feature 
I would like to have a declare-colorscheme command that will add a colorscheme to the available colorscheme options, but not source the file. It would simply take a path argument like source.
Usecase 
I am extending cork.kak to support colorschemes, and currently the only ways to do it "properly" are to either copy the colorscheme files to the ~/.config/kak/colors directory, or symlink them. Neither of these are preferred, because they both involve messing with the user's kak config directory, which cork.kak currently avoids entirely. Being able to add colorschemes to the colorscheme command with a different command would allow the files to remain outside the default kak directories.
declare-colorscheme "~/.local/share/kak/cork/plugins/one.kak/repo/colors/one-darker.kak"

Closing comment (2021-09-11T06:20:24Z): Dupe of #2402