[vim/vim] Add g:help_example_languages to support language annotation highlighting (PR #16238)
Shougo
Continues of #16215
I have added g:help_example_languages variable to support language annotation highlighting.
Because markdown has similar feature by g:markdown_fenced_languages.
Before:
2024-12-17_17-52.png (view on web)
After:
2024-12-17_17-55.png (view on web)
You can view, comment on, or merge this pull request online at:
https://github.com/vim/vim/pull/16238
Commit Summary
- 8fe8ec9 Add g:help_example_languages to support language annotation highlighting
File Changes
(4 files)
- M runtime/doc/helphelp.txt (28)
- M runtime/doc/os_dos.txt (4)
- M runtime/doc/tags (1)
- M runtime/syntax/help.vim (32)
Patch Links:
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo pushed 1 commit.
- 242dbef Add g:help_example_languages to support language annotation highlighting
—
View it on GitHub or unsubscribe.
You are receiving this because you are subscribed to this thread.
mityu
@mityu commented on this pull request.
> endif
+
+for [s:lang, s:syntax] in g:help_example_languages->items()
+ unlet! b:current_syntax
+ " silent! to prevent E403
+ execute 'silent! syntax include' $'@Example{s:lang}' $'syntax/{s:syntax}.vim'
+
+ execute $'syn region helpExample{s:lang} matchgroup=helpIgnore'
+ \ $'start=/^>{s:lang}$/ start=/ >{s:lang}$/'
+ \ 'end=/^[^ \t]/me=e-1 end=/^</'
+ \ (has("conceal") ? 'concealends' : '')
+ \ $'contains=@Example{s:lang} keepend'
+endfor
+
How about to unlet s:lang and s:syntax here?
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
h_east
Ummm... I feel like there's something really bothering me, though...
Maybe the match condition ( >[a-z0-9]*$ or ^>[a-z0-9]*$) is too simple.
Is it okay if it's " >|[a-z0-9]+|$", "^>|[a-z0-9]+|$" or " >:[a-z0-9]+:$", "^>:[a-z0-9]+:$"?
Example1: >|vim|
code1
>
Obviously, the following is the same highlighting as before.
Example2: >
code2
>
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Clason
You do what works best for you, of course, but Neovim already uses >foo for code block annotations. It would be really nice if plugins could support both editors in their documentation.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
@chrisbra commented on this pull request.
> @@ -433,17 +433,27 @@ To quote a block of ex-commands verbatim, place a greater than (>) character at the end of the line before the block and a less than (<) character as the first non-blank on a line following the block. Any line starting in column 1 also implicitly stops the block of ex-commands before it. E.g. > - function Example_Func() - echo "Example" - endfunction + function Example_Func() + echo "Example" + endfunction
why the indentation change?
> <
-It's possible to add Vim syntax highlighting support to code examples. This
-can be done by adding "vim" after the greater than (>) character (">vim").
-E.g: >vim
- function Example_Func()
- echo "Example"
- endfunction
+
+To add annotation in the block, place the annotation (ex: "lua") after a
+greater than (>) character. E.g: >lua
+ print("hello")
+<
⬇️ Suggested change
-< +< +Note: uses lua syntax highlighting, if "lua" is in |g:help_example_languages|.
> <
-It's possible to add Vim syntax highlighting support to code examples. This
-can be done by adding "vim" after the greater than (>) character (">vim").
-E.g: >vim
- function Example_Func()
- echo "Example"
- endfunction
+
+To add annotation in the block, place the annotation (ex: "lua") after a
+greater than (>) character. E.g: >lua
+ print("hello")
+<
+In default, it's possible to add Vim syntax highlighting support to code
⬇️ Suggested change
-In default, it's possible to add Vim syntax highlighting support to code +It's possible to add Vim syntax highlighting support to code
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is language annotation and the value is syntax name.
+
When not configured, help files support Vim script highlighting only.
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
Perhaps it should be named: g:help_import_languages ?
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is language annotation and the value is syntax name.
⬇️ Suggested change
-The key is language annotation and the value is syntax name. +The key is the annotation marker and the value is the 'syntax' name.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo commented on this pull request.
> @@ -433,17 +433,27 @@ To quote a block of ex-commands verbatim, place a greater than (>) character at the end of the line before the block and a less than (<) character as the first non-blank on a line following the block. Any line starting in column 1 also implicitly stops the block of ex-commands before it. E.g. > - function Example_Func() - echo "Example" - endfunction + function Example_Func() + echo "Example" + endfunction
I have read the other example indentation.
It seems indented by tab.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
Hm... It seems from implementation name.
help_example_languages means it describes the example languages.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is language annotation and the value is syntax name.
+
OK.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo commented on this pull request.
> endif
+
+for [s:lang, s:syntax] in g:help_example_languages->items()
+ unlet! b:current_syntax
+ " silent! to prevent E403
+ execute 'silent! syntax include' $'@Example{s:lang}' $'syntax/{s:syntax}.vim'
+
+ execute $'syn region helpExample{s:lang} matchgroup=helpIgnore'
+ \ $'start=/^>{s:lang}$/ start=/ >{s:lang}$/'
+ \ 'end=/^[^ \t]/me=e-1 end=/^</'
+ \ (has("conceal") ? 'concealends' : '')
+ \ $'contains=@Example{s:lang} keepend'
+endfor
+
OK.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
Maybe the match condition ((^| )>[a-z0-9]*$) is too simple.
Is it okay if it's (^| )>|[a-z0-9]+|$ or (^| )>:[a-z0-9]+:$ ?
(Enclose the language name in symbols)
It may be too simple. But markdown syntax uses similar markup like this.
```vim
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo pushed 2 commits.
You are receiving this because you are subscribed to this thread.
Shougo
I have updated the syntax file.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo pushed 6 commits.
- ddbfdc1 Add g:help_example_languages to support language annotation highlighting
- d53c2a2 Update runtime/doc/helphelp.txt
- 9104ae2 Update runtime/doc/helphelp.txt
- ef513ac Update runtime/doc/helphelp.txt
- 1c35613 Fix for reviews
- 24b1cb0 Improve syntax file
You are receiving this because you are subscribed to this thread.
Shougo
Hm... Why the tests are failed?
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo commented on this pull request.
> endif
+
+for [s:lang, s:syntax] in g:help_example_languages->items()
+ unlet! b:current_syntax
+ " silent! to prevent E403
+ execute 'silent! syntax include' $'@Example{s:lang}' $'syntax/{s:syntax}.vim'
+
+ execute $'syn region helpExample{s:lang} matchgroup=helpIgnore'
+ \ $'start=/^>{s:lang}$/ start=/ >{s:lang}$/'
+ \ 'end=/^[^ \t]/me=e-1 end=/^</'
+ \ (has("conceal") ? 'concealends' : '')
+ \ $'contains=@Example{s:lang} keepend'
+endfor
+
Fixed.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
h_east
It may be too simple. But markdown syntax uses similar markup like this.
The "simple" here means that there is a high probability that the pattern will match unintentionally in the help text.
That actually existed, right? (Well, it was a bit subtle) --> #16215 (comment)
In that sense, markdown syntax is NOT "simple".
However, the original >$ itself is simple, so I guess it's okay.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
zeertzjq
Maybe the pattern can be added only for every language in the list instead of [a-z]* to avoid false positives?
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
h_east
@h-east commented on this pull request.
> endif
+
+for [s:lang, s:syntax] in g:help_example_languages->items()
+ unlet! b:current_syntax
+ " silent! to prevent E403
+ execute 'silent! syn include' $'@helpExampleHighlight_{s:lang}'
+ \ $'syntax/{s:syntax}.vim'
+
+ execute $'syn region helpExampleHighlight_{s:lang} matchgroup=helpIgnore'
+ \ $'start=/^>{s:lang}$/ start=/ >{s:lang}$/'
This also inspires me 😜
⬇️ Suggested change- \ $'start=/^>{s:lang}$/ start=/ >{s:lang}$/'
+ \ $'start=/\%(^\| \)>{s:lang}$/'
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
h_east
Maybe the pattern can be added only for every language in the list instead of [a-z]* to avoid false positives?
If we do that, I feel like examples in languages not specified in g:help_example_languages will no longer be highlighted with helpExample. Is that okay?
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Shougo
The "simple" here means that there is a high probability that the pattern will match unintentionally in the help text.
That actually existed, right? (Well, it was a bit subtle) --> #16215 (comment)
It might unintentionally conflict with the existing description.
In such cases, it is likely that the markup is not done correctly.
Maybe the pattern can be added only for every language in the list instead of [a-z]* to avoid false positives?
It is possible but ...
If we do that, I feel like examples in languages not specified in g:help_example_languages will no longer be highlighted with helpExample. Is that okay?
Yes. I think it is problem. Even if the unspecified language is not syntax highlighted, I would like to keep the example highlighting.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
h_east
@h-east commented on this pull request.
Wouldn't it be better if vim highlighting was always enabled?
I think it would be less confusing if it was always enabled internally, without the need to set it in g:help_example_languages.
> +unlet s:lang +unlet s:syntax
Error with let g:help_example_languages = {}
line 43:
E108: No such variable: "s:lang"
line 44:
E108: No such variable: "s:syntax"
Press ENTER or type command to continu
-unlet s:lang -unlet s:syntax +unlet! s:lang +unlet! s:syntax
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Aliaksei Budavei
Syntax file maintainers will justifiably balk at rewriting
parts of their files to accommodate arbitrary inclusion.
Currently, they can manage the context of syntax items by
choosing :syn-contained for some and omitting it for other,
and establish :syn-priority among the same scope items by
moving them up and down a file. As soon as their files are
:syn-included, ALL is :syn-contained, with :syn-priority
revised without their consulting!
There is already one discrepancy spotted, e.g.:
Head section.
>vim
if 1
elseif 0
else " endif
endif
if 1 | elseif 0 | else | endif " endif
while 0
endwhile
while 0 | endwhile " endwhile
print
Tail section.
Well, a naïve fix is as follows:
diff --git a/runtime/syntax/generator/vim.vim.base b/runtime/syntax/generator/vim.vim.base index 6d67d7b93..81e01a0c5 100644 --- a/runtime/syntax/generator/vim.vim.base +++ b/runtime/syntax/generator/vim.vim.base @@ -205,13 +205,13 @@ syn case match syn cluster vimCmdList contains=vimAbb,vimAddress,vimAutoCmd,vimAugroup,vimBehave,vimCall,vimCatch,vimConst,vimDef,vimDefFold,vimDelcommand,@vimEcho,vimEnddef,vimEndfunction,vimExecute,vimIsCommand,vimExtCmd,vimFor,vimFunction,vimFuncFold,vimGlobal,vimHighlight,vimLet,vimLoadkeymap,vimMap,vimMark,vimMatch,vimNotFunc,vimNormal,vimSet,vimSleep,vimSyntax,vimThrow,vimUnlet,vimUnmap,vimUserCmd,vimMenu,vimMenutranslate,@vim9CmdList syn cluster vim9CmdList contains=vim9Class,vim9Const,vim9Enum,vim9Export,vim9Final,vim9For,vim9Interface,vim9Type,vim9Var syn match vimCmdSep "[:|]\+" skipwhite nextgroup=@vimCmdList,vimSubst1 -syn match vimIsCommand "\<\%(\h\w*\|[23]mat\%[ch]\)\>" contains=vimCommand syn match vimBang contained "!" syn match vimVar contained "\<\h[a-zA-Z0-9#_]*\>" syn match vimVar "\<[bwglstav]:\h[a-zA-Z0-9#_]*\>" syn match vimVar "\s\zs&\%([lg]:\)\=\a\+\>" syn match vimVar "\s\zs&t_\S[a-zA-Z0-9]\>" syn match vimVar "\s\zs&t_k;" +syn match vimIsCommand "\<\%(\h\w*\|[23]mat\%[ch]\)\>" contains=vimCommand syn match vimFBVar contained "\<[bwglstav]:\h[a-zA-Z0-9#_]*\>" syn keyword vimCommand contained in syn match vimBang contained "!"
BUT, it breaks a test (vim9_ex_loadkeymap), @dkearns.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo pushed 1 commit.
- f7e4d2e Update runtime/syntax/help.vim
—
View it on GitHub or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
Wouldn't it be better if vim highlighting was always enabled?
I think it would be less confusing if it was always enabled internally, without the need to set it in >g:help_example_languages.
The change is possible, but I would like to keep it configurable, including Vim script syntax highlighting.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo pushed 7 commits.
- ceb407e Add g:help_example_languages to support language annotation highlighting
- de0b90b Update runtime/doc/helphelp.txt
- 567b20b Update runtime/doc/helphelp.txt
- 11bb2a7 Update runtime/doc/helphelp.txt
- 8ad76a0 Fix for reviews
- bc0c786 Improve syntax file
- bfa123b Update runtime/syntax/help.vim
You are receiving this because you are subscribed to this thread.
h_east
Then, add to the documentation the behavior when g:help_example_languages is not defined and the precautions when setting g:help_example_languages.
Current documentation will confuse everyone regarding Vim script highlighting.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Shougo
*g:help_example_languages*
If you want to change the syntax highlighting in the block, you can
change it like this: >
:let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
The key is the annotation marker name and the value is the 'syntax' name.
When not configured, help files support Vim script highlighting only.
Then, add to the documentation the behavior when g:help_example_languages is not defined and the precautions when setting g:help_example_languages.
Current documentation will confuse everyone regarding Vim script highlighting.
Could you please specify what kind of precautions are necessary?
Could you provide some suggestions?
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
h_east
@h-east commented on this pull request.
> +if !exists('g:help_example_languages')
+ let g:help_example_languages = #{ vim: 'vim' }
+endif
Document this.
And, when setting g:help_example_languages, if you do not add vim, vim script syntax highlighting will not be available.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo commented on this pull request.
> +if !exists('g:help_example_languages')
+ let g:help_example_languages = #{ vim: 'vim' }
+endif
And, when setting g:help_example_languages, if you do not add vim, vim script syntax highlighting will not be available.
OK. I will add it.
Document this.
I think it is documented by When not configured, help files support Vim script highlighting only.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo pushed 1 commit.
- c5c5345 Update the documentation
—
View it on GitHub or unsubscribe.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
@chrisbra commented on this pull request.
> +if !exists('g:help_example_languages')
+ let g:help_example_languages = #{ vim: 'vim' }
+endif
yes should be fine
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
@chrisbra commented on this pull request.
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is the annotation marker name and the value is the 'syntax' name.
+When not configured, help files support Vim script highlighting only.
+Note: When setting "g:help_example_languages", if you do not add "vim", Vim
+script syntax highlighting will not be available.
⬇️ Suggested change
-script syntax highlighting will not be available. +When setting "g:help_example_languages" to an empty value, syntax highlighting for embedded languages will be disabled.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
I am undecided mainly because of the issue mentioned by @zzzyxwvut
@dkearns your opinion please to include further languages?
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
h_east
@h-east commented on this pull request.
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is language annotation and the value is syntax name.
+
- The flow from the previous line seems strange.
- Exceeds 80 characters.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
h_east
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is the annotation marker name and the value is the 'syntax' name.
+When not configured, help files support Vim script highlighting only.
+Note: When setting "g:help_example_languages", if you do not add "vim", Vim
+When setting "g:help_example_languages" to an empty value, syntax highlighting for embedded languages will be disabled.
This was posted to vim_dev, but it doesn't seem to be reflected on GitHub, so I'm rewriting it.
- The flow from the previous line seems strange.
- Exceeds 80 columns.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo commented on this pull request.
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is the annotation marker name and the value is the 'syntax' name.
+When not configured, help files support Vim script highlighting only.
+Note: When setting "g:help_example_languages", if you do not add "vim", Vim
+When setting "g:help_example_languages" to an empty value, syntax highlighting for embedded languages will be disabled.
Exceeds 80 columns.
Thanks.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo pushed 1 commit.
- 126077a Improve the documentation
—
View it on GitHub or unsubscribe.
You are receiving this because you are subscribed to this thread.
Shougo
@Shougo commented on this pull request.
> <
+ *g:help_example_languages*
+If you want to change the syntax highlighting in the block, you can
+change it like this: >
+ :let g:help_example_languages = #{ vim: 'vim', sh: 'bash' }
+The key is the annotation marker name and the value is the 'syntax' name.
+When not configured, help files support Vim script highlighting only.
+Note: When setting "g:help_example_languages", if you do not add "vim", Vim
+When setting "g:help_example_languages" to an empty value, syntax highlighting for embedded languages will be disabled.
The flow from the previous line seems strange.
I have updated the documentation.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
Okay, I include it and add a note, that for proper support included syntax highlighting needs to be accounted for, it may not always work perfectly otherwise.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Christian Brabandt
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
dkearns
dkearns left a comment (vim/vim#16238)Sorry, I completely missed this when it was included. Too much Xmas cheer?
As @zzzyxwvut points out, supporting this sort of inclusion can be difficult but I'll see what I can do.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.