runtime(doc): Add documentation style

dlejay · brianhuster · chrisbra · commit 57d6d004331f · 2025-07-07T19:19:48.000+02:00
closes: #17627 Co-authored-by: Phạm Bình An <111893501+brianhuster@users.noreply.github.com> Signed-off-by: Damien Lejay <damien@lejay.be> Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,7 +3,7 @@
 Patches are welcome in whatever form.
 Discussions about patches happen on the [vim-dev][0] mailing list.
 If you create a pull request on GitHub it will be
-forwarded to the vim-dev mailing list.  You can also send your patch there
+forwarded to the vim-dev mailing list. You can also send your patch there
 directly (but please note, the initial posting is subject to moderation).
 In that case an attachment with a unified diff format is preferred.
 Information about the mailing list can be found [on the Vim website][0]
@@ -12,32 +12,32 @@ A pull request has the advantage that it will trigger the Continuous
 Integration tests, you will be warned of problems (you can ignore the coverage
 warning, it's noisy).
 
-Please consider adding a test.  All new functionality should be tested and bug
+Please consider adding a test. All new functionality should be tested and bug
 fixes should be tested for regressions: the test should fail before the fix and
-pass after the fix.  Look through recent patches for examples and find help
-with ":help testing".  The tests are located under "src/testdir".
+pass after the fix. Look through recent patches for examples and find help
+with ":help testing". The tests are located under "src/testdir".
 
-Contributions will be distributed with Vim under the Vim license.  Providing a
+Contributions will be distributed with Vim under the Vim license. Providing a
 change to be included implies that you agree with this and your contribution
-does not cause us trouble with trademarks or patents.  There is no CLA to sign.
+does not cause us trouble with trademarks or patents. There is no CLA to sign.
 
 ## Signing-off commits
 
 While not required, it's recommended to use **Signed-off commits** to ensure
 transparency, accountability, and compliance with open-source best practices.
 Signed-off commits follow the [Developer Certificate of Origin (DCO)][15],
 which confirms that contributors have the right to submit their changes under
-the project's license.  This process adds a `Signed-off-by` line to commit
+the project's license. This process adds a `Signed-off-by` line to commit
 messages, verifying that the contributor agrees to the project's licensing
-terms.  To sign off a commit, simply use the -s flag when committing:
+terms. To sign off a commit, simply use the -s flag when committing:
 
 ```sh
 git commit -s
 ```
 
 This ensures that every contribution is properly documented and traceable,
 aligning with industry standards used in projects like the Linux Kernel or
-the git project.  By making Signed-off commits a standard practice, we help
+the git project. By making Signed-off commits a standard practice, we help
 maintain a legally compliant and well-governed codebase while fostering trust
 within our contributor community.
 
@@ -48,12 +48,12 @@ approvers are happy with that particular change.
 
 # Reporting issues
 
-We use GitHub issues, but that is not a requirement.  Writing to the Vim
+We use GitHub issues, but that is not a requirement. Writing to the Vim
 mailing list is also fine.
 
 Please use the GitHub issues only for actual issues. If you are not 100% sure
 that your problem is a Vim issue, please first discuss this on the Vim user
-mailing list.  Try reproducing the problem without any of your plugins or settings:
+mailing list. Try reproducing the problem without any of your plugins or settings:
 
     vim --clean
 
@@ -77,7 +77,7 @@ or may not work with older Vim releases (since they may contain new features).
 If you find a problem with one of these files or have a suggestion for
 improvement, please first try to contact the maintainer directly.
 Look in the header of the file for the name, email address, github handle and/or
-upstream repository.  You may also check the [MAINTAINERS][11] file.
+upstream repository. You may also check the [MAINTAINERS][11] file.
 
 The maintainer will take care of issues and send updates to the Vim project for
 distribution with Vim.
@@ -88,23 +88,25 @@ If the maintainer does not respond, contact the [vim-dev][0] mailing list.
 
 If you want to contribute new runtime files for Vim or Neovim, please create a
 PR with your changes against this repository here. For new filetypes, do not forget:
-* to add a new [filetype test][12] (keep it similar to the other filetype tests).
-* all configuration switches should be documented
+
+- to add a new [filetype test][12] (keep it similar to the other filetype tests).
+- all configuration switches should be documented
   (check [filetype.txt][13] and/or [syntax.txt][14] for filetype and syntax plugins)
-* add yourself as Maintainer to the top of file (again, keep the header similar to
+- add yourself as Maintainer to the top of file (again, keep the header similar to
   other runtime files)
-* add yourself to the [MAINTAINERS][11] file.
+- add yourself to the [MAINTAINERS][11] file.
 
 # Translations
 
-Translating messages and runtime files is very much appreciated!  These things
+Translating messages and runtime files is very much appreciated! These things
 can be translated:
-*   Messages in Vim, see [src/po/README.txt][1]
-    Also used for the desktop icons.
-*   Menus, see [runtime/lang/README.txt][2]
-*   Vim tutor, see [runtime/tutor/README.txt][3]
-*   Manual pages, see [runtime/doc/\*.1][4] for examples
-*   Installer, see [nsis/lang/README.txt][5]
+
+- Messages in Vim, see [src/po/README.txt][1]
+  Also used for the desktop icons.
+- Menus, see [runtime/lang/README.txt][2]
+- Vim tutor, see [runtime/tutor/README.txt][3]
+- Manual pages, see [runtime/doc/\*.1][4] for examples
+- Installer, see [nsis/lang/README.txt][5]
 
 The help files can be translated and made available separately.
 See https://www.vim.org/translations.php for examples.
@@ -113,9 +115,11 @@ See https://www.vim.org/translations.php for examples.
 
 Please have a look at the following [discussion][6], which should give you some
 ideas. Please also check the [develop.txt][7] helpfile for the recommended
-style. Often it's also beneficial to check the surrounding code for the style
+coding style. Often it's also beneficial to check the surrounding code for the style
 being used.
 
+For the recommended documentation style, please check [helphelp.txt][16].
+
 # I have a question
 
 If you have some question on the style guide, please contact the [vim-dev][0]
@@ -139,3 +143,4 @@ mailing list. For other questions please use the [Vi Stack Exchange][8] website,
 [13]: https://github.com/vim/vim/blob/master/runtime/doc/filetype.txt
 [14]: https://github.com/vim/vim/blob/master/runtime/doc/syntax.txt
 [15]: https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin
+[16]: https://github.com/vim/vim/blob/master/runtime/doc/helphelp.txt
diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
@@ -1,4 +1,4 @@
-*helphelp.txt*	For Vim version 9.1.  Last change: 2025 Jun 03
+*helphelp.txt*	For Vim version 9.1.  Last change: 2025 Jul 07
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -410,6 +410,24 @@ and 'tabstop' options and the 'filetype' to "help".  Never set a global option
 in such a modeline, that can have undesired consequences.
 
 
+STYLE
+
+If your Vim has 'modeline' enabled, Vim should follow the preferred style
+automatically when editing built-in help files.
+
+Vim help files should be formatted for a 'textwidth' of 78 characters, so they
+look good in a typical 80 x 24 terminal window.
+
+Use two spaces between the final dot of a sentence of the first letter of the
+next sentence.  Like this.
+
+Use tab characters for aligning content, with a 'tabstop' setting of 8.
+This also helps reduce the file size.
+
+Always use |:retab| after you have finished editing.  Don't blindly use
+|:retab!|, always review what will be changed to avoid unwanted changes.
+
+
 TAGS
 
 To define a help tag, place the name between asterisks ("*tag-name*").  The
