[Discussion] Misleading naming and function

[saccarosium]

Hi, I think that calling the plugin wiki-ft and specificly targeting .wiki filetypes is a little misleading since when refering to a .wiki file, usually is in the media wiki syntax or vimwiki syntax. But when I look at the docs I see simply commonmark with the wiki-style links extention and nothing more. So why this is a .wiki filetype and not a markdown filetype?

[lervag]

I think that calling the plugin wiki-ft and specificly targeting .wiki filetypes is a little misleading since when refering to a .wiki file, usually is in the media wiki syntax or vimwiki syntax.

Originally, wiki-ft.vim was part of wiki.vim. wiki.vim sort of started as a "fork" of Vimwiki. It's only partially true, because I didn't really reuse most of the code and instead rewrote it, but it was clearly based on Vimwiki. For this reason, I started wiki.vim with an ftplugin for .wiki files. For simplicity, I pivoted the syntax much more towards more standard Markdown (or commonmark or github flavored markdown). At one point, I realized that the wiki.vim idea should be general, and so I moved the filetype features into a separate plugin. I wanted wiki.vim to be filetype "agnostic". The result was that I created wiki-ft.vim.

So, you are sort of correct. However, wiki-ft.vim is really an unspecified file format that is a mix of other more or less specified formats. I still use this myself, but I have a long-term plan to change my notes into standard Markdown (or some flavor like CommonMark) and then use a better and more complete plugin for that (or perhaps Treesitter).

But when I look at the docs I see simply commonmark with the wiki-style links extention and nothing more. So why this is a .wiki filetype and not a markdown filetype?

Good question with no very good answer except "historic" reasons. So, perhaps we could say it is because of "bad choices".

It seems you are also using this right now. If you do not have very many notes yet, then I think it could be good advice to consider to use a more standard filetype for your wiki/knowledge base/notes. wiki.vim should still work very well, and if you find it doesn't, then please let me know and I will be happy to look into it.

Also, if you use wiki-ft.vim and are actually happy with it, except for the name, then that's also nice to hear. Notice, though, that I don't think it is right to apply this plugin as a .md filetype. It would then "fail" to work correctly on many common elements of standard README.md files and similar. That is, I don't really want to spend much more time on this particular plugin, except for simple maintenance.

[saccarosium]

It seems you are also using this right now. If you do not have very many notes yet, then I think it could be good advice to consider to use a more standard filetype for your wiki/knowledge base/notes. wiki.vim should still work very well, and if you find it doesn't, then please let me know and I will be happy to look into it.

I personally use now asciidoc, but the reason I've checkout this plugin was for two main reasons:

1. I was interested in investigating mediawiki markup for writing notes, I was already using asciidoc for document formatting but though that maybe could be a bit heavy for light note taking;
2. wiki.vim as some weird default syntax biasses that confuses me like: wiki#toc#gather_entries searches all heading prepended with an #, but uses the tag notation with the colons :tag1:tag2. This was really confusing since we are mixing markups here.

My argument is that is probably better trying to make wiki.vim more syntax agnostic and probably bettering the defaults because I argue that calling this a .wiki syntax is confusing.

[lervag]

wiki.vim [h]as some weird default syntax biasses that confuses me like: wiki#toc#gather_entries searches all heading prepended with an #, but uses the tag notation with the colons :tag1:tag2. This was really confusing since we are mixing markups here.

Ah, yes. But that is not related to this plugin (wiki-ft.vim). But you are right. There are a few features in wiki.vim that assumes a specific file format. This is usually pretty standard Markdown, I think.

My argument is that is probably better trying to make wiki.vim more syntax agnostic and probably bettering the defaults

I may tend to agree here as well, but again, this point does addresses wiki.vim, not wiki-ft.vim.

because I argue that calling this a .wiki syntax is confusing.

One alternative here would be to remove wiki-ft.vim from the public sphere. I use it personally, and as mentioned, I have a long-term plan to migrate to a more standard filetype. In the meantime, it could be less confusing if I made wiki-ft.vim a personal, unshared plugin.

So, perhaps I should consider to make the default for wiki.vim be to assume standard Markdown filetype instead of the .wiki filetype.

Currently, this is on the top of the wiki.vim README:

Note: wiki.vim is not a filetype plugin. It is designed to be used with
      filetype plugins, e.g. dedicated Markdown plugins. A simple alternative
      is to use wiki-ft.vim for syntax highlighting and folding of .wiki
      files. Users are adviced to read ":help wiki-intro-plugins" for a list of
      plugins that work well with wiki.vim.

I think the last part of that note combined with the default setting may be the most confusing parts here?

[saccarosium]

I may tend to agree here as well, but again, this point does addresses wiki.vim, not wiki-ft.vim.

I will move this issue to wiki.vim repo.

I think the last part of that note combined with the default setting may be the most confusing parts here?

The TLDR is you should probably not advertise this plugin as a .wiki Filetype plugin and start support for true .wiki syntax if you want to keep supporting this extension. (obviously you can do whatever you prefer, the project is yours)