README enhancements #1547

cobbweb · 2017-04-21T13:47:28Z

A few README enhancements. Mostly re-arranging things and, fixing up formatting and consistency problems, including:

Add logo to header and center align it
Add Contents section
Tighten up Features list
Add OS-specific setup notes
Promote plugins to their own section
Fix up various Markdown and indentation issues
Add syntax highlighting to JSON examples
Improve heading consistency (use "sentence case")
Make settings-based headings look like their JSON key equivalents
Prefer the language "settings" over "option" or "configuration" where possible.

Sorry for all the commits, happy to squash them once this is good to merge. I'd like to have another pass at proofreading over the weekend too. Let me know if there's anything you want removed/revert/fixed 👍

Thanks for an awesome plugin too

xconverge · 2017-04-21T14:28:22Z

Can you add the recent lightline plugin information? Sorry I think I added that since you branched :)

cobbweb · 2017-04-21T21:46:41Z

@xconverge Are you talking about the status bar colors? That's in there, but under Settings. I didn't want to put it under 'Emulated plugins', as the other under emulated plugins have really good feature parity. Happy to move it if you want, but I thought it could be a bit misleading.

jpoon

Thanks for the PR!

jpoon · 2017-04-21T22:05:23Z

README.md

@@ -1,19 +1,35 @@
-# Vim [![Version](http://vsmarketplacebadge.apphb.com/version/vscodevim.vim.svg)](http://aka.ms/vscodevim) [![Build Status](https://travis-ci.org/VSCodeVim/Vim.svg?branch=master)](https://travis-ci.org/VSCodeVim/Vim) [![Slack Status](https://vscodevim-slackin.azurewebsites.net/badge.svg)](https://vscodevim-slackin.azurewebsites.net)
+<h1 align="center">


I'm not a big fan of embedding HTML into the markdown

Yea I get it's not ideal from purity standpoint, but we're not the first to do this.
It's supported by Github and the VSCode marketplace.

jpoon · 2017-04-21T22:06:23Z

README.md

-## Special Shoutouts to Cool Contributors
+## F.A.Q.
+
+### `j`, `k` and others keys don't repeat when I hold them down.


You had this covered in the Mac setup? Maybe delete it from here.

I thought it might be be worth leaving it duplicated for a little while? I know I've linked to this section before getting friends up-to-speed. Happy to remove though.

Or reference a link to the Mac setup.

jpoon · 2017-04-21T22:08:17Z

README.md


