changeset 36505:8eecffbe2cc3 draft

runtime(doc): Tweak documentation style a bit Commit: https://github.com/vim/vim/commit/624bb83619cbd685b1902b016ca3ececfc1c135c Author: h-east <h.east.727@gmail.com> Date: Sat Nov 9 18:37:32 2024 +0100 runtime(doc): Tweak documentation style a bit closes: https://github.com/vim/vim/issues/11419 Signed-off-by: h-east <h.east.727@gmail.com> Signed-off-by: Christian Brabandt <cb@256bit.org>
author Christian Brabandt <cb@256bit.org>
date Sat, 09 Nov 2024 18:45:04 +0100
parents 961d533d1780
children f8aa79e2c757
files runtime/defaults.vim runtime/doc/builtin.txt runtime/doc/filetype.txt runtime/doc/if_pyth.txt runtime/doc/pattern.txt runtime/doc/pi_netrw.txt runtime/doc/pi_tutor.txt runtime/doc/syntax.txt runtime/doc/undo.txt
diffstat 9 files changed, 72 insertions(+), 71 deletions(-) [+]
line wrap: on
line diff
--- a/runtime/defaults.vim
+++ b/runtime/defaults.vim
@@ -1,7 +1,7 @@
 " The default vimrc file.
 "
 " Maintainer:	The Vim Project <https://github.com/vim/vim>
-" Last Change:	2024 Nov 03
+" Last Change:	2024 Nov 09
 " Former Maintainer:	Bram Moolenaar <Bram@vim.org>
 "
 " This is loaded if no vimrc file was found.
@@ -115,7 +115,7 @@ if 1
       \ |   execute "normal! g`\""
       \ | endif
 
