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
This commit is contained in:
Veronica Berglyd Olsen
committed by
GitHub
GitHub
parent
d7f2fec8ad
commit
6d097f0bcb
@@ -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
|
||||
|
||||
@@ -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 <https://abiword.github.io/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 <https://cgit.freedesktop.org/libreoffice/dictionaries/tree/>`_ 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\<USER>\AppData\Local\enchant\hunspell``
|
||||
|
||||
This assumes your user profile is stored at ``C:\Users\<USER>``. 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 <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/syntax>`_.
|
||||
* The existing GUI themes are stored in
|
||||
`novelwriter/assets/themes <https://github.com/vkbo/novelWriter/tree/main/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 <https://doc.qt.io/qt-5/stylesheet-syntax.html>`_` documentation for more
|
||||
details.
|
||||
@@ -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
|
||||
=================
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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\<USER>\AppData\Local\novelwriter\novelwriter.conf``
|
||||
|
||||
Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ``<USER>`` 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\<USER>\AppData\Roaming\novelwriter\``
|
||||
|
||||
Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ``<USER>`` 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.
|
||||
@@ -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)."
|
||||
|
||||
@@ -278,6 +278,18 @@ class Config:
|
||||
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__)))
|
||||
|
||||
Reference in New Issue
Block a user