From 0719fd857fcad6a16bf40e3604e3ac403a217124 Mon Sep 17 00:00:00 2001 From: Greg Hurrell Date: Thu, 3 Jan 2019 02:44:48 +0100 Subject: [PATCH] doc: prepare for 1.0 release - Add links to screencasts. - Add FAQ explaining why you'd want to use Scalpel. - Update HISTORY. --- README.md | 29 +++++++++++++++++++++++++++++ doc/scalpel.txt | 42 +++++++++++++++++++++++++++++++++++++----- plugin/scalpel.vim | 31 +++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 181999b..6bc2744 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,12 @@ Press `` and Scalpel will prompt to confirm each substitution, starting a Scalpel works similarly in visual mode, except that it scopes itself to the current visual selection rather than operating over the entire file. +Screencasts that show Scalpel in action: + +- https://youtu.be/YwMgnmZNWXA: "Vim screencast #13: Multiple Cursors" +- https://youtu.be/7Bx_mLDBtRc: "Vim screencast #14: *Ncgn" +- https://youtu.be/iNVyCPPYFzc: "Vim screencast #21: Scalpel update" + Note that `:Scalpel` just calls through to an underlying `scalpel#substitute` function that does the real work, ultimately calling Vim's own `:substitute`. As such, be aware that whatever changes you make to the command-line prior to pressing `` must keep it a valid pattern, or bad things will happen. The mapping can be suppressed by setting: @@ -84,6 +90,24 @@ To generate help tags under Pathogen, you can do so from inside Vim with: ``` +## FAQ + + +### Why use Scalpel rather than a built-in alternative? + +Scalpel is a lightweight plug-in that provides subtle but valuable improvements to the experience you'd get by using Vim's built-in functionality. + +Compared to writing a `:substitute` command manually: + +- Scalpel is quickly activated by a mapping. +- Scalpel prepopulates the search pattern with the word currently under the cursor. +- Scalpel avoids a jarring jump to the top of the file, instead starting replacements at the current location. + +Compared to a mapping such as "*Ncgn": + +- Scalpel allows you to preview the location at which each change will occur instead of performing the change blindly. + + ## Website The official Scalpel source code repo is at: @@ -168,6 +192,11 @@ Scalpel is written and maintained by Greg Hurrell <greg@hurrell.net>. ## History +### 1.0 (3 January 2019) + +- Perform multiple replacements per line even when `'gdefault'` is on. + + ### 0.5 (28 July 2018) - Fix problem with `Visual` mode operation on older versions of Vim (GitHub issue #8). diff --git a/doc/scalpel.txt b/doc/scalpel.txt index 3c0b547..d873e71 100644 --- a/doc/scalpel.txt +++ b/doc/scalpel.txt @@ -4,11 +4,12 @@ CONTENTS *scalpel-contents* 1. Intro |scalpel-intro| 2. Installation |scalpel-installation| -3. Website |scalpel-website| -4. License |scalpel-license| -5. Development |scalpel-development| -6. Authors |scalpel-authors| -7. History |scalpel-history| +3. FAQ |scalpel-faq| +4. Website |scalpel-website| +5. License |scalpel-license| +6. Development |scalpel-development| +7. Authors |scalpel-authors| +8. History |scalpel-history| INTRO *scalpel-intro* @@ -28,6 +29,12 @@ the file). Scalpel works similarly in visual mode, except that it scopes itself to the current visual selection rather than operating over the entire file. +Screencasts that show Scalpel in action: + +- https://youtu.be/YwMgnmZNWXA: "Vim screencast #13: Multiple Cursors" +- https://youtu.be/7Bx_mLDBtRc: "Vim screencast #14: *Ncgn" +- https://youtu.be/iNVyCPPYFzc: "Vim screencast #21: Scalpel update" + Note that `:Scalpel` just calls through to an underlying `scalpel#substitute` function that does the real work, ultimately calling Vim's own `:substitute`. As such, be aware that whatever changes you make to the command-line prior @@ -92,6 +99,27 @@ To generate help tags under Pathogen, you can do so from inside Vim with: > :call pathogen#helptags() < +FAQ *scalpel-faq* + +Why use Scalpel rather than a built-in alternative? ~ + +Scalpel is a lightweight plug-in that provides subtle but valuable +improvements to the experience you'd get by using Vim's built-in +functionality. + +Compared to writing a |:substitute| command manually: + +- Scalpel is quickly activated by a mapping. +- Scalpel prepopulates the search pattern with the word currently under the + cursor. +- Scalpel avoids a jarring jump to the top of the file, instead starting + replacements at the current location. + +Compared to a mapping such as "*Ncgn": + +- Scalpel allows you to preview the location at which each change will occur + instead of performing the change blindly. + WEBSITE *scalpel-website* The official Scalpel source code repo is at: @@ -173,6 +201,10 @@ Scalpel is written and maintained by Greg Hurrell . HISTORY *scalpel-history* +1.0 (3 January 2019) ~ + +- Perform multiple replacements per line even when |'gdefault'| is on. + 0.5 (28 July 2018) ~ - Fix problem with |Visual| mode operation on older versions of Vim (GitHub diff --git a/plugin/scalpel.vim b/plugin/scalpel.vim index 0126c10..920946b 100644 --- a/plugin/scalpel.vim +++ b/plugin/scalpel.vim @@ -25,6 +25,12 @@ " Scalpel works similarly in visual mode, except that it scopes itself to the " current visual selection rather than operating over the entire file. " +" Screencasts that show Scalpel in action: +" +" - https://youtu.be/YwMgnmZNWXA: "Vim screencast #13: Multiple Cursors" +" - https://youtu.be/7Bx_mLDBtRc: "Vim screencast #14: *Ncgn" +" - https://youtu.be/iNVyCPPYFzc: "Vim screencast #21: Scalpel update" +" " Note that `:Scalpel` just calls through to an underlying `scalpel#substitute` " function that does the real work, ultimately calling Vim's own `:substitute`. " As such, be aware that whatever changes you make to the command-line prior to @@ -107,6 +113,27 @@ " :call pathogen#helptags() " ``` " +" # FAQ +" +" ## Why use Scalpel rather than a built-in alternative? +" +" Scalpel is a lightweight plug-in that provides subtle but valuable +" improvements to the experience you'd get by using Vim's built-in +" functionality. +" +" Compared to writing a |:substitute| command manually: +" +" - Scalpel is quickly activated by a mapping. +" - Scalpel prepopulates the search pattern with the word currently under the +" cursor. +" - Scalpel avoids a jarring jump to the top of the file, instead starting +" replacements at the current location. +" +" Compared to a mapping such as "*Ncgn": +" +" - Scalpel allows you to preview the location at which each change will occur +" instead of performing the change blindly. +" " # Website " " The official Scalpel source code repo is at: @@ -196,6 +223,10 @@ " " # History " +" ## 1.0 (3 January 2019) +" +" - Perform multiple replacements per line even when |'gdefault'| is on. +" " ## 0.5 (28 July 2018) " " - Fix problem with |Visual| mode operation on older versions of Vim