From 6d097f0bcbb9aa532471ca48824b0e8c5f36a6c8 Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Sun, 6 Feb 2022 13:45:30 +0100 Subject: [PATCH] Add customisation help to docs (#984) * Make sure user-defined themes folders exist in the data path * Minor cleanup in shortcuts table * Add details in docs on how to customise GUI and add dictionaries * Add spell check reference in docs overview --- docs/source/index.rst | 2 + docs/source/int_customise.rst | 74 +++++++++++++++++++++++++++++++++ docs/source/int_overview.rst | 2 + docs/source/int_started.rst | 13 ++++-- docs/source/tech_locations.rst | 57 +++++++++++++++++++++++++ docs/source/usage_shortcuts.rst | 16 +++---- novelwriter/config.py | 12 ++++++ 7 files changed, 164 insertions(+), 12 deletions(-) create mode 100644 docs/source/int_customise.rst create mode 100644 docs/source/tech_locations.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index b786d2870..0191425ba 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -54,6 +54,7 @@ too. novelWriter can be run directly from the Python source, installed from the int_overview int_started int_source + int_customise .. toctree:: :maxdepth: 1 @@ -82,5 +83,6 @@ too. novelWriter can be run directly from the Python source, installed from the :caption: Under the Hood :hidden: + tech_locations tech_storage tech_tests diff --git a/docs/source/int_customise.rst b/docs/source/int_customise.rst new file mode 100644 index 000000000..f6bf1c5d5 --- /dev/null +++ b/docs/source/int_customise.rst @@ -0,0 +1,74 @@ +.. _a_custom: + +************** +Customisations +************** + +There are a few ways you can customise novelWriter youself. Currently, you can add new GUI themes, +your own syntax themes, and install additional dictionaries. + + +.. _a_custom_dict: + +Spell Check Dictionaries +======================== + +novelWriter uses `Enchant `_ as the spell checking tool. +Depending on you operating system, it may or may not load installed spell check dictionaries. + +Linux + On Linux, you generally only have to install hunspell or aspell dictionaries on your system like + you do for other applications. See your distro's documentation for how to do this. + +Windows + For Windows, English is included with the installation. For other languages you have to download + and add dictionaries yourself. You can find the various dictionaries on the + `Free Desktop `_ website. You should + find a folder for your language, if it is available at all, and download the files ending with + ``.aff`` and ``.dic``. These files must then be copied to the following location: + + ``C:\Users\\AppData\Local\enchant\hunspell`` + + This assumes your user profile is stored at ``C:\Users\``. The last one or two folders may + not exist, so you may need to create them. + + +.. _a_custom_theme: + +Syntax and GUI Themes +===================== + +Adding your own GUI and syntax themes is relatively easy. The themes are defined by simple plain +text config files with meta data and colour settings. + +In order to make your own versions, first copy one of the existing files to your local computer and +modify it as you like. + +* The existing syntax themes are stored in + `novelwriter/assets/syntax `_. +* The existing GUI themes are stored in + `novelwriter/assets/themes `_. + +Remember to also change the name of your theme by modifying the ``name`` setting at the top of the +file. + +For novelWriter to locate the custom theme files, you must copy them to the :ref:`a_locations_data` +location in your home or user area. There should be a folder there named ``syntax`` for syntax +themes and just ``themes`` for GUI themes. + +Once the files are copied there, they should show up in :guilabel:`Preferences` with the label you +set as ``name`` inside the file. + +Theme CSS Files +--------------- + +If you wish, you can also modify the CSS styles of the GUI in addition to change colour settings. +This is only available for GUI themes, and you do this by creating a file with the exact same file +name as the ``.conf`` file with colour settings and give it the ``.qss`` extension. + +On Windows, file extensions may not be visible by default, so make sure you only have one file +extension, and don't end up with two. + +The QSS files are Qt Style Sheet files. See Qt's +`The Style Sheet Syntax `_` documentation for more +details. diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst index 56f2b1a57..38484562d 100644 --- a/docs/source/int_overview.rst +++ b/docs/source/int_overview.rst @@ -21,6 +21,8 @@ applications. For install instructions, see :ref:`a_started`. +For information on how to add spell check dictionaries, see :ref:`a_custom_dict`. + Using novelWriter ================= diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index e2eeaffb0..ebe9b8fea 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -4,22 +4,27 @@ Getting Started *************** +.. _brew docs: https://docs.brew.sh/Homebrew-and-Python +.. _Enchant: https://abiword.github.io/enchant/ .. _GitHub: https://github.com/vkbo/novelWriter -.. _Releases: https://github.com/vkbo/novelWriter/releases -.. _RPM: https://github.com/vkbo/novelWriter/issues/907 .. _macOS: https://github.com/vkbo/novelWriter/issues/867 .. _main website: https://novelwriter.io .. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter .. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre -.. _python.org: https://www.python.org/downloads/windows -.. _brew docs: https://docs.brew.sh/Homebrew-and-Python .. _PyPi: https://pypi.org/project/novelWriter/ +.. _python.org: https://www.python.org/downloads/windows +.. _Releases: https://github.com/vkbo/novelWriter/releases +.. _RPM: https://github.com/vkbo/novelWriter/issues/907 If you are using Windows or a Debian-based Linux distribtuion, you can install novelWriter from package installers. If you are on macOS, you have the option to run novelWriter from a standalone folder. See :ref:`a_started_minimal`. This option is also available for Windows and Linux. The third option is to install novelWriter from the Python Package Index. See :ref:`a_started_pip`. +Spell checking in novelWriter is provided by a third party library called Enchant_. Generally, it +should pull dictionaries from your operating system automatically. However, on Windows they must be +installed manually. See :ref:`a_custom_dict` for more details. + .. admonition:: Help Wanted :class: seealso diff --git a/docs/source/tech_locations.rst b/docs/source/tech_locations.rst new file mode 100644 index 000000000..8f1d4db6b --- /dev/null +++ b/docs/source/tech_locations.rst @@ -0,0 +1,57 @@ +.. _a_locations: + +************** +File Locations +************** + +.. _QStandardPaths: https://doc.qt.io/qt-5/qstandardpaths.html + +novelWriter will create a few files on your system outside of the application folder itself. These +file locations are described in this document. + + +.. _a_locations_conf: + +Configuration +============= + +The general configuration of novelWriter, including everything that is in :guilabel:`Preferences`, +is saved in one central configuration file. The location of this file depends on your operating +system. The system paths are provided by the Qt QStandardPaths_ class and its ConfigLocation value. + +The standard paths are: + +* Linux: ``~/.config/novelwriter/novelwriter.conf`` +* macOS: ``~/Library/Preferences/novelwriter/novelwriter.conf`` +* Windows: ``C:\Users\\AppData\Local\novelwriter\novelwriter.conf`` + +Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ```` is the +user's username on Windows. + +.. note:: + These are the standard operating system defined locations. If your system has been set up in a + different way, these locations may also be different. + + +.. _a_locations_data: + +Application Data +================ + +novelWriter also stores a bit of data that is generated by the user's actions. This includes the +list of recent projects form the :guilabel:`Open Project` dialog. Custom themes are also saved +here. The system paths are provided by the Qt QStandardPaths_ class and its AppDataLocation value +on Qt 5.4 or greater, or DataLocation for earlier versions. + +The standard paths are: + +* Linux: ``~/.local/share/novelwriter/`` +* macOS: ``~/Library/Application Support/novelwriter/`` +* Windows: ``C:\Users\\AppData\Roaming\novelwriter\`` + +Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ```` is the +user's username on Windows. + +.. note:: + These are the standard operating system defined locations. If your system has been set up in a + different way, these locations may also be different. diff --git a/docs/source/usage_shortcuts.rst b/docs/source/usage_shortcuts.rst index 862b48fb4..fea65c8c8 100644 --- a/docs/source/usage_shortcuts.rst +++ b/docs/source/usage_shortcuts.rst @@ -16,7 +16,7 @@ The main shorcuts are as follows: .. csv-table:: Keyboard Shortcuts :header: "Shortcut", "Description" - :widths: 25, 75 + :widths: 20, 80 :class: "tight-table" ":kbd:`Alt`:kbd:`1`", "Switch focus to the project tree. On Windows, use :kbd:`Ctrl`:kbd:`Alt`:kbd:`1`." @@ -42,9 +42,9 @@ The main shorcuts are as follows: ":kbd:`Ctrl`:kbd:`B`", "Format selected text, or word under cursor, with strong emphasis (bold)." ":kbd:`Ctrl`:kbd:`C`", "Copy selected text to clipboard." ":kbd:`Ctrl`:kbd:`D`", "Strikethrough selected text, or word under cursor." - ":kbd:`Ctrl`:kbd:`E`", "If in the project tree, edit a document or folder settings. (Same as :kbd:`F2`.)" + ":kbd:`Ctrl`:kbd:`E`", "If in the project tree, edit a document or folder settings." ":kbd:`Ctrl`:kbd:`F`", "Open the search bar and search for the selected word, if any is selected." - ":kbd:`Ctrl`:kbd:`G`", "Find next occurrence of search word in current document. (Same as :kbd:`F3`.)" + ":kbd:`Ctrl`:kbd:`G`", "Find next occurrence of search word in current document." ":kbd:`Ctrl`:kbd:`H`", "Open the search and replace bar and search for the selected word, if any is selected. (On Mac, this is :kbd:`Cmd`:kbd:`=`.)" ":kbd:`Ctrl`:kbd:`I`", "Format selected text, or word under cursor, with emphasis (italic)." ":kbd:`Ctrl`:kbd:`K`", "Activate the insert commands. The commands are listed in :ref:`a_kb_ins`." @@ -71,7 +71,7 @@ The main shorcuts are as follows: ":kbd:`Ctrl`:kbd:`Shift`:kbd:`/`", "Remove block formatting for block under cursor." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`1`", "Replace occurrence of search word in current document, and search for next occurrence." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`A`", "Select all text in current paragraph." - ":kbd:`Ctrl`:kbd:`Shift`:kbd:`G`", "Find previous occurrence of search word in current document. (Same as :kbd:`Shift`:kbd:`F3`.)" + ":kbd:`Ctrl`:kbd:`Shift`:kbd:`G`", "Find previous occurrence of search word in current document." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`I`", "Import text to the current document from a text file." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`N`", "Create new folder." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`O`", "Open a project." @@ -81,8 +81,8 @@ The main shorcuts are as follows: ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`", "Undo move of project tree item." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`", "If in the project tree, move a document to trash, or delete a folder." ":kbd:`F1`", "Open the online user manual." - ":kbd:`F2`", "If in the project tree, edit a document or folder settings. (Same as :kbd:`Ctrl`:kbd:`E`)" - ":kbd:`F3`", "Find next occurrence of search word in current document. (Same as :kbd:`Ctrl`:kbd:`G`)" + ":kbd:`F2`", "If in the project tree, edit a document or folder settings." + ":kbd:`F3`", "Find next occurrence of search word in current document." ":kbd:`F5`", "Open the :guilabel:`Build Novel Project` dialog." ":kbd:`F6`", "Open the :guilabel:`Writing Statistics` dialog." ":kbd:`F7`", "Re-run spell checker." @@ -91,7 +91,7 @@ The main shorcuts are as follows: ":kbd:`F10`", "Re-build the project outline." ":kbd:`F11`", "Activate full screen mode." ":kbd:`Shift`:kbd:`F1`", "Open the local user manual (PDF) if it is available." - ":kbd:`Shift`:kbd:`F3`", "Find previous occurrence of search word in current document. (Same as :kbd:`Ctrl`:kbd:`Shift`:kbd:`G`.)" + ":kbd:`Shift`:kbd:`F3`", "Find previous occurrence of search word in current document." ":kbd:`Shift`:kbd:`F6`", "Open the :guilabel:`Project Details` dialog." ":kbd:`Return`", "If in the project tree, open a document for editing." @@ -110,7 +110,7 @@ a key or key combination for the inserted content. .. csv-table:: Keyboard Shortcuts :header: "Shortcut", "Description" - :widths: 25, 75 + :widths: 30, 70 :class: "tight-table" ":kbd:`Ctrl`:kbd:`K`, :kbd:`−`", "Insert a short dash (en dash)." diff --git a/novelwriter/config.py b/novelwriter/config.py index e063991ab..c5159493e 100644 --- a/novelwriter/config.py +++ b/novelwriter/config.py @@ -278,6 +278,18 @@ def initConfig(self, confPath=None, dataPath=None): logger.verbose("Config path: %s", self.confPath) logger.verbose("Data path: %s", self.dataPath) + # Check Data Path Subdirs + dataDirs = ["syntax", "themes"] + for dataDir in dataDirs: + dirPath = os.path.join(self.dataPath, dataDir) + if not os.path.isdir(dirPath): + try: + os.mkdir(dirPath) + logger.info("Created folder: %s", dirPath) + except Exception: + logger.error("Could not create folder: %s", dirPath) + logException() + self.confFile = self.appHandle+".conf" self.lastPath = os.path.expanduser("~") self.appPath = getattr(sys, "_MEIPASS", os.path.abspath(os.path.dirname(__file__)))