[vim/vim] [WIP/RFC] Documentation for indexing into strings/buffers/windows/screen (PR #10405)
Andrey Mishchenko
I think it could be useful to have a help page covering indexing into strings/buffers/windows/the screen. Specifically I think this would be useful for plugin authors writing text manipulation code where alignment is important, for example when writing an in-buffer GUI or writing a plugin dealing with text alignment.
My hope is that this page can cover the main coordinate systems in Vim (buffer, window, virtual, screen), functions that let you get/set text and cursor position in each of these coordinate systems, and conversion between the coordinate systems. It is also a good place to talk about the different "coordinate systems" for indexing into a string (byte/character/display column).
Doing this will take a lot of work, so before I go further I would like to get feedback:
- Is this addition welcome? I am willing to put a lot of time into making this well-organized, well-written, consistent with the rest of the docs, etc., but the change will still probably require some feedback from Bram or another core maintainer.
- How should this help page be named? Ideas:
indexing.txt,geometry.txt,coords.txt,coordinates.txt, ...- I think
indexing.txtis a good name, but it's very close toindex.txt, which might be annoying.
- I think
- If this help page gets created, should it just consist of prose/examples with links to the reference docs in
builtin.txt, or should the reference documentation for all of these functions get moved to this help page?
The PR below has a proposed outline and a writing sample. Let me know what you think and whether I should continue.
Thanks!
You can view, comment on, or merge this pull request online at:
https://github.com/vim/vim/pull/10405
Commit Summary
- a531a59 Add geometry.txt to Makefile and help.txt
- 3cd5417 wip: geometry.txt
- c7c0a34 wip: indexing.txt
- 084d642 wip: complete rename
- b74d6bd wip: draft of indexing.txt
File Changes
(3 files)
- M runtime/doc/Makefile (1)
- M runtime/doc/help.txt (1)
- A runtime/doc/indexing.txt (266)
Patch Links:
—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.
vim-dev ML
>
> I think it could be useful to have a help page covering indexing into
> strings/buffers/windows/the screen.
>
As a user, I agree that would be useful.
But the most basic info for strings is missing in the current doc. For
example, I got bit a few weeks ago, I wanted to do
for c in "somestring"
and I looked at help for ":for" and it said Lists and Blobs, didn't
mention strings. I took a quick look at ":he List"; didn't mention
strings. I tried to find a way to convert/wrap a string in a Blob, no
joy. ":he string" didn't mention it can be used in :for or indexed with
"[]".
Updating the existing docs might be good start; then you'd have
something to link your overview to.
-ernie
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.
Bram Moolenaar
Andrey Mishchenko wrote:
> I think it could be useful to have a help page covering indexing into
> strings/buffers/windows/the screen. Specifically I think this would be
> useful for plugin authors writing text manipulation code where
> alignment is important, for example when writing an in-buffer GUI or
> writing a plugin dealing with text alignment.
>
> My hope is that this page can cover the main coordinate systems in Vim
> (buffer, window, virtual, screen), functions that let you get/set text
> and cursor position in each of these coordinate systems, and
> conversion between the coordinate systems. It is also a good place to
> into a string (byte/character/display column).
>
> Doing this will take a lot of work, so before I go further I would
> like to get feedback:
>
> making this well-organized, well-written, consistent with the rest of
> the docs, etc., but the change will still probably require some
> feedback from Bram or another core maintainer.
> - I think `indexing.txt` is a good name, but it's very close to
> `index.txt`, which might be annoying.
> - If this help page gets created, should it just consist of prose/examples with links to the reference docs in `builtin.txt`, or should the reference documentation for all of these functions get moved to this help page?
>
> The PR below has a proposed outline and a writing sample. Let me know
> what you think and whether I should continue.
done", while the rest of the help is more a reference manual.
Currently there is only usr_41.txt, which has grown quite long already.
We could turn this into just a short introduction, and then make a whole
new section, with multiple files, about specific parts of script
writing. Something like:
Tuning Vim
usr_40.txt Make new commands
usr_41.txt Introduction to Vim script
usr_42.txt Add new menus
...
Using Vim script
usr_50.txt organising scripts, plugins and import
usr_51.txt manipulating text
usr_52.txt etc.
Your text about indexing will probably fit in usr_51.txt.
Note that the user manual is about explaining how to do something,
omitting complexity and details, concentrating on teaching one thing.
Linking to other parts of the help for when the user does need more.
--
If Microsoft would build a car...
... the oil, water temperature, and alternator warning lights would
all be replaced by a single "General Protection Fault" warning light.
/// Bram Moolenaar -- ***@***.*** -- http://www.Moolenaar.net \\\
/// \\\
\\\ sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///
—
Reply to this email directly, view it on GitHub.
You are receiving this because you commented.
Andrey Mishchenko
That sounds like a great plan. One of Vim's strengths is its plugin community, and a section in the manual about extending/scripting Vim sounds very useful.
It sounds like a good next step is to split a bunch of usr_41.txt into usr_5X.txt pages, under an "Extending Vim" or "Scripting Vim" section of the user manual. Bram, is this something you would like to do personally, or do you think it would be productive for me to give it a shot? Once that is done, the content I am writing can be added incrementally.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you commented.
Bram Moolenaar
> That sounds like a great plan. One of Vim's strengths is its plugin
> community, and a section in the manual about extending/scripting Vim
> sounds very useful.
>
> It sounds like a good next step is to split a bunch of `usr_41.txt`
> into `usr_5X.txt` pages, under an "Extending Vim" or "Scripting Vim"
> section of the user manual. Bram, is this something you would like to
> do personally, or do you think it would be productive for me to give
> it a shot? Once that is done, the content I am writing can be added
> incrementally.
with just one "usr_52.txt' and incrementally update, moving things
around later. Main thing is to avoid trying to explain all the details,
but just the main "how to make it work" part. That is different from
"this is how it works", which belongs in the reference section.
--
hundred-and-one symptoms of being an internet addict:
181. You still remember the "happy tune" your modem made
while dialing your ISP.
/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
Andrey Mishchenko
Closed #10405.
—
Reply to this email directly, view it on GitHub.
You are receiving this because you commented.