[vim/vim] vim9.txt: rewrite Section 2 (PR #21132)

# vim9.txt: Conclusion to the rewrite and enhancements - part 2 of 2 (summary)

This is a very significant update.  Initially it considered only Section 2, the last to be enhanced with sourceable Vim9 script examples.  Along the way it extended to also include several standardisation changes, plus improvements to some passages of sections 4 and 6 especially.  “Part 1” of the rewrite addressed those things in Sections 1, and 3 to 7 (NB: they are listed in the explanation to [PR20706](https://github.com/vim/vim/pull/20706)).

**The description, which follows, is a SUMMARY only.**
For more details and the rationale of changes, refer to this Gist: [vim9.txt rewrite Section 2 (details)](https://gist.github.com/kennypete/297fdcb48988b19a22833a405722bf99).

Some improvements in this “Part 2” update necessarily involve the help files `eval.txt` and `userfunc.txt`, where some tags are better relocated either to/from `vim9.txt`.

Locations of changes are indicated by reference to ***tag*** in the _updated_ file.

## 1. Corrections to the current help

- `:&`: currently, the help states this, “cannot be used to repeat a `:substitute` command”.  That is incorrect.  Only bare `&` is unusable; `:&` remains valid.
- Comparing null with 0/false in legacy script: Currently, the help states this “would return true”.  That is incorrect because `1` is not literally `true`, and legacy Vim script returns `1`.
- Predefined-value type table: The current help states, “the other null_ values have the type indicated by their name”.  That is a little misleading.  For example, `null_partial` is `v:t_func`, not `v:t_partial`.
- For-loop item-deletion “trick”: The current help implies this legacy technique does not apply in Vim9 script, which is not wholly the case because it works _identically_ in a non-compiled scope, only behaving differently when compiled.

## 2. Error codes

_Many are relocated, and almost all are accompanied by sourceable scripts now._

- Nearly every error code, below, previously had no sourceable/working example or sat in a location disconnected from what actually triggers it.  Most now have a dedicated, sourceable script demonstrating what gives the error.
  - _New or first-time examples_: E1004, E1014, E1017, E1020, E1021, E1025, E1026, E1034, E1050, E1054, E1055, E1068, E1069, E1074, E1075, E1079, E1080, E1082, E1084, E1087, E1091, E1097, E1099, E1100, E1103, E1106, E1124, E1127, E1128, E1130, E1131, E1133, E1134, E1139, E1144, E1147, E1148, E1149, E1150, E1157, E1160, E1163, E1167, E1168, E1171, E1172, E1176, E1178, E1180, E1181, E1182, E1190, E1191, E1202, E1205, E1213, E1254, E1307, E1360 (example only added; the tag remains in `vim9class.txt), E1395, E1581.
  - _Relocated for logical grouping_ (i.e., the tag is moved to sit with its actual trigger, rather than a disconnected general list): E1147/E1148 (moved from eval.txt to vim9.txt), E1037 (eval.txt, hot-linked to the new `*vim9-comparators*`), E1094, E1053, E1071, E1257, E1261, and the E1047–E1262 import/namespace block (12 errors, itemised individually via the companion “Part 1” PR).

## 3. Other improvements

- New tags are added for concepts which previously had none: `*vim9-invalid-Ex-commands*`, `*vim9-no-shorten*`, `*vim9-functions*`, `*vim9-any-type*`, `*vim9-block*`, `*vim9-no-shadowing*`, `*vim9-omitting-:call*`, `*vim9-omitting-:eval*`, `*vim9-noclear*`, and more.
- Legacy Vim versus Vim9 script comparisons are added in places where Vim9 script-only or abstract snippets do/would not clearly demonstrate the script version behavioural differences.
- The “Predefined values” passage is restructured as a table (`type()`/`typename()`/`string()` per value) rather than prose.
- The “Comparators” passage expands string-only coverage to complete treatment of primitive types, jobs/channels, containers, Funcrefs, class objects, and enum values (including enum singleton-mutation behaviour), none of which is documented currently.

## 4. Open questions

- E1146 (“Command not recognised”): This may be unreachable following resolution of Issues [8454](https://github.com/vim/vim/issues/8454), [8563](https://github.com/vim/vim/issues/8563), and [9270](https://github.com/vim/vim/issues/9270).  It has been left as-is, though is worth a maintainer’s view regarding whether either it is now redundant or remains an intentional catch-all.
- `userfunc.txt`: The recommendation to prefix autoloaded function calls with `g:filename#funcname()` appears worthy of revision, though is out of this PR’s scope to change.
- `null_class`/`null_enumvalue`: The former _always_ errors when used as a value with no apparent legitimate use.  Conversely, there is no `null_enumvalue`, despite it seeming as though it could have real utility.  It may be worth a design discussion.
- E1213 placement: Currently this is in Section 2’s shadowing passage.  Arguably, this could sit with the Import errors in Section 6.
- The legacy `is`/`==` non-transitivity (`v:true == 8` and `8 == 8.0` both work, but `v:true == 8.0` errors).  This has been documented as an aside because it is outside this PR’s scope to resolve (and given it is in legacy Vim script, probably is not worth messing with, though may be worth considering).
You can view, comment on, or merge this pull request online at:

  https://github.com/vim/vim/pull/21132

-- Commit Summary --

  * vim9.txt: rewrite Section 2

-- File Changes --

    M runtime/doc/eval.txt (278)
    M runtime/doc/tags (22)
    M runtime/doc/userfunc.txt (7)
    M runtime/doc/vim9.txt (4086)

-- Patch Links --

https://github.com/vim/vim/pull/21132.patch
https://github.com/vim/vim/pull/21132.diff

-- 
Reply to this email directly or view it on GitHub:
https://github.com/vim/vim/pull/21132
You are receiving this because you are subscribed to this thread.

Message ID: <vim/vim/pull/[email protected]>

-- 
-- 
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/vim/vim/pull/21132%40github.com.