-    " Set the default background for putty to dark. Putty usually sets the 
+    " Set the default background for putty to dark. Putty usually sets the
     " $TERM to xterm and by default it starts with a dark background which
     " makes syntax highlighting often hard to read with bg=light
     " undo this using:  ":au! vimStartup TermResponse"
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.1.  Last change: 2024 Nov 06
+*builtin.txt*	For Vim version 9.1.  Last change: 2024 Nov 09
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -5203,7 +5203,7 @@ glob({expr} [, {nosuf} [, {list} [, {all
 		on {list}
 
 
-glob2regpat({string})					 *glob2regpat()*
+glob2regpat({string})					*glob2regpat()*
 		Convert a file pattern, as used by glob(), into a search
 		pattern.  The result can be used to match with a string that
 		is a file name.  E.g. >
@@ -5656,7 +5656,7 @@ iconv({string}, {from}, {to})				*iconv(
 		Return type: |String|
 
 
-id({item})							    *id()*
+id({item})							*id()*
 		The result is a unique String associated with the {item} and
 		not with the {item}'s contents. It is only valid while the
 		{item} exists and is referenced. It is valid only in the
@@ -7081,7 +7081,7 @@ matchbufline({buf}, {pat}, {lnum}, {end}
 		Return type: list<dict<any>> or list<any>
 
 
-matchdelete({id} [, {win})		       *matchdelete()* *E802* *E803*
+matchdelete({id} [, {win})			*matchdelete()* *E802* *E803*
 		Deletes a match with ID {id} previously defined by |matchadd()|
 		or one of the |:match| commands.  Returns 0 if successful,
 		otherwise -1.  See example for |matchadd()|.  All matches can
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -1,4 +1,4 @@
-*filetype.txt*	For Vim version 9.1.  Last change: 2024 Oct 21
+*filetype.txt*	For Vim version 9.1.  Last change: 2024 Nov 09
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -946,8 +946,8 @@ To enable: >
 	let g:typst_folding = 1
 <
 							*g:typst_foldnested*
-When |TRUE| the Typst filetype plugin will fold nested heading under their parents
-(default: |TRUE|)
+When |TRUE| the Typst filetype plugin will fold nested heading under their
+parents. (default: |TRUE|)
 
 To disable: >
 	let g:typst_foldnested = 0
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -1,4 +1,4 @@
-*if_pyth.txt*   For Vim version 9.1.  Last change: 2024 Nov 06
+*if_pyth.txt*   For Vim version 9.1.  Last change: 2024 Nov 09
 
 
 		  VIM REFERENCE MANUAL    by Paul Moore
@@ -201,8 +201,8 @@ vim.eval(str)						*python-eval*
 	[{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name': ~
 	'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}] ~
 
-	NOTE: In vim9script, local variables in def functions are not visible
-	to to python evaluations. To pass local variables to python evaluations,
+	NOTE: In Vim9 script, local variables in def functions are not visible
+	to python evaluations. To pass local variables to python evaluations,
 	use the {locals} dict when calling |py3eval()| and friends.
 
 vim.bindeval(str)					*python-bindeval*
--- a/runtime/doc/pattern.txt
+++ b/runtime/doc/pattern.txt
@@ -1,4 +1,4 @@
-*pattern.txt*   For Vim version 9.1.  Last change: 2024 Jun 18
+*pattern.txt*   For Vim version 9.1.  Last change: 2024 Nov 09
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -164,7 +164,7 @@ or auto suspended with nohlsearch plugin
 
 
 When 'shortmess' does not include the "S" flag, Vim will automatically show an
-index, on which the cursor is. This can look like this: >
+index, on which the cursor is.  This can look like this: >
 
   [1/5]		Cursor is on first of 5 matches.
   [1/>99]	Cursor is on first of more than 99 matches.
@@ -757,7 +757,7 @@ overview.
 	\([a-z]\+\)\zs,\1		",abc" in "abc,abc"
 
 \@123<=
-	Like "\@<=" but only look back 123 bytes. This avoids trying lots
+	Like "\@<=" but only look back 123 bytes.  This avoids trying lots
 	of matches that are known to fail and make executing the pattern very
 	slow.  Example, check if there is a "<" just before "span":
 		/<\@1<=span
@@ -783,7 +783,7 @@ overview.
 	\(\/\/.*\)\@<!in	"in" which is not after "//"
 
 \@123<!
-	Like "\@<!" but only look back 123 bytes. This avoids trying lots of
+	Like "\@<!" but only look back 123 bytes.  This avoids trying lots of
 	matches that are known to fail and make executing the pattern very
 	slow.
 
@@ -907,7 +907,7 @@ An ordinary atom can be:
 	inside the Visual area put it at the start and just before the end of
 	the pattern, e.g.: >
 		/\%Vfoo.*ba\%Vr
-<	This also works if only "foo bar" was Visually selected. This: >
+<	This also works if only "foo bar" was Visually selected.  This: >
 		/\%Vfoo.*bar\%V
 <	would match "foo bar" if the Visual selection continues after the "r".
 	Only works for the current buffer.
@@ -1014,7 +1014,7 @@ An ordinary atom can be:
 <	To match all characters after the current virtual column (where the
 	cursor is): >
 		/\%>.v.*
-<	Column 17 is not included, because this is a |/zero-width| match. To
+<	Column 17 is not included, because this is a |/zero-width| match.  To
 	include the column use: >
 		/^.*\%17v.
 <	This command does the same thing, but also matches when there is no
@@ -1138,11 +1138,11 @@ x	A single character, with no special me
 	in the collection: "[^xyz]" matches anything but 'x', 'y' and 'z'.
 	- If two characters in the sequence are separated by '-', this is
 	  shorthand for the full list of ASCII characters between them.  E.g.,
-	  "[0-9]" matches any decimal digit. If the starting character exceeds
-	  the ending character, e.g. [c-a], E944 occurs. Non-ASCII characters
+	  "[0-9]" matches any decimal digit.  If the starting character exceeds
+	  the ending character, e.g. [c-a], E944 occurs.  Non-ASCII characters
 	  can be used, but the character values must not be more than 256 apart
-	  in the old regexp engine. For example, searching by [\u3000-\u4000]
-	  after setting re=1 emits a E945 error. Prepending \%#=2 will fix it.
+	  in the old regexp engine.  For example, searching by [\u3000-\u4000]
+	  after setting re=1 emits a E945 error.  Prepending \%#=2 will fix it.
 	- A character class expression is evaluated to the set of characters
 	  belonging to that character class.  The following character classes
 	  are supported:
@@ -1208,7 +1208,7 @@ x	A single character, with no special me
 	  any character that's not in "^]-\bdertnoUux".  "[\xyz]" matches '\',
 	  'x', 'y' and 'z'.  It's better to use "\\" though, future expansions
 	  may use other characters after '\'.
-	- Omitting the trailing ] is not considered an error. "[]" works like
+	- Omitting the trailing ] is not considered an error.  "[]" works like
 	  "[]]", it matches the ']' character.
 	- The following translations are accepted when the 'l' flag is not
 	  included in 'cpoptions':
@@ -1444,14 +1444,14 @@ 10. Highlighting matches				*match-highl
 		display you may get unexpected results.  That is because Vim
 		looks for a match in the line where redrawing starts.
 
-		Also see |matcharg()| and |getmatches()|. The former returns
+		Also see |matcharg()| and |getmatches()|.  The former returns
 		the highlight group and pattern of a previous |:match|
 		command.  The latter returns a list with highlight groups and
 		patterns defined by both |matchadd()| and |:match|.
 
 		Highlighting matches using |:match| are limited to three
 		matches (aside from |:match|, |:2match| and |:3match| are
-		available). |matchadd()| does not have this limitation and in
+		available).  |matchadd()| does not have this limitation and in
 		addition makes it possible to prioritize matches.
 
 		Another example, which highlights all characters in virtual
@@ -1480,7 +1480,7 @@ 10. Highlighting matches				*match-highl
 		with the lowest number has priority if several match at the
 		same position.  It uses the match id 3.
 		The ":3match" command is used by (Vim < 9.0.2054) |matchparen|
-		plugin. You are suggested to use ":match" for manual matching
+		plugin.  You are suggested to use ":match" for manual matching
 		and ":2match" for another plugin or even better make use of
 		the more flexible |matchadd()| (and similar) functions instead.
 
@@ -1489,10 +1489,10 @@ 11. Fuzzy matching					*fuzzy-matching*
 
 Fuzzy matching refers to matching strings using a non-exact search string.
 Fuzzy matching will match a string, if all the characters in the search string
-are present anywhere in the string in the same order. Case is ignored.  In a
+are present anywhere in the string in the same order.  Case is ignored.  In a
 matched string, other characters can be present between two consecutive
-characters in the search string. If the search string has multiple words, then
-each word is matched separately. So the words in the search string can be
+characters in the search string.  If the search string has multiple words, then
+each word is matched separately.  So the words in the search string can be
 present in any order in a string.
 
 Fuzzy matching assigns a score for each matched string based on the following
@@ -1511,8 +1511,8 @@ will match the strings "GetPattern", "Pa
 "getSomePattern", "MatchpatternGet" etc.
 
 The functions |matchfuzzy()| and |matchfuzzypos()| can be used to fuzzy search
-a string in a List of strings. The matchfuzzy() function returns a List of
-matching strings. The matchfuzzypos() functions returns the List of matches,
+a string in a List of strings.  The matchfuzzy() function returns a List of
+matching strings.  The matchfuzzypos() functions returns the List of matches,
 the matching positions and the fuzzy match scores.
 
 The "f" flag of `:vimgrep` enables fuzzy matching.
--- a/runtime/doc/pi_netrw.txt
+++ b/runtime/doc/pi_netrw.txt
@@ -1,4 +1,4 @@
-*pi_netrw.txt*  For Vim version 9.1.  Last change: 2024 Nov 02
+*pi_netrw.txt*  For Vim version 9.1.  Last change: 2024 Nov 09
 
 	    ------------------------------------------------
 	    NETRW REFERENCE MANUAL    by Charles E. Campbell
@@ -1537,7 +1537,7 @@ Associated setting variables:
 	|g:netrw_nogx|	prevent gx map while editing
 	|g:netrw_suppress_gx_mesg| controls gx's suppression of browser messages
 
-OPENING FILES AND LAUNCHING APPS                 *netrw-gx* *:Open* *:Launch* {{{2
+OPENING FILES AND LAUNCHING APPS	*netrw-gx* *:Open* *:Launch* {{{2
 
 Netrw determines which special handler by the following method:
 
--- a/runtime/doc/pi_tutor.txt
+++ b/runtime/doc/pi_tutor.txt
@@ -1,26 +1,26 @@
-*pi_tutor.txt*    For Vim version 9.1.  Last change: 2024 Nov 03
+*pi_tutor.txt*    For Vim version 9.1.  Last change: 2024 Nov 09
 
 INTERACTIVE TUTORIALS FOR VIM			 *vim-tutor-mode*
 
 vim-tutor-mode provides a system to follow and create interactive tutorials
-for vim and third party plugins. It replaces the venerable `vimtutor` system.
+for vim and third party plugins.  It replaces the venerable `vimtutor` system.
 
 =============================================================================
 1. Usage                                                      *vim-tutor-usage*
 
 vim-tutor-mode tutorials are hypertext documents, they have rich text and
-contain links. To stand out from the rest of the text, links are underlined.
+contain links.  To stand out from the rest of the text, links are underlined.
 You can follow them by placing the cursor over them and pressing <Enter>, or
 by double-clicking them.
 
 1.1 Commands
 ------------
 								      *:Tutor*
-:Tutor {tutorial}	Opens a tutorial. Command-line completion for
+:Tutor {tutorial}	Opens a tutorial.  Command-line completion for
 			{tutorial} is provided, the candidates are a list of
 			'.tutor' files found in the 'tutor/'  folder in
-			the 'runtimepath'. Tutorials prefixed with 'vim-' will
-			always be shown first.
+			the 'runtimepath'.  Tutorials prefixed with 'vim-'
+			will always be shown first.
 
 			If no {tutorial} is provided, the command starts the
 			'vim-01-beginner' tutorial, which is equivalent to
@@ -29,7 +29,7 @@ 1.1 Commands
 =============================================================================
 2. Creating tutorials                                        *vim-tutor-create*
 
-Writing vim-tutor-mode tutorials is easy. For an overview of the format used,
+Writing vim-tutor-mode tutorials is easy.  For an overview of the format used,
 please consult the 'tutor.tutor' file: >
 
     :Tutor tutor
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1,4 +1,4 @@
-*syntax.txt*	For Vim version 9.1.  Last change: 2024 Oct 22
+*syntax.txt*	For Vim version 9.1.  Last change: 2024 Nov 09
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -1679,20 +1679,20 @@ on" command in your .vimrc file.
 When you edit an existing Fortran file, the syntax script will assume free
 source form if the fortran_free_source variable has been set, and assumes
 fixed source form if the fortran_fixed_source variable has been set.  Suppose
-neither of these variables have been set. In that case, the syntax script attempts to
-determine which source form has been used by examining the file extension
-using conventions common to the ifort, gfortran, Cray, NAG, and PathScale
-compilers (.f, .for, .f77 for fixed-source, .f90, .f95, .f03, .f08 for
-free-source). No default is used for the .fpp and .ftn file extensions because
-different compilers treat them differently. If none of this works, then the
-script examines the first five columns of the first 500 lines of your file. If
-no signs of free source form are detected, then the file is assumed to be in
-fixed source form.  The algorithm should work in the vast majority of cases.
-In some cases, such as a file that begins with 500 or more full-line comments,
-the script may incorrectly decide that the code is in fixed form.  If that
-happens, just add a non-comment statement beginning anywhere in the first five
-columns of the first twenty-five lines, save (:w), and then reload (:e!) the
-file.
+neither of these variables have been set. In that case, the syntax script
+attempts to determine which source form has been used by examining the file
+extension using conventions common to the ifort, gfortran, Cray, NAG, and
+PathScale compilers (.f, .for, .f77 for fixed-source, .f90, .f95, .f03, .f08
+for free-source).  No default is used for the .fpp and .ftn file extensions
+because different compilers treat them differently. If none of this works,
+then the script examines the first five columns of the first 500 lines of your
+file. If no signs of free source form are detected, then the file is assumed
+to be in fixed source form.  The algorithm should work in the vast majority of
+cases.  In some cases, such as a file that begins with 500 or more full-line
+comments, the script may incorrectly decide that the code is in fixed form.
+If that happens, just add a non-comment statement beginning anywhere in the
+first five columns of the first twenty-five lines, save (:w), and then reload
+(:e!) the file.
 
 Vendor extensions ~
 Fixed-form Fortran requires a maximum line length of 72 characters but the
@@ -2226,9 +2226,9 @@ define the vim variable 'lace_case_insen
 LF (LFRC)		*lf.vim* *ft-lf-syntax* *g:lf_shell_syntax*
 						*b:lf_shell_syntax*
 
-For the lf file manager configuration files (lfrc) the shell commands
-syntax highlighting can be changed globally and per buffer by setting
-a different 'include' command search pattern using these variables:
+For the lf file manager configuration files (lfrc) the shell commands syntax
+highlighting can be changed globally and per buffer by setting a different
+'include' command search pattern using these variables: >
 	let g:lf_shell_syntax = "syntax/dosbatch.vim"
 	let b:lf_shell_syntax = "syntax/zsh.vim"
 
@@ -2538,9 +2538,10 @@ set "msql_minlines" to the value you des
 	:let msql_minlines = 200
 
 
-NEOMUTT			*neomutt.vim* *ft-neomuttrc-syntax* *ft-neomuttlog-syntax*
-
-To disable the default NeoMutt log colors >
+NEOMUTT					*neomutt.vim* *ft-neomuttrc-syntax*
+					*ft-neomuttlog-syntax*
+
+To disable the default NeoMutt log colors: >
 
 	:let g:neolog_disable_default_colors = 1
 
@@ -2710,9 +2711,9 @@ specified. Default = 1 >
 
 	:let g:pandoc#syntax#codeblocks#embeds#use = 1
 
-For specify what languages and using what syntax files to highlight embeds. This is a
-list of language names. When the language pandoc and vim use don't match, you
-can use the "PANDOC=VIM" syntax. For example: >
+For specify what languages and using what syntax files to highlight embeds.
+This is a list of language names. When the language pandoc and vim use don't
+match, you can use the "PANDOC=VIM" syntax. For example: >
 
 	:let g:pandoc#syntax#codeblocks#embeds#langs = ["ruby", "bash=sh"]
 
@@ -3922,7 +3923,7 @@ set "tf_minlines" to the value you desir
 	:let tf_minlines = your choice
 <
 TYPESCRIPT				*typescript.vim* *ft-typescript-syntax*
-				*typescriptreact.vim* *ft-typescriptreact-syntax*
+			    *typescriptreact.vim* *ft-typescriptreact-syntax*
 
 There is one option to control the TypeScript syntax highlighting.
 
@@ -5309,9 +5310,9 @@ of colors by using the `:colorscheme` co
 			This is basically the same as >
 				:echo g:colors_name
 <			In case g:colors_name has not been defined :colo will
-			output "default". Its palette is defined in the file
+			output "default".  Its palette is defined in the file
 			"$VIMRUNTIME/syntax/syncolor.vim" and is based on
-			legacy versions of peachpuff and desert. When compiled
+			legacy versions of peachpuff and desert.  When compiled
 			without the |+eval| feature it will output "unknown".
 
 :colo[rscheme] {name}	Load color scheme {name}.  This searches 'runtimepath'
@@ -5721,8 +5722,8 @@ guisp={color-name}					*highlight-guisp*
 	    :highlight Comment guifg=#11f0c3 guibg=#ff00ff
 <
 	If you are authoring a color scheme and use the same hexadecimal value
-	repeatedly, you can define a (lower case) name for it in |v:colornames|.
-	For example: >
+	repeatedly, you can define a (lower case) name for it in
+	|v:colornames|.  For example: >
 
 	    # provide a default value for this color but allow the user to
 	    # override it.
--- a/runtime/doc/undo.txt
+++ b/runtime/doc/undo.txt
@@ -1,4 +1,4 @@
-*undo.txt*      For Vim version 9.1.  Last change: 2024 Sep 29
+*undo.txt*      For Vim version 9.1.  Last change: 2024 Nov 09
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -183,7 +183,7 @@ g-			Go to older text state.  With a cou
 g+			Go to newer text state.  With a count repeat that many
 			times.
 							*:lat* *:later*
-:lat[er] {count}		Go to newer text state {count} times.
+:lat[er] {count}	Go to newer text state {count} times.
 :lat[er] {N}s		Go to newer text state about {N} seconds later.
 :lat[er] {N}m		Go to newer text state about {N} minutes later.
 :lat[er] {N}h		Go to newer text state about {N} hours later.