vimdoc format thought

[osamuaoki]

This is continuation of discussion I originally mentioned in PR "vimdoc format patches" #264 .

The updated file in github repo can produce nice entry for "LOCAL ADDITIONS". Thanks. It served my needs well.

In order to make sure I didn't create misunderstanding, let me summarize vimdoc help file convention situation. It's too complicated for me and I don't find easy answer which one is the best one.

The vimdoc help files shipped by vim start with:

*arabic.txt*	For Vim version 9.0.  Last change: 2021 Jun 22

The vimdoc help files shipped by nvim start with:

*arabic.txt*	Nvim

Since these are part of system, these are not scanned for LOCAL ADDITIONS:`. So tailing differences makes no real impact other than how they show up in help.txt.

The vimdoc help files shipped by vim package author such as aireline (and most other packages on my system) start with:

*airline.txt*  Lean and mean status/tabline that's light as air

This ensure nice looking and consistent listing of auto generated content for help.txt.

The vimdoc help files shipped by many nvim package author such as LazyVim follow:

*LazyVim.txt*          For Neovim >= 0.8.0          Last change: 2023 March 12

These missing package explanation. (There are also some packages which follow similar style with explanation as vim packages.)

For all cases, the initial line starts with it's file name.

In your updated file, e.g., mini-ai.txt, you start with:

*mini.ai* Extend and create a/i textobjects
*MiniAi*

If you want to keep it consistent with the convention to start with file name, this should be more like

*mini-ai.txt*  Extend and create a/i textobjects
                                                                                                      *mini.ai*  *MiniAi*

FYI: The above should still allow us to jump to mini.ai.

[echasnovski]

The full description of how first line should be formatted for it do appear in local additions are listed in :h help-writing. Here is a citation:

The first line in a help file should have the following format:

*plugin_name.txt*	{short description of the plugin}

The first field is a help tag where ":help plugin_name" will jump to.  The
remainder of the line, after a Tab, describes the plugin purpose in a short
way.  This will show up in the "LOCAL ADDITIONS" section of the main help
file.  Check there that it shows up properly: |local-additions|.

If you want to add a version number or last modification date, put it in the
second line, right aligned.

I am more inclined to follow the The first field is a help tag where ":help plugin_name" will jump to. portion of advice.

I did not want to use 'mini-ai.txt' at start because module/plugin name is 'mini.ai', not 'mini-ai'. In turn, help file is named 'mini-ai.txt' because 'mini.ai.txt' feels wrong for having two dots in its name. Besides, having two tags for identical purposes is already a bit much. Adding third one is definitely too much.

Help files most certainly won't have a "Last change:" text because it has little value in my opinion and needs to be additionally automated on top of existing automation.