Improve documentation workflow.

[seflue]

Describe the bug

I have two issues with the documentation as it is currently.

1. it is not consistently formatted. In my setup I have enabled automatic reformatting for markdown files and it changes basically the whole file. Having a consistent and commonly used formatting standard would be very helpful, because otherwise it is quite tedious to adjust the documentation. Ideally it would come with a formatting configuration as part of the repository, but I am currently not aware of a solution for markdown.
2. The currently used md2vim to generate the vim help from the markdown files is far from ideal. The generated vimhelp.txt lacks a lot of features which are actually part of vims help system and make the manual unnecessary hard to use. Fortunately, I just stumbled over a very promising looking project, panvimdoc which has all the nice features md2vim is missing. And while md2vim is actually archived, vim-pandoc is actively developed. They provide a ready-to-go github action, so it should not be hard to integrate it in this project.

@kristijanhusak Before I put work into this, I want to ask, if there is motivation to actually go in this direction.

Steps to reproduce

left empty on purpose

Expected behavior

1. A consistently formatted set of markdown files for documentation so updating doesn't need cumbersome reconfiguration of the editor or carful selection of actual changes after saving the file.
2. A vimhelp.txt which is actually navigable with the features of vim help, like jumpable tags.

Emacs functionality

No response

Minimal init.lua

left empty on purpose

Screenshots and recordings

No response

OS / Distro

left empty on purpose

Neovim version/commit

all currently supported versions

Additional context

No response

[kristijanhusak]

I was thinking to migrate both readme and docs to an org format, and use https://github.com/kdheepak/panvimdoc to convert it to vim docs.

I got this idea from https://github.com/chipsenkbeil/org-roam.nvim. Docs are written in org https://github.com/chipsenkbeil/org-roam.nvim/blob/main/DOCS.org, and generated with this github action https://github.com/chipsenkbeil/org-roam.nvim/blob/main/.github/workflows/docs.yml

Downside is that everything needs to be adapted to an org format.

For start, your solution will also work, and it should be much faster to implement, so you can proceed if you want.

[seflue]

I actually meant panvimdoc for the conversion. The names are confusing ...

My approach would be the following:

1. Reformat the markdown files.
2. Replace md2vim with panvimdoc
3. Get both on master

After that we can actually play around with converting the existing markdown files to org using pandoc - but because this might need some manual adjustments I would defer this for a separate PR.

[kristijanhusak]

That works.

[parishrutpandey]

I want to add that vim doesn't recognize orgmode.txt as 'help' filetype. I have to add an autocmd for it to do that.

[seflue]

I want to add that vim doesn't recognize orgmode.txt as 'help' filetype. I have to add an autocmd for it to do that.

What you typical do is: You run :helptags ALL and Neovim generates all missing help tags. In this process it actually should find orgmode.txt and also use it.

But to be honest, the result of md2vim looks not good. You don't have syntax highlighting and the table of contents can be only used for navigation with poor-mans tags: searching the next word occurence under cursor with # and *.

[seflue]

@kristijanhusak I was about to experimenting with the migration of the DOCS.md to Org when I saw, that you already pushed a branch with a migrated one. Do you want to discuss the results?

What I discovered, that in org format the very nested documentation of Extract source code (tangle), where you use org source examples containing source examples within org, which confuses treesitter a lot.

I am actually not sure, how panvimdoc handles orgfiles. If it converts them back into markdown before converting it to vimdoc, it might be better, if we cleanup the markdown directly, because there we have more control about what we get from panvimdoc. But I was too lazy to look at the code so far.

[kristijanhusak]

@seflue I converted DOCS.md to DOCS.org with pandoc and started manually fixing it, but it's too big of a work so I stopped. Also it didn't convert it really well, so I'll probably have to start from scratch manually.

I am actually not sure, how panvimdoc handles orgfiles. If it converts them back into markdown before converting it to vimdoc, it might be better, if we cleanup the markdown directly

I'm not sure, I need to look into it better. I had an idea to organize it into multiple files but I'm not sure how will linking work on github and locally.

[seflue]

Yes, the file actually grow a lot. Just my two cents:

I think, it would make sense to ditch the ToC. In Github you can actually show the ToC as a sidebar and panvimdoc will generate one from the headings-structure (including nice jump tags). If I find time to do more research, I will post my findings here in the issue. If you have more insights, I would appreciate, if you could give an update as well.

I really would like to have proper "in-vim" documentation, because it is now my source number one to look if a feature already exists, how it works etc. And I am motivated to help making that happen.

[kristijanhusak]

Yes, we can ditch the ToC. We can generate one in vim docs with panvimdoc if necessary.