Describe boxes integration with vscode

_posts/2018-09-10-notepadplusplus-integration.md

@@ -4,5 +4,5 @@ title: "Notepad++ Integration"
 date: 2018-09-10 22:00:00 +0200
 ---
 
-We put together some [step-by-step instructions]({{ site.baseurl }}/editors.html#notepadplusplus) on how to call
+We put together some [step-by-step instructions]({{ site.baseurl }}/editors-notepadplusplus.html) on how to call
 *boxes* directly from the Notepad++ editor on Windows. It requires a bit of clicking to set up, but works like a charm!

_posts/2021-06-19-vscode-integration.md

@@ -0,0 +1,9 @@
+---
+layout: post
+title: "Visual Studio Code Integration"
+date: 2021-06-19 14:30:00 +0200
+---
+
+Use *boxes* with Visual Studio Code!<br/>
+<a href="{{ site.baseurl }}/editors-vscode.html"><img src="{{ site.baseurl }}/images/vscode-logo.png"
+   class="img-fluid" width="50" height="50" alt="VSCode" /></a>

pages/editors-vscode.md

@@ -0,0 +1,119 @@
+---
+title: Editor Integration - Visual Studio Code
+permalink: editors-vscode.html
+created_at: 2021-06-18 22:00:00 +0200
+last_modified_at: 2021-06-18 22:00:00 +0200
+---
+
+<a href="{{ site.baseurl }}/editors.html"><button type="button" class="btn btn-outline-primary">Back to All Editors</button></a>
+
+
+# Integration with Visual Studio Code
+
+In order to invoke *boxes* from Visual Studio Code, we need a Visual Studio Code plugin that can invoke filter programs.
+Several of those exist. For this example, we use
+[Filter Text](https://marketplace.visualstudio.com/items?itemName=yhirose.FilterText) by *yhirose*. It hasn't been
+updated for a while, but worked fine for us.
+
+1. Install the [Filter Text](https://marketplace.visualstudio.com/items?itemName=yhirose.FilterText) extension into
+   your Visual Studio Code.
+2. In your settings.json, add the following configuration:
+   ```json
+   "filterText.commandList": [
+       {
+           "name": "Boxes Peek (create)",
+           "description": "Add a 'peek' box around selected text",
+           "command": "boxes -d peek -p h1 -s 118 -i none -n UTF-8"
+       },
+       {
+           "name": "Boxes Peek (mend)",
+           "description": "Repair a 'peek' box",
+           "command": "boxes -d peek -p h1 -s 118 -i none -n UTF-8 -m"
+       }
+   ]
+   ```
+   This snippet defines two invocations of *boxes*, one for adding a new box, and one for repairing it.
+   The [options]({{ site.baseurl }}/boxes-man-1.html#OPTIONS) passed to *boxes* do this:
+
+   <table class="table table-striped">
+   <thead>
+       <tr><th scope="col">Option</th><th scope="col">Meaning</th></tr>
+   </thead>
+   <tbody>
+       <tr><td><code>-d peek</code></td>
+           <td>Choose the <code>peek</code> box design.</td></tr>
+       <tr><td><code>-p h1</code></td>
+           <td>Add a space to the left and right of the text. Looks better.</td></tr>
+       <tr><td><code>-s 118</code></td>
+           <td>Always make the box 118 characters wide. The boxes look better when all are the same width.</td></tr>
+       <tr><td><code>-i none</code></td>
+           <td>Do not indent box or text, always start at the left side.</td></tr>
+       <tr><td><code>-n UTF-8</code></td>
+           <td>Tell <i>boxes</i> that the input is UTF-8 encoded text. Adjust if you use a different encoding.</td></tr>
+       <tr><td><code>-m</code></td>
+           <td>Mend box. Tells <i>boxes</i> that we want a repair instead of a new box.</td></tr>
+   </tbody>
+   </table>
+
+   You can add more commands to the JSON to add different boxes, or add a command for removing a box. By using
+   workspace-specific settings.json files, you can even share those commands in your team, and configure different
+   boxes for different projects.
+
+3. Define a [key binding](https://code.visualstudio.com/docs/getstarted/keybindings). Press `Ctrl+Shift+P` or
+   ⇧⌘P (on Mac) to bring up the command palette, then choose *Preferences: Open Keyboard Shortcuts (JSON)*. Add the
+   following JSON:
+
+   ```json
+   [
+       {
+           "key": "ctrl+shift+b",
+           "command": "-workbench.action.tasks.build"
+       },
+       {
+           "key": "ctrl+shift+b",
+           "command": "extension.filterPredefined"
+       }
+   ]
+   ```
+
+   In my case, `Ctrl+Shift+B` was already defined for a build action, so the first entry removes it. Choose any key
+   that suits you.
+
+Done!
+
+
+{% comment %} ---------------------------------------------------------------------------------------- {% endcomment %}
+{% include heading.html
+   level=4
+   text="Example" %}
+
+In order to use this, just select some text:
+
+<img src="{{ site.baseurl}}/images/editor-vscode-filter1.png" class="img-fluid" width="384" height="133"
+     alt="text before filtering" />
+
+Now you can invoke *boxes* by pressing the hotkey (`Ctrl+Shift+B` in the example). This will show the predefined
+commands:
+
+<img src="{{ site.baseurl}}/images/editor-vscode-filter2.png" class="img-fluid" width="403" height="124"
+     alt="text before filtering" />
+
+Select *Boxes Peek (create)*, which gets you the box:
+
+<img src="{{ site.baseurl}}/images/editor-vscode-filter3.png" class="img-fluid" width="384" height="193"
+     alt="text before filtering" />
+
+If you damage the box later by editing in it:
+
+<img src="{{ site.baseurl}}/images/editor-vscode-filter4.png" class="img-fluid" width="384" height="193"
+     alt="text before filtering" />
+
+You can repair it again by selecting the entire broken box:
+
+<img src="{{ site.baseurl}}/images/editor-vscode-filter5.png" class="img-fluid" width="384" height="193"
+     alt="text before filtering" />
+
+And using the *Boxes Peek (mend)* command:
+
+<img src="{{ site.baseurl}}/images/editor-vscode-filter3.png" class="img-fluid" width="384" height="193"
+     alt="text before filtering" />

pages/editors.md

@@ -5,7 +5,7 @@ redirect_from:
   - /docs/install.html
   - /docs/install.shtml
 created_at: 1999-04-06
-last_modified_at: 2021-05-04 22:00:00 +0200
+last_modified_at: 2021-06-18 22:00:00 +0200
 ---
 
 # Text Editor Integration
@@ -16,10 +16,10 @@ afterwards with the output of the external program. Most editors can do that.
 
 Currently, we have concrete instructions on how to integrate *boxes* with the following text editors:
 
-### Vim
+### Emacs
 
-<a href="{{ site.baseurl }}/editors-vim.html"><img src="{{ site.baseurl }}/images/vim-logo.png"
-   class="img-fluid ml-lg-5" width="120" height="120" alt="Vim" /></a>
+<a href="{{ site.baseurl }}/editors-emacs.html"><img src="{{ site.baseurl }}/images/emacs-logo.png"
+   class="img-fluid ml-lg-5" width="200" height="249" alt="Emacs" /></a>
 
 
 ### JED
@@ -28,10 +28,10 @@ Currently, we have concrete instructions on how to integrate *boxes* with the fo
    class="img-fluid ml-lg-5" width="183" height="100" alt="JED" /></a>
 
 
-### Emacs
+### Notepad++
 
-<a href="{{ site.baseurl }}/editors-emacs.html"><img src="{{ site.baseurl }}/images/emacs-logo.png"
-   class="img-fluid ml-lg-5" width="200" height="249" alt="Emacs" /></a>
+<a href="{{ site.baseurl }}/editors-notepadplusplus.html"><img src="{{ site.baseurl }}/images/notepadplusplus-logo.png"
+   class="img-fluid ml-lg-5" width="289" height="120" alt="Notepad++" /></a>
 
 
 ### Sublime Text
@@ -40,10 +40,16 @@ Currently, we have concrete instructions on how to integrate *boxes* with the fo
    class="img-fluid ml-lg-5" width="512" height="60" alt="Sublime Text" /></a>
 
 
-### Notepad++
+### Vim
 
-<a href="{{ site.baseurl }}/editors-notepadplusplus.html"><img src="{{ site.baseurl }}/images/notepadplusplus-logo.png"
-   class="img-fluid ml-lg-5" width="289" height="120" alt="Notepad++" /></a>
+<a href="{{ site.baseurl }}/editors-vim.html"><img src="{{ site.baseurl }}/images/vim-logo.png"
+   class="img-fluid ml-lg-5" width="110" height="110" alt="Vim" /></a>
+
+
+### Visual Studio Code
+
+<a href="{{ site.baseurl }}/editors-vscode.html"><img src="{{ site.baseurl }}/images/vscode-logo.png"
+   class="img-fluid ml-lg-5" width="100" height="100" alt="VSCode" /></a>
 
 
 Let us know if you have a recipe of how to do this for another text editor! You can add to this page via GitHub or just