Vim: Search Javascript documentation

I usually work at Kate or Geany. But sometimes, like all people, I want to learn Vim. And each time, approximately in the second minute of “mastering,” some completely stupid question arises. For example, why when you press the arrows (or jk keys) the cursor jumps right through all the lines of a paragraph?

No matter how hard I tried to formulate my questions, the search gives me about the same one hundred sites each with titles like “100 Most Useful Vim Commands”. And whatever website I choose, it will always lack the “team” that I need right now.

I thought how to find not a hundred, but in general all the Wim teams. And I found the same page on the network, which was called “All Vim teams”. And there really was a very large list - about six hundred words. But it was not stated that these commands do, - just a list of terms. I was so angry with this joke that I finally decided to read the documentation and once and for all make my own list of “all Vim commands”. Result on the screen. Details below.

On the official site I was sent to study the documentation on the page vimdoc.sourceforge.net . There are more than a hundred links to different files on this page; the description of tasks in them often overlaps: for example, for me editing.html, motion.html, insert.html - all this is as if one continuous “editing”. Some files are not needed at all for finding a solution — for example, comparing versions like version5.html . Some are like a textbook ( usr_NN.html ).

I chose everything more or less related to “reference”, downloaded and decided to somehow organize search-filtering on all the material at once. After processing with sed and bonding, a file of 3.5 megabytes is obtained. The “teams” there turned out to be not 600, but six thousand (with all the pseudonyms and variants - which fit in about four thousand “articles” or “paragraphs”). They managed to find and select everything, because the author of the documentation, Bram Moolenaar, carefully concluded them all in the tags " a name ".

It is by this principle that I divided the entire text of the documentation: one “keyword” (or a group of synonymous terms) is one segment of the text. I wanted to organize “end-to-end” filtering in order to see fragments from different documentation files when searching for an arbitrary word. And not to lose the standard documentation option - when you click on a term or “tag”, jump to the text with the definition (or description) of this term.

To do this, all the material was placed in one large html-table, and then it was organized in a search using Javascript.

Everyone knows that such a large table - 4000 lines, 3.5 megabytes - will barely toggle in the browser. But the eyes are afraid, the hands are doing. Javascript in modern browsers is a very fast language. Much more time is spent on text output on the screen. Therefore, it is not necessary to show the entire table at once.

This is the first simple technique that gives the greatest loading acceleration for a large page — specify the display:none; rule for the table display:none; . An invisible table loads an order of magnitude faster, after which you can slowly create all the necessary indexes. And later, when the user starts the search, we will display only a small part of the table. Sometimes, of course, even more if you enter just one letter in the search field.

To beat the user (that is, first of all, himself) from a long wait, we _Table.tx = 2 two parameters in the filtering script: _Table.tx = 2 - we start searching only if the user has entered at least two letters; _Table.vrows = 100 - show only the first 100 search results (not more).

In Vim, of course, there are commands of two letters, and even of one letter. According to them, it is almost impossible to filter the necessary text, because many common words will be found. So that when searching for the letter of the sought-for terms, they did not mix with “ordinary letters”, we concluded all the “terms” in asterisks (or rather, left these asterisks, as in the source files). To find, for example, the description of the command “B” (capital Latin B), you must enter the letter directly with asterisks in the search field:

It is assumed that with the number of results, for example, 200, a reasonable user will continue filtering to reduce the number of rows found — for example, adding letters to the search field of another column. But if you really want to see all 4000 lines found, you can click the "Show hidden" checkbox.

You can also search for terms and hotkeys using the usual Ctrl+f - all keywords are completely displayed on the page in a separate list on the right, almost like on the site where "all commands are Vim". Only on our page for any word you can click and see the detailed text from the documentation. By Ctrl+f in the list on the right, you can also find commands consisting of one letter - there they are also surrounded by asterisks.

This is the second method of acceleration - the organization of the search for individual lists, and not for all the solid text - for this you need a table with several columns, and, perhaps, a couple of columns outside the table.

The third trick is to not touch the DOM. A search for Javascript is always better to conduct on specially prepared arrays, and not on real DOM nodes.

The fourth technique is “indexing.” We associate a word from the list directly with a specific element of the array by its number. This is something like the primary key . Then when you click on such a word, you can display the necessary information almost instantly - this is how the list of terms on the right works. We can associate a link with several elements of the array, then the search is also accelerated, because there is no search - just strings associated with a set of array elements (something like a one-to-many relationship) are output. This is how the list of “categories” on the left works — there are the names of the source files of the documentation: options, editing, motion ... True, the “acceleration” is not very noticeable when you click, for example, on the vim.eval link, because there are more than five hundred items in this section (lines tables), and they are displayed on the screen for quite a long time (if you, of course, put a tick "Show hidden").

We search for text in Javascript using the indexOf() function — all values ​​in the array are searched and compared with the letters entered for the search. Usually, to search using this method, all values ​​in the search arrays should be reduced to lowercase. But in our case gg is not the same as GG, so the search is made case-sensitive.

***

The documentation in each paragraph contains many links. Of course, these links were not created by hand, and sometimes quite strange things can be found in the files. So, I had to completely delete the links to the motion.as command - because there were more than a thousand such links in the final file (in statements like " same as: map "). I have already decided, the trouble has passed; but suddenly I saw the next set of “noise” links - with the word “do”.

