[vim/vim] runtime(doc): Use ellipses for overlength example comments at :help vim9.txt (PR #19298)
dkearns
Use ellipses, matching the file's general style, rather than hard
truncation of overlength tail comments in examples.
Ping @kennypete
Signed-off-by: Doug Kearns dougk...@gmail.com
You can view, comment on, or merge this pull request online at:
https://github.com/vim/vim/pull/19298
Commit Summary
- 3258462 runtime(doc): Use ellipses for overlength example comments at :help vim9.txt
File Changes
(1 file)
- M runtime/doc/vim9.txt (50)
Patch Links:
—
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#19298)On a related note, I think we should consider bumping all examples back to a four column indent. I don't think anything would be lost in terms of readability.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Peter Kenny
kennypete left a comment (vim/vim#19298)Use ellipses, matching the file's general style, rather than hard truncation of overlength tail comments in examples.
I’d done that in many places, though there are some where the cut-off feels odd. If the ‘r’ in ‘String’ is at col 78, ending with ‘Str’ is more informative than ‘…’, for example. It feels like another aspect where a generally agreed approach would help (pardon the pun).
Another consideration is whether to use '…’ or ‘…’ (U+2026). The latter would save two columns’ width, which is not trivial when keeping to <80.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
dkearns
dkearns left a comment (vim/vim#19298)Yes, my preference would be to just truncate them with ellipses in a mechanical fashion. I don't think crafting individual lines based on taste alone works very well with many contributors. To my eye, it looks like someone has taken an axe to those lines and it wasn't always clear if the message was truncated or not. I looked up a couple to be sure.
There's already one use of Unicode ellipsis in general help text at :help gx so that's arguably a green light.
Thanks for all your work on the docs. I realise having people only comment on your line wrapping doesn't make one feel appreciated.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Peter Kenny
kennypete left a comment (vim/vim#19298)Yes, my preference would be to just truncate them with ellipses in a mechanical fashion. I don't think crafting individual lines based on taste alone works very well with many contributors. To my eye, it looks like someone has taken an axe to those lines and it wasn't always clear if the message was truncated or not. I looked up a couple to be sure.
There's already one use of Unicode ellipsis in general help text at
:help gxso that's arguably a green light.
If no truncation is preferred, no problem. I'll standardise to the one-character … with the next vim9.txt PR (which will be the most significant by far).
Thanks for all your work on the docs. I realise having people only comment on your line wrapping doesn't make one feel appreciated.
I'm not a youngster, so have plenty of experience with people focusing mostly on what they consider to be negatives. Better that than silence, provided the intent is to improve things. Specifically, though, thank-you for your, "Thanks". I appreciate that, especially coming from a top contributor and maintainer (who has done/does far more than me).
Although many days in total time spent, it has been an interesting, educational exercise reviewing and, by the time it's done, more that 2x extending vim9.txt, including many working, practical examples. Also, unearthing several unusual loose ends - some still open, some fixed (expr-! fails to handle 0.0 float (except in a :def)) being the latest). Hopefully, it will improve readers' experience and understanding. Even better would be if it drives more Vim9 script uptake in the future.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Peter Kenny
kennypete left a comment (vim/vim#19298)On a related note, I think we should consider bumping all examples back to a four column indent. I don't think anything would be lost in terms of readability.
I agree that it's a good idea to consider it. Although a (with modeline ts=8) one-tab initial indent for examples seems to be the standard, I (fwiw) would prefer a lesser indent for the >vim9 and >vim examples particularly because:
- The syntax highlighting does enough (the earlier "Note:" argument is somewhat analogous?) to distinguish the content, especially as we agreed earlier to have an empty line before and after syntax highlighted code blocks,
- Reducing the number of columns consumed would aid writing script examples,
- It would require fewer continuation lines, and
- Fewer ellipses would be necessary at the end of
#in-line comments.
Arguably, an initial 2-space indent for those code blocks even may be okay?
Further, should a 2-space or 4-space indent be used within Vim9 script code? The distribution’s plugins are inconsistent. Consider these four pack/dist/opt packages:
- comment (2-space in plugin/comment.vim, 4-space in autoload/comment.vim)
- hlyank (2-space)
- helptoc (4-space)
- termdebug (2-space)
No doubt there's a range of views as to what's "best", maybe reflecting a JavaScript or TypeScript v. Python background/preference. Here is a selection of potential options (with 'list'):
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
dkearns
dkearns left a comment (vim/vim#19298)On a related note, I think we should consider bumping all examples back to a four column indent. I don't think anything would be lost in terms of readability.
I agree that it's a good idea to consider it.
[...]
Arguably, an initial 2-space indent for those code blocks even may be okay?
I'd be happy enough with 2 or 4.
Further, should a 2-space or 4-space indent be used within Vim9 script code?
2-space indent has always been the de facto standard but it probably hasn't been enforced with suitable zealotry. I've noticed the help files have all the indents on display (at least 2, 3, 4, and 8) in code examples.
https://github.com/vim/vim/blob/b39b065d6fde5f214feebab882b8ebba78945035/.editorconfig#L23-L25
Let the indent wars restart...
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
Peter Kenny
kennypete left a comment (vim/vim#19298)I agree that it's a good idea to consider it.
[...]
Arguably, an initial 2-space indent for those code blocks even may be okay?
I'd be happy enough with 2 or 4.
Further, should a 2-space or 4-space indent be used within Vim9 script code?
2-space indent has always been the de facto standard but it probably hasn't been enforced with suitable zealotry. I've noticed the help files have all the indents on display (at least 0, 2, 3, 4, and 8) in code examples.
https://github.com/vim/vim/blob/b39b065d6fde5f214feebab882b8ebba78945035/.editorconfig#L23-L25
I would like to go with 4 initial and 2 thereafter. It looks a bit tight with a very small initial indent, and the 8 column initial indent with one tab may be efficient (see below), though does consume too much 'real estate' and makes for more wrapping and ellipsis use. However, I'm concerned about not following helphelp.txt:
Use tab characters for aligning content, with a 'tabstop' setting of 8.
This also helps reduce the file size.
There is also, uniformize help file indents #16204, though there's been no concern about my initial tab and 4-space indents to date. If space is the concern, but applying common sense too, maybe initial tab then 2-space indents is closer to the "uniformize" expectation? The initial tab would follow the help file guidance and the latter (intra code examples) would match the 2-indent de facto standard. That would also keep the size down on what's been accepted so far and, although not minimal, given most of the examples' lines are not indented further than past the tab it's probably a trivial size difference. Also, given the syntax highlighted Vim9 script (and legacy Vim script) examples are not common, this could be a new case with its own rules? I will run with 8 initial (one tab) and 2 intra code (2 spaces) for now. That's not too much to revise given it'll only be the indented lines within code blocks that will need to go from 4 to 2.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.