doc: prepare for 1.0 release

- Add links to screencasts. - Add FAQ explaining why you'd want to use Scalpel. - Update HISTORY.
wincent · Jan 3, 2019 · 0719fd8 · 0719fd8
1 parent c00f46b
commit 0719fd8
Show file tree

Hide file tree

Showing 3 changed files with 97 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -14,6 +14,12 @@ Press `<Enter>` 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: &quot;Vim screencast #13: Multiple Cursors&quot;
+- https://youtu.be/7Bx_mLDBtRc: &quot;Vim screencast #14: *Ncgn&quot;
+- https://youtu.be/iNVyCPPYFzc: &quot;Vim screencast #21: Scalpel update&quot;
+
 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 `<Enter>` 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<a name="scalpel-faq" href="#user-content-scalpel-faq"></a>
+
+
+### Why use Scalpel rather than a built-in alternative?<a name="scalpel-why-use-scalpel-rather-than-a-built-in-alternative" href="#user-content-scalpel-why-use-scalpel-rather-than-a-built-in-alternative"></a>
+
+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 <strong>`:substitute`</strong> 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 &quot;*Ncgn&quot;:
+
+- Scalpel allows you to preview the location at which each change will occur instead of performing the change blindly.
+
+
 ## Website<a name="scalpel-website" href="#user-content-scalpel-website"></a>
 
 The official Scalpel source code repo is at:
@@ -168,6 +192,11 @@ Scalpel is written and maintained by Greg Hurrell &lt;[email protected]&gt;.
 ## History<a name="scalpel-history" href="#user-content-scalpel-history"></a>
 
 
+### 1.0 (3 January 2019)<a name="scalpel-10-3-january-2019" href="#user-content-scalpel-10-3-january-2019"></a>
+
+- Perform multiple replacements per line even when <strong>`'gdefault'`</strong> is on.
+
+
 ### 0.5 (28 July 2018)<a name="scalpel-05-28-july-2018" href="#user-content-scalpel-05-28-july-2018"></a>
 
 - Fix problem with <strong>`Visual`</strong> mode operation on older versions of Vim (GitHub issue #8).

diff --git 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 <[email protected]>.
 
 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
@@ -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