Then I stopped to think that looking for the “freshest” html documentation files is such a good idea. Suppose my Vim is not the most recent, but the documentation still does not change every day. So why, instead of “wget ...”, write cp -R /usr/share/vim/vim74/doc ~/Downloads/vim7/source in the console. And go for the source files far away.

In my vim74 / doc folder there were also more .rux files - translations into Russian. There are a lot of files, and even with different extensions. And in general, the choice of files for search began to be defined a little differently: not “choose everything that looks like a reference”, but remove the obviously non-reference: rm -R usr_*; rm -R version*; rm -R todo* rm -R usr_*; rm -R version*; rm -R todo* rm -R usr_*; rm -R version*; rm -R todo* .

The number of “vim commands” or tags in the right list has increased to 9000. More precisely, it has become even “over 9000”. And some of the tags were not connected with one segment of the text, but with two - English and Russian (if there is a translation). Worse, in my opinion, this is not. True, the number of rows of the table also increased - to "over 8000". But the difference in the speed of the search between a table of 4,000 lines and a table with 8,000 lines to the naked eye is not noticeable.

Vim tags

Looking at the documentation files, I found a "list of Wim commands" in the tags file, but I could not use it in Javascript - I did not understand what could be gained. It can be used earlier when generating html, as the vim2html.pl script in the same folder does, in order to highlight keywords and mark them with html tags a name . But for a search in Javascript it is not exactly “a name” that is needed, any conditional labels are enough (we chose <b> ). And you don’t need such a complex tool like vim2html.pl, - you can place labels using ordinary re-exams, sed'om (the code is given at the end of the article).

Returning to Vim hjkl

While I was unhurriedly sawing in Kate Javascript filtering for Vim's docks, I simultaneously typed this text in Vim. And I received the answer to my first question about jk-navigation only at the very end of work, in five days. In the first approximation, the answer was found quickly - in one of the articles right here on Habré: for the cursor to move along the on-screen lines, not paragraphs, you need to change the key assignment using the map instruction in the ~ / .vimrc file: map k gk , map j gj .

But it was the smallest part of the problem. The big turned out to be in ideology. The hjkl keys, used instead of arrows, are designed to increase the convenience of navigation: do not take your hand away from the main keys - to the arrows. Well, I moved to the right place in the text, pressed i , typed a letter. And then what? How to move further with these jk? If I click on them, they will simply be printed.

We must somehow switch back to the “normal” mode - that is, we must still divert one of the hands from the main keys to the Esc key. It, of course, is easier to click than to move the arrows. But the very fact of frequent switching of modes for minor edits is annoying - any profit is lost.

A wise thought about "map k gk" suggested the next step: imap <Cj> <Esc>gji . And it worked perfectly for almost all four areas. Besides <Cl> , when pressed, Vim for some reason stubbornly refused to do anything. A fresh search for documentation has shown that this default combination is not used anywhere. I went through several options, including all sorts of tricks:

 imap <Cl> <Esc>l map <Cl> li 

And in this last, I suddenly noticed that the keys work somehow through time. Having observed a little more about the behavior of the patient , I found some strange solution that inexplicably turned out to be a worker:

 imap <Cl> <Esc>lli 

***

You can talk a lot about the inner beauty of Javascript and the intricacies of working with tables like table-layout: fixed; , but I'm starting to feel Linus' reproachful look behind me: “Show me the code already!” Here it is, the code for processing the source documentation files:

 cd source rm -R usr_* rm -R version* rm -R todo* for f in *.txt; do n=$(echo "$f" | sed -r 's/\.\w+//'); perl -pe 's/</&lt;/g' <"$f">"$n".html; done; for f in *.rux; do n=$(echo "$f" | sed -r 's/\.\w+//'); perl -pe 's/</&lt;/g' <"$f">"$n"-ru.html; done; for f in *.html; do n=$(echo "$f" | sed -r 's/\.\w+//'); for ((i=0; i < 3; i++)); do sed -i -r "s:\|([^\t ]+)\|:<u>\1</u>:g; s:(^|\t| )(\*[^\t ]+\*)(\t| |$):\1<b>\2</b>\3:g" "$n".html; done; sed -i "/<b>/i<\/pre><\/td><\/tr><tr><td><u>vim.$n<\/u><\/td><td><pre>" "$n".html; done; cat *.html > ../table.htm cd .. sed -i '/vim:tw=78:ts=8:ft=help:norl/d' table.htm cat htm00.htm table.htm endhtm.htm >vim.html 

First we encode in html all opening tags in the text. And at the same time copy the source code to files with a different extension. Then we look for all the words with asterisks and enclose them in tags <b> . The difficulty is not to hook the occurrences of the form ": autocmd BufRead * / doc / *. Txt set tw = 78" - asterisks without keywords. Because of the difficult condition, the search has to be repeated several times, because some contexts overlap. When all the keywords are found and marked, relying on them, it is already possible to divide the future html-table into lines.

Then the files are glued into one, added !DOCTYPE with meta tags, 300 lines of js and 40 lines of css, which can be viewed right inside the final file. Result: Vim docs

PS While modifying the description, I added something to Javascript: 1) double-clicking with the mouse starts the search for the selected word; 2) you can select a few words with the mouse and click to search for F2. 3) Ctrl + Left returns to the previous search result (Ctrl + Right - on the contrary).