Run Manuskript from Source Code on Windows - olivierkes/manuskript GitHub Wiki

SUMMARY

This guide describes the steps for installing and running Manuskript from source code on Windows.

The steps include installing all necessary software dependencies.

These steps were developed on 32 bit Windows XP and also tested on 64 bit Windows 7 (see also Appendix A near bottom). The steps should work as is or as a guideline for newer version of Windows.

Text based commands in this guide should be run in a command prompt.

Open Command Prompt

Following are some ways to invoke a command prompt in Windows:

  • Use menu option Start -> All Programs -> Accessories -> Command Prompt
  • Simultaneously press Windows + R keys on keyboard to open launcher, type cmd.exe and press Enter key.

INSTALLATION

Install Required Software Packages

Manuskript is written in the Python (v3) programming language and uses the QT (v5) cross-platform UI framework and also requires some additional software.

Download and install the following software:

Python v3.x

Download Python v3.4.4 - Windows x86 MSI installer and run the installer accepting all defaults.
https://www.python.org/downloads/windows/
Python v3.4.4 is the last version that works with Windows XP.

PyQT v5.x

Download PyQt v5.5.1 for python v3.4 Windows 32 bit installer and run the installer accepting all defaults.
https://sourceforge.net/projects/pyqt/files/PyQt5/
PyQt v5.5.1 is the last version that works with Windows XP and Python v3.4.x

Note that 64 bit versions and newer versions are available from
https://www.riverbankcomputing.com/software/pyqt/download5

LXML

Download lxml-3.4.4.win32-py3.4.exe and run the installer accepting all defaults.
https://pypi.python.org/pypi/lxml/3.4.4/

Spell checker libraries (Optional - provides spell checking functionality)

Why does Manuskript support so many of spell checker libraries, you might wonder. Simply put: they all have their pros and cons, and what is best for me may not be best for you.

You ideally want to install at least one to keep the typos at bay.

All of them exist as modules that are easily installed through pip, the python package manager.

This can be done as follows:

  1. Open a command prompt as described earlier.

  2. Change to the C:\Python34\Scripts directory.

    C:
cd \Python34\Scripts

  3. Install module(s) using pip. You can find the command for your chosen spellchecker(s) below.

  4. Close command prompt.

The spell checkers that manuskript supports are as follows:

  • PyEnchant [Recommended for all except 64-bit Python on Windows]

    PyEnchant is perhaps the most traditional spellchecker in that it interacts with the Enchant library written by Dom Lachowicz. Unfortunately, PyEnchant is no longer maintained by anyone, and this causes a problem: it currently cannot be installed on 64-bit versions of Python on Windows.

    Install it using: pip install pyenchant

    At time of writing v1.6.8 was installed. You can specify this version with the pip install pyenchant==1.6.8 command.

    The following dictionaries were automatically installed with PyEnchant: de_DE, en_AU, en_GB, en_US, and fr_FR.

  • PySpellChecker

    PySpellChecker is a pure-Python implementation of a spell checker that uses the Levenshtein Distance algorithm. It should work on all systems and comes with dictionaries generated using the WordFrequency project for several popular languages. The drawback? It tends to be rather slow.

    Install it using: pip install pyspellchecker

    At time of writing v0.5.0 was installed. You can specify this version with the pip install pyspellchecker==0.5.0 command.

    It includes dictionaries for English, Spanish, German, French and Portuguese.

  • Symspellpy

    Symspellpy is a Python port of SymSpell. Despite not being optimized for speed (according to the project description), it is considerably faster than PySpellChecker when operating on the same dictionaries. It does not come with any dictionaries of its own, but if pyspellchecker is installed, Manuskript will use those in conjunction with symspellpy.

    Install it using: pip install symspellpy

    At time of writing v6.3.9 was installed. You can specify this version with the pip install symspellpy==6.3.9 command.

    It does not include any dictionaries.

    See also Issue 614 - Comments on 'Run from Source Code' wiki page and Spell Checker documentation for more information on spell checkers.

MarkDown (Optional - provides Manuskript export as HTML)

Use steps similar to those above to install a spell checker.

  • Install MarkDown using pip.

    pip install markdown

    At time of writing v2.6.8 was installed. You can specify this version with the pip install markdown==2.6.8 command.

Pandoc (Optional - provides more Compile/Export formats)

To access additional compile/export formats, such as ePub, OpenDocument and DocX, download and install pandoc.

At time of writing pandoc v1.19.2.1 was installed.

Install Git and Manuskript

The source code for Manuskript is managed with the git distributed version control system, and hence we need git to be able to clone a copy of the source code.

Install Git

Download Git-v2.10.0-32-bit.exe and run the installer accepting all defaults.
https://github.com/git-for-windows/git/releases/tag/v2.10.0.windows.1
Git v2.10.0 is the last version to support Windows XP.

Download Manuskript Source Code

  1. Open a command prompt as described earlier.

  2. Choose and change to a directory to install the source code. For example, your C:\ directory:

    C:
cd \

  3. Use git to clone a copy of the source code your chosen directory.

    git clone https://github.com/olivierkes/manuskript.git

    The above command will create a manuskript subdirectory.

  4. Change into the manuskript subdirectory.

    cd manuskript

At any time after you have cloned the source code, you can update your copy to the latest version with the git pull command.

Optional: Switch to the develop Branch (latest unreleased version)

git checkout develop

Note that you can return to the master branch with the git checkout master command.

EXECUTION

Run manuskript from Source Code

Enter the following command in a command prompt, or Win+R launcher:

C:\Python34\python "C:\manuskript\bin\manuskript"

Note that the above command requires the full directory path to the location in which you installed manuskript.

Appendix A: Install Required Software Packages on Windows 7 and Higher

If you are running Windows 7 or higher, you may wish to install more recent software to run Manuskript. Following are the steps I used to install the required software packages for Manuskript on 64-bit Windows 7 (also tested on Windows 10).

  1. Download Python 3.7.2 - Windows x86 executable installer file.

    In Windows Explorer (Windows + E keys) find python-3.7.2.exe in the Downloads folder and double-click.

    Be sure to enable "Add Python to PATH".

    I chose a custom install with the path C:\Python37, and chose Install for all users.

    NOTE: When I installed Python 3.7.2 on Windows 10 a dialog window at the end indicates that the installation can remove the MAX_PATH limit if so desired. This makes a change to your Windows configuration, more specifically the registry. If you plan to use long chapter and scene names then you might consider disabling the MAX_PATH length limit to avoid issue #313 - Main program does not load (FileNotFound error) - filename path too long > 260 chars.

    python3 7 2-install-on-windows10-max-path

  2. Install PyQt5, Lxml, PyEnchant (optional spell check), and Markdown (optional HTML export).

    Open a command prompt as described earlier.

    pip install pyqt5 lxml pyenchant markdown

  3. Install Git and Manuskript, and optionally Pandoc as described earlier.