[vim/vim] remove misleading :3mat from the documentation (PR #10691)
haron13-2019
When skimming over documentation it is easy to erroneously believe one can use ":3mat" command - see my recent bug report #10690 instantly closed by @chrisbra ))))
Thinking about it a bit, may be this is good idea to officially remove ":3mat" from the documentation. For normal use cases it is anyway not (really) available, it can be only used (as far as I understood) only in some exotic circumstances - for example that standard matchit plugin is deactivated?
Another "improvement" - documentation encourages plugin authors to use ":2mat". Is it not better to leave ":mat" and ":2mat" for interactive usage entirely and ask plugin authors to use matchadd() call directly?
You can view, comment on, or merge this pull request online at:
https://github.com/vim/vim/pull/10691
Commit Summary
- 81f0e89 remove misleading :3mat from the documentation
File Changes
(2 files)
- M runtime/doc/builtin.txt (14)
- M runtime/doc/pattern.txt (13)
Patch Links:
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
codecov[bot]
Codecov Report
Merging #10691 (81f0e89) into master (99af91e) will increase coverage by
0.90%.
The diff coverage isn/a.
@@ Coverage Diff @@ ## master #10691 +/- ## ========================================== + Coverage 81.71% 82.61% +0.90% ========================================== Files 158 148 -10 Lines 185631 172975 -12656 Branches 41980 39102 -2878 ========================================== - Hits 151684 142904 -8780 + Misses 21485 17483 -4002 - Partials 12462 12588 +126
| Flag | Coverage Δ | |
|---|---|---|
| huge-clang-none | 82.61% <ø> (+<0.01%) |
⬆️ |
| linux | 82.61% <ø> (+<0.01%) |
⬆️ |
| mingw-x64-HUGE | ? |
|
| mingw-x64-HUGE-gui | ? |
|
| windows | ? |
Flags with carried forward coverage won't be shown. Click here to find out more.
| Impacted Files | Coverage Δ | |
|---|---|---|
| src/highlight.c | 78.41% <0.00%> (-2.69%) |
⬇️ |
| src/misc2.c | 86.68% <0.00%> (-2.61%) |
⬇️ |
| src/time.c | 87.08% <0.00%> (-2.56%) |
⬇️ |
| src/help.c | 80.07% <0.00%> (-2.38%) |
⬇️ |
| src/buffer.c | 84.11% <0.00%> (-2.35%) |
⬇️ |
| src/session.c | 63.15% <0.00%> (-1.94%) |
⬇️ |
| src/gui.c | 71.19% <0.00%> (-1.87%) |
⬇️ |
| src/menu.c | 81.36% <0.00%> (-1.83%) |
⬇️ |
| src/arglist.c | 83.83% <0.00%> (-1.72%) |
⬇️ |
| src/vim9cmds.c | 85.16% <0.00%> (-1.70%) |
⬇️ |
| ... and 128 more |
Continue to review full report at Codecov.
Legend - Click here to learn more
Δ = absolute <relative> (impact),ø = not affected,? = missing data
Powered by Codecov. Last update 99af91e...81f0e89. Read the comment docs.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Gary Johnson
> When skimming over documentation it is easy to erroneously believe one can use
> ":3mat" command - see my recent bug report #10690 instantly closed by @chrisbra
> ))))
>
> Thinking about it a bit, may be this is good idea to officially remove ":3mat"
> from the documentation. For normal use cases it is anyway not (really)
> available, it can be only used (as far as I understood) only in some exotic
> circumstances - for example that standard matchit plugin is deactivated?
>
> Another "improvement" - documentation encourages plugin authors to use ":2mat".
> Is it not better to leave ":mat" and ":2mat" for interactive usage entirely and
> ask plugin authors to use matchadd() call directly?
and it _can_ be used. In fact, it _is_ used, by the matchparen
plugin. I don't think that hiding it or pretending that it doesn't
exist benefits the user. I certainly would not remove the mentions
of the matchparen plugin.
For example, matcharg(3) returns a different result than matcharg(4)
and :3match will work while :4match will fail. This could be
confusing to the user without an discoverable explanation.
The semi-reserved status of match ID 3 should be mentioned in a few
more places, such as ":help matchadd()", but I would not remove any
of the existing documentation on it.
Regards,
Gary
vim-dev ML
> When skimming over documentation it is easy to erroneously believe one can use
> ":3mat" command - see my recent bug report #10690 instantly closed by @chrisbra
> ))))
>
> Thinking about it a bit, may be this is good idea to officially remove ":3mat"
> from the documentation. For normal use cases it is anyway not (really)
> available, it can be only used (as far as I understood) only in some exotic
> circumstances - for example that standard matchit plugin is deactivated?
>
> Another "improvement" - documentation encourages plugin authors to use ":2mat".
> Is it not better to leave ":mat" and ":2mat" for interactive usage entirely and
> ask plugin authors to use matchadd() call directly?
and it _can_ be used. In fact, it _is_ used, by the matchparen
plugin. I don't think that hiding it or pretending that it doesn't
exist benefits the user. I certainly would not remove the mentions
of the matchparen plugin.
For example, matcharg(3) returns a different result than matcharg(4)
and :3match will work while :4match will fail. This could be
confusing to the user without an discoverable explanation.
The semi-reserved status of match ID 3 should be mentioned in a few
more places, such as ":help matchadd()", but I would not remove any
of the existing documentation on it.
Regards,
Gary
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Tony Mechelynck
If someone reads the source of the matchparen (not matchit) plugin and tries to understand what it does when and how, he'll find that the :3match instruction is used. IMHO it runs totally against the whole Vim philosophy to have such a feature intentionally entirely undocumented: in Vim, everything is documented (or if not, it is an unintentional oversight).
Best regards,
Tony.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you commented.
Bram Moolenaar
As mentioned, removing the :3match command and other info goes against the intention of having help for everything.
I'll include some remarks where a match is added that the ID three is being used by matchparen.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you commented.
Bram Moolenaar
Closed #10691.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you commented.