runtime(doc): Add documentation style
Commit:
https://github.com/vim/vim/commit/57d6d004331f1770b5f04ba28ac242c0e0c8a005
Author: Damien Lejay <[email protected]>
Date: Mon Jul 7 19:19:48 2025 +0200
runtime(doc): Add documentation style
closes: https://github.com/vim/vim/issues/17627
Co-authored-by: Phạm Bình An
<[email protected]>
Signed-off-by: Damien Lejay <[email protected]>
Signed-off-by: Christian Brabandt <[email protected]>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b15727751..8f0947acf 100644
--- 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,14 +12,14 @@ 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
@@ -27,9 +27,9 @@ 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
@@ -37,7 +37,7 @@ 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
index c49a4d50b..f3c5293b7 100644
--- 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
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/vim_dev/E1uYpfM-0094Tk-R5%40256bit.org.
