se windows instructions

1-windows-instructions.md

Setting up a Windows 10 machine to use the StandardEbooks toolset

These instructions provide a base for getting everything working on a windows machine to use the StandardEbooks command line tools.

0.5 (Optional) Install Visual Studio Code

• https://code.visualstudio.com/
• Really nice code editor and fantastic integrated git tooling with extensions.

1. Install GIT

• https://git-scm.com/
• Set Visual Studio Code as the default Editor (if you are using VS Code)
• Set up credentials however you like (default credential cache should be ok, but you're fine to use no credential manager too)

2. Install Java

• https://adoptopenjdk.net/
• Version 16, you only need the JRE, you can also have the JDK
• Download and run the msi.

3. Install GTK 3 Runtime (to create the SVGs cover images as part of the SE toolset)

• https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases/
• You have to tell windows its ok to run this installer (it's unsigned).

4. Install Python 3.9.X (64 bit)

• https://www.python.org/downloads/
• Be sure to tell the installer to add python to your PATH (if you forget or it doesn't tell you, you can change it later if you 'modify' the installation)
• Also, tell it to disable the path length limit
• I used stable version 3.9.2.

5. Install Calibre

• https://calibre-ebook.com/

6. (Optional, but Recommended) Install Visual Studio Build Tools 2019

• https://visualstudio.microsoft.com/visual-cpp-build-tools
• This is not strictly needed as all the python dependencies used by the toolkit as of April 2020 are distributed with python wheels for Windows. But should that change, you will need a compiler installed to build the dependencies.
• It is nearly 6 GB in size!
• See here for details on why you might need a windows compiler for python:
  • https://wiki.python.org/moin/WindowsCompilers#Which_Microsoft_Visual_C.2B-.2B-_compiler_to_use_with_a_specific_Python_version_.3F
• Select C++ build tools under 'desktop & mobile'
  • MSVCv142 - VS 2019 C++ x64/x86 build tools
  • Windows 10 SDK

Reboot your machine.

• You might not need to, but I found it helpful to ensure the env vars are set right.

7. Upgrade Pip and Install Pipx and make sure PATHS are set

1. Open a new terminal (either a new visual studio code instance or straight CMD/powershell/git bash)
2. Run command python -m pip install --upgrade pip
3. Run command python -m pip install --upgrade setuptools
4. Run command python -m pip install --user pipx
5. Run command python -m pipx ensurepath
6. Close Terminal

8. Run pipx install standardebooks

1. Open a new terminal (either a new visual studio code instance or straight CMD/powershell/git bash)
2. Run command pipx install standardebooks

Use it

• Now you can use the all the ```se`` commands from the vs code command line. You can use powershell or git bash or even old cmd.

Useful VS Code Extensions for ebook editing

Almost-Must-Haves:

• GitLens
• Github Pull Requests and Issues
• SVG
• HTML Preview
• Insert Unicode (has a great unicode character search feature)
• Batch Rename
• Bookmarks
• Gremlins (for all those zero-width unicode characters we add to the text)

Nice to have

• macro-commander (Command Runner)
• MetaGo, MetaJump, MetaWord (for wicked fast keyboard navigation)
• Code Spell Checker (spell checker inside vs code - it is not perfect but is a good first-pass)
• Escape HTML Code (for those long descriptions)
• Multiple clipboards for VSCode
• Path Intellisense
• show-offset (for those error messages that don't give a line number)
• Text Pastry
• Zip File Explorer (rename your epub to zip, and you can browse it)

Others

• Rewrap (very useful for PG transcriptions, haven't found a use in SE for this yet)
• Python & Pylance (If you want to develop against the SE tools)

2-macro-commander-macros.md

macro-commander macros for se tools

macro-commander is a VS code extension.

I set up some macros for SE command line tools. Add these to your settings.json file in the macros section. CleanAll and Lint assume that you have opened the root path of your ebook that you are working on in VS code. Other commands are possible as well.

Run the macros by using command palette (ctrl-shift-p) Macros: Run a Macro and selecting it. You can also bind the macros to keys too.

"macros": {
        "SE-TitleCase" : [
            {
                "javascript": [                    
                    "const editor = vscode.window.activeTextEditor;",
                    "if (!editor) { return; }",
                    "const document = editor.document;",
                    "const selection = editor.selection;",
                    "if (!document) { return; }",
                    "const text = document.getText(selection);",
                    "const { execSync } = require('child_process');",
                    "const titlecased = execSync('se titlecase \"' + text + '\"').toString().replace(/^\\s+|\\s+$/g, \"\");",
                    "const rng = new vscode.Range(selection.start, selection.end);",
                    "editor.edit(edit => edit.replace(rng, titlecased));"
                ]
            }
        ],
        "SE-CleanAll" : [
            {
                "injections" : [
                    { "replace": "$root", "withResultOf": "vscode.workspace.rootPath" },
                ],
                "command": "workbench.action.terminal.sendSequence",
                "args": { "text": "se clean $root\\.\n" }
            }
        ],
        "SE-Lint" : [
            {
                "injections" : [
                    { "replace": "$root", "withResultOf": "vscode.workspace.rootPath" },
                ],
                "command": "workbench.action.terminal.sendSequence",
                "args": { "text": "se lint $root\\.\n" }
            }
        ]
    },

3-gremlins-settings.md

gremlins settings for se tools

gremlins is a VS code extension that highlights unicode characters

Useful for seeing the characters that your keyboard doesn't type or are invisible.

"gremlins.characters": {
        "2013": {
            "description": "en dash",
            "level": "info"
        },
        "2014": {
            "description": "em dash",
            "level": "info",
            "hideGutterIcon": true
        },
        "2018": {
            "description": "left single quotation mark",
            "level": "info",
            "hideGutterIcon": true
        },
        "2019": {
            "description": "right single quotation mark",
            "level": "info",
            "hideGutterIcon": true
        },
        "2029": {
            "zeroWidth": true,
            "description": "paragraph separator",
            "level": "error"
        },
        "2060": {
            "zeroWidth": true,
            "description": "word joiner",
            "level": "warning",
            "hideGutterIcon": true
        },
        "0003": {
            "description": "end of text",
            "level": "warning"
        },
        "000b": {
            "description": "line tabulation",
            "level": "warning"
        },
        "00a0": {
            "description": "non breaking space",
            "level": "info"
        },
        "00ad": {
            "description": "soft hyphen",
            "level": "info"
        },
        "200b": {
            "zeroWidth": true,
            "description": "zero width space",
            "level": "error"
        },
        "200c": {
            "zeroWidth": true,
            "description": "zero width non-joiner",
            "level": "warning"
        },
        "200e": {
            "zeroWidth": true,
            "description": "left-to-right mark",
            "level": "error"
        },
        "201c": {
            "description": "left double quotation mark",
            "level": "info",
            "hideGutterIcon": true
        },
        "201d": {
            "description": "right double quotation mark",
            "level": "info",
            "hideGutterIcon": true
        },
        "202c": {
            "zeroWidth": true,
            "description": "pop directional formatting",
            "level": "error"
        },
        "202d": {
            "zeroWidth": true,
            "description": "left-to-right override",
            "level": "error"
        },
        "202e": {
            "zeroWidth": true,
            "description": "right-to-left override",
            "level": "error"
        },
        "fffc": {
            "zeroWidth": true,
            "description": "object replacement character",
            "level": "error"
        }
    },