-## Configuring VSCodeVim
+* [Quick example settings](#quick-example-settings)


I think quick example settings should fall under the settings category.

Mac/Windows setup could be under it's own setup/getting started category.

Yea good idea, I knew this section was 'off'. I'll move the quick settings into Settings, and rename this to 'Getting started', and might even include some links to some vim learning resources?

rebornix · 2017-04-22T00:08:47Z

README.md


 VSCodeVim is a [Visual Studio Code](https://code.visualstudio.com/) extension that enables Vim keybindings, including:

-* Modes: normal, insert, command, visual, visual line, visual block (with `useCtrlKeys`, see below)
+* Modes: normal, insert, command-line, visual, visual line, visual block


we may want to use command, AFAIK it's referring to ex-command.

I changed it in case there was any confusion with the next point: "Command combinations". It's also called command-line mode in the vim docs.

rebornix · 2017-04-22T00:10:24Z

README.md

@@ -51,14 +87,14 @@ Below is an example of a [settings.json](https://code.visualstudio.com/Docs/cust
            "after": ["d", "d"]
        },
        {
-           "before":["<C-n>"],
-           "after":[],
+            "before":["<C-n>"],


Let's keep using 2 spaces.

rebornix · 2017-04-22T00:11:29Z

README.md

-       ]
-   }
+    {
+        "before": [":"],


same here, I suppose it's changed by some indenting or formatting?

The indentation was all whacky, I re-indented it all so it was consistent. (I think there was 3 spaces here)

rebornix · 2017-04-22T00:13:55Z

Just a few tiny suggestions, it looks good to me and it's way way awesome.

jpoon · 2017-04-22T07:17:46Z

Also, while you are at this, mind taking care of this? #1466

cobbweb · 2017-04-23T07:20:41Z

Ok pushed a few extra bits:

Added a Getting started section to house the OS-specific setup. I also add some new words, but I think it's just waffling and that I should probably remove it again?
Added a small sub-section regarding Vim compatibility, with another link to the roadmap (there's already one in the features list)
Removed the duplicate info about key-repeat on Macs

jpoon · 2017-04-23T08:36:47Z

One last thing, mind squashing?

xconverge · 2017-04-23T16:20:41Z

We can squash when we merge too...not a big deal

xconverge · 2017-04-23T16:23:14Z

README.md

+
+### Vim compatibility
+
+All common Vim commands are supported. For an in-depth look at what Vim features are supported, check out the [roadmap](ROADMAP.md). Vimscript isn't supported, so you aren't able to load your `.vimrc` or use `.vim` plugins. You have to replicated this using our [Settings](#settings) and [Emulated plugins](#emulated-plugins).


small grammar issue in last sentence "you have to replicate these"

johnfn · 2017-04-23T16:59:51Z

Sorry, not going to have the time to review this this weekend, but I'm sure I can just merge in changes directly if I notice anything is horribly wrong. :) (Which I doubt.)

The HTML is supported in the VS Code Marketplace site too, and this is layout is shamelessly stolen from the Chrome Debugger plugin: https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome

This what their repos are named, and make our README look more consistent.

It's enabled by default, and so isn't really a feature.

* Re-arrange certain sections based on importance * Promoted plugin info to it's own section * Add contents * Bunch of other small formatting tweaks

They're outlined nicely in the contents area just below, seems like overkill to have them all listed here too.

The tricks list is cooler (read: more important)

And clean up extra closing backticks

This is in-line with terminology in VSCode (i.e. `settings.json`).

And move `useCtrlKeys` and `handleKeys` into VSCodeVim Settings.

The stuff between the <...> was getting drop because Markdown parsers think that it's HMTL tags ;)

It didn't make sense to have Settings-related info here. The quick example settings has been more to the start of the Settings section.

xconverge · 2017-04-24T00:26:22Z

Thanks a ton! This looks great and is definitely a solid start to build on!

mightyiam · 2017-04-25T10:03:43Z

Thank you so much!

* Reformat the heading (add logo, centered styling) The HTML is supported in the VS Code Marketplace site too, and this is layout is shamelessly stolen from the Chrome Debugger plugin: https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome * Normalize how we reference the real Vim plugins This what their repos are named, and make our README look more consistent. * Remove reference to useCtrlKeys in features list It's enabled by default, and so isn't really a feature. * Bulk refactoring of README * Re-arrange certain sections based on importance * Promoted plugin info to it's own section * Add contents * Bunch of other small formatting tweaks * Simply plugins point in features They're outlined nicely in the contents area just below, seems like overkill to have them all listed here too. * Add Contents link to status bar customization (vim-airline) * Push FAQ further down the page The tricks list is cooler (read: more important) * Additional language/linking tweaks * Add 'json' language to code blocks And clean up extra closing backticks * Prefer "setting" over "option" or "configuration" This is in-line with terminology in VSCode (i.e. `settings.json`). * Fix heading numbers and use Sentence case * Fix formatting and indentation issues * Move Key remppaing under settings And move `useCtrlKeys` and `handleKeys` into VSCodeVim Settings. * Add OS-specific setup sub-sections * More heading tweaks * Add more links to useCtrlKeys and handleKeys * Fix formatting with backticks The stuff between the <...> was getting drop because Markdown parsers think that it's HMTL tags ;) * Fix typo * More heading level and case fixes * Add quick-link to `gc` docs * Format VSCode Vim tricks list consistently * Test: backticks around settings headings * Make setting's headings map to JSON keys * Fix Contents link to Emulated plugins * Tweaks to Contributing and Release notes * Tight up features some more * Introduce "Getting started" section with OS-setup info It didn't make sense to have Settings-related info here. The quick example settings has been more to the start of the Settings section. * Add sub-section on compatibility with link to ROADMAP * Remove duplicate info about key repeat issues on Mac * Tweak waffling * Small grammar fix

Enkdress · 2020-06-23T20:07:28Z

README.md

+* `gq` - on a visual selection - Reflow and wordwrap blocks of text, preserving commenting style. Great for formatting documentation comments.
+* `gc` - which adds another cursor on the next word it finds which is the same as the word under the cursor.
+* `af` - a command that I added in visual mode, which selects increasingly large blocks of text. e.g. if you had "blah (foo [bar 'ba|z'])" then it would select 'baz' first. If you pressed `af` again, it'd then select [bar 'baz'], and if you did it a third time it would select "(foo [bar 'baz'])".
+* `gh` - another custom VSCodeVim command. This one is equivalent to hovering your mouse over wherever the cursor is. Handy for seeing types and error messages without reaching for the mouse!


Can I have this feature in nvim with any plugin or something like that

Haven't used nvim seriously for a while but this might be useful: https://neovim.io/doc/user/lsp.html

cobbweb force-pushed the feature/improve-readme-structure branch from 3a84a7c to aa1aed8 Compare April 21, 2017 21:31

jpoon requested changes Apr 21, 2017

View reviewed changes

rebornix reviewed Apr 22, 2017

View reviewed changes

jpoon approved these changes Apr 23, 2017

View reviewed changes

xconverge reviewed Apr 23, 2017

View reviewed changes

Andrew Cobby added 15 commits April 24, 2017 09:35

Reformat the heading (add logo, centered styling)

a772d03

The HTML is supported in the VS Code Marketplace site too, and this is layout is shamelessly stolen from the Chrome Debugger plugin: https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome

Normalize how we reference the real Vim plugins

a52b4bc

This what their repos are named, and make our README look more consistent.

Remove reference to useCtrlKeys in features list

2be9c75

It's enabled by default, and so isn't really a feature.

Bulk refactoring of README

b2f999d

* Re-arrange certain sections based on importance * Promoted plugin info to it's own section * Add contents * Bunch of other small formatting tweaks

Simply plugins point in features

016851c

They're outlined nicely in the contents area just below, seems like overkill to have them all listed here too.

Add Contents link to status bar customization (vim-airline)

b24ef85

Push FAQ further down the page

7579410

The tricks list is cooler (read: more important)

Additional language/linking tweaks

322abc3

Add 'json' language to code blocks

807776e

And clean up extra closing backticks

Prefer "setting" over "option" or "configuration"

aeb68fc

This is in-line with terminology in VSCode (i.e. `settings.json`).

Fix heading numbers and use Sentence case

558bfe7

Fix formatting and indentation issues

50e07fe

Move Key remppaing under settings

16af161

And move `useCtrlKeys` and `handleKeys` into VSCodeVim Settings.

Add OS-specific setup sub-sections

fe4f604

More heading tweaks

4981595

Andrew Cobby added 16 commits April 24, 2017 09:35

Add more links to useCtrlKeys and handleKeys

3c729ee

Fix formatting with backticks

9c7c34c

The stuff between the <...> was getting drop because Markdown parsers think that it's HMTL tags ;)

Fix typo

f42b57d

More heading level and case fixes

3a81c39

Add quick-link to gc docs

205e5a1

Format VSCode Vim tricks list consistently

541bebb

Test: backticks around settings headings

65bdc2f

Make setting's headings map to JSON keys

7cd023d

Fix Contents link to Emulated plugins

5ba9411

Tweaks to Contributing and Release notes

905a492

Tight up features some more

bbb1c79

Introduce "Getting started" section with OS-setup info

f8d030f

It didn't make sense to have Settings-related info here. The quick example settings has been more to the start of the Settings section.

Add sub-section on compatibility with link to ROADMAP

5158006

Remove duplicate info about key repeat issues on Mac

e1d3406

Tweak waffling

01b4150

Small grammar fix

33a9e9b

cobbweb force-pushed the feature/improve-readme-structure branch from cde0f96 to 33a9e9b Compare April 23, 2017 23:35

xconverge merged commit d3758c3 into VSCodeVim:master Apr 24, 2017

cobbweb deleted the feature/improve-readme-structure branch April 24, 2017 00:27

Enkdress reviewed Jun 23, 2020

View reviewed changes

This pull request was closed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README enhancements #1547

README enhancements #1547

cobbweb commented Apr 21, 2017 •

edited

Loading

xconverge commented Apr 21, 2017

cobbweb commented Apr 21, 2017

jpoon left a comment •

edited

Loading

jpoon Apr 21, 2017

cobbweb Apr 21, 2017

jpoon Apr 21, 2017

cobbweb Apr 21, 2017

jpoon Apr 22, 2017 •

edited

Loading

jpoon Apr 21, 2017 •

edited

Loading

cobbweb Apr 21, 2017

rebornix Apr 22, 2017 •

edited

Loading

cobbweb Apr 23, 2017

rebornix Apr 22, 2017

rebornix Apr 22, 2017

cobbweb Apr 23, 2017 •

edited

Loading

rebornix commented Apr 22, 2017

jpoon commented Apr 22, 2017

cobbweb commented Apr 23, 2017

jpoon commented Apr 23, 2017

xconverge commented Apr 23, 2017

xconverge Apr 23, 2017

cobbweb Apr 23, 2017

johnfn commented Apr 23, 2017

xconverge commented Apr 24, 2017

mightyiam commented Apr 25, 2017

Enkdress Jun 23, 2020

J-Fields Jun 23, 2020

		@@ -1,19 +1,35 @@
		# Vim [![Version](http://vsmarketplacebadge.apphb.com/version/vscodevim.vim.svg)](http://aka.ms/vscodevim) [![Build Status](https://travis-ci.org/VSCodeVim/Vim.svg?branch=master)](https://travis-ci.org/VSCodeVim/Vim) [![Slack Status](https://vscodevim-slackin.azurewebsites.net/badge.svg)](https://vscodevim-slackin.azurewebsites.net)
		<h1 align="center">


		## Configuring VSCodeVim
		* [Quick example settings](#quick-example-settings)


		### Vim compatibility

		All common Vim commands are supported. For an in-depth look at what Vim features are supported, check out the [roadmap](ROADMAP.md). Vimscript isn't supported, so you aren't able to load your `.vimrc` or use `.vim` plugins. You have to replicated this using our [Settings](#settings) and [Emulated plugins](#emulated-plugins).

README enhancements #1547

README enhancements #1547

Conversation

cobbweb commented Apr 21, 2017 • edited Loading

xconverge commented Apr 21, 2017

cobbweb commented Apr 21, 2017

jpoon left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jpoon Apr 22, 2017 • edited Loading

Choose a reason for hiding this comment

jpoon Apr 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rebornix Apr 22, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cobbweb Apr 23, 2017 • edited Loading

Choose a reason for hiding this comment

rebornix commented Apr 22, 2017

jpoon commented Apr 22, 2017

cobbweb commented Apr 23, 2017

jpoon commented Apr 23, 2017

xconverge commented Apr 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnfn commented Apr 23, 2017

xconverge commented Apr 24, 2017

mightyiam commented Apr 25, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cobbweb commented Apr 21, 2017 •

edited

Loading

jpoon left a comment •

edited

Loading

jpoon Apr 22, 2017 •

edited

Loading

jpoon Apr 21, 2017 •

edited

Loading

rebornix Apr 22, 2017 •

edited

Loading

cobbweb Apr 23, 2017 •

edited

Loading