diff --git a/docs/source/index.rst b/docs/source/index.rst index 8e863ff8..793d1d38 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -75,6 +75,7 @@ storage for robustness. more/counting more/typography + more/dictionaries more/customise more/handling_errors more/project_format diff --git a/docs/source/more/customise.rst b/docs/source/more/customise.rst index 80aa1201..8f3d2f60 100644 --- a/docs/source/more/customise.rst +++ b/docs/source/more/customise.rst @@ -1,94 +1,35 @@ .. _docs_more_custom: -************** -Customisations -************** +************* +Custom Themes +************* -.. _Enchant: https://rrthomas.github.io/enchant/ -.. _Free Desktop: https://cgit.freedesktop.org/libreoffice/dictionaries/tree/ - -There are a few ways you can customise novelWriter yourself. Currently, you can add new GUI themes, -your own syntax themes, and install additional dictionaries. - - -.. _docs_more_custom_dict: - -Spell Check Dictionaries -======================== - -novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or -may not load all installed spell check dictionaries automatically. - - -Linux and MacOS ---------------- - -On Linux and MacOS, you generally only have to install hunspell, aspell or myspell dictionaries on -your system like you do for other applications. See your distro or OS documentation for how to do -this. These dictionaries should show up as available spell check languages in novelWriter. - - -Windows -------- - -For Windows, English is included with the installation. For other languages you have to download -and add dictionaries yourself. - -**Install Tool** - -A small tool to assist with this can be found under **Tools > Add Dictionaries**. It will import -spell checking dictionaries from Free Office or Libre Office extensions. The dictionaries are then -installed in the install location for the Enchant library and should thus work for any application -that uses Enchant for spell checking. - -**Manual Install** - -If you prefer to do this manually or want to use a different source than the ones mentioned above, -You need to get compatible dictionary files for your language. You need two files 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. - -You can find the various dictionaries on the `Free Desktop`_ website. - -.. note:: - The Free Desktop link points to a repository, and what may look like file links inside the - dictionary folder are actually links to web pages. If you right-click and download those, you - get HTML files, not dictionaries! - - In order to download the actual dictionary files, right-click the "plain" label at the end of - each line and download that. +There are a few ways you can customise novelWriter yourself. Currently, you can relatively easily +add new GUI themes. You can also add new icon themes, although this is not as straightforward. .. _docs_more_custom_theme: -Syntax and GUI Themes -===================== +Colour Themes +============= -Adding your own GUI and syntax themes is relatively easy, although it requires that you manually -edit config files with colour values. The themes are defined by simple plain text config files with -meta data and colour settings. +Adding your own colour themes is relatively easy, although it requires that you manually edit +config files with colour values. 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 `_. -* The existing icon themes are stored in - `novelwriter/assets/icons `_. +The existing colour 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, otherwise you may not be able to distinguish them in **Preferences**. For novelWriter to be able to locate the custom theme files, you must copy them to the -:ref:`docs_technical_locations_data` location in your home or user area. There should be a folder there named -``syntax`` for syntax themes, just ``themes`` for GUI themes, and ``icons`` for icon themes. These -folders are created the first time you start novelWriter. +:ref:`docs_technical_locations_data` location in your home or user area. There should be a folder +there named ``themes`` for colour themes. These folders are created the first time you start +novelWriter. Once the files are copied there, they should show up in **Preferences** with the label you set as ``name`` inside the file. @@ -99,71 +40,123 @@ set as ``name`` inside the file. files up to date. -Custom GUI and Icons Theme --------------------------- +The Theme File Format +--------------------- -A GUI theme ``.conf`` file consists of the following settings: +A colour theme ``.conf`` file consists of the following settings: .. code-block:: cfg + :caption: The theme file for the "Default Light Theme" [Main] - name = My Custom Theme - description = A description of my custom theme - author = Jane Doe - credit = John Doe - url = https://example.com + name = Default Light Theme + mode = light + description = The novelWriter standard light theme + author = Veronica Berglyd Olsen + credit = Veronica Berglyd Olsen + url = https://github.com/vkbo/novelWriter license = CC BY-SA 4.0 licenseurl = https://creativecommons.org/licenses/by-sa/4.0/ - [Icons] - default = 100, 100, 100 - faded = 100, 100, 100 - red = 255, 0, 0 - orange = 255, 128, 0 - yellow = 255, 255, 0 - green = 0, 255, 0 - aqua = 0, 255, 255 - blue = 0, 0, 255 - purple = 255, 0, 255 + [Base] + default = #303030 + faded = #6c6c6c + red = #a62a2d + orange = #b36829 + yellow = #a68542 + green = #296629 + cyan = #269999 + blue = #3a70a6 + purple = #b35ab3 [Project] - root = 0, 255, 255 - folder = 255, 255, 0 - file = 100, 100, 100 - title = 0, 255, 0 - chapter = 255, 0, 0 - scene = 0, 0, 255 - note = 255, 255, 0 + root = blue + folder = yellow + file = default + title = green + chapter = red + scene = blue + note = yellow [Palette] - window = 100, 100, 100 - windowtext = 100, 100, 100 - base = 100, 100, 100 - alternatebase = 100, 100, 100 - text = 100, 100, 100 - tooltipbase = 100, 100, 100 - tooltiptext = 100, 100, 100 - button = 100, 100, 100 - buttontext = 100, 100, 100 - brighttext = 100, 100, 100 - highlight = 100, 100, 100 - highlightedtext = 100, 100, 100 - link = 100, 100, 100 - linkvisited = 100, 100, 100 + window = #efefef + windowtext = #000000 + base = #ffffff + alternatebase = #e0e0e0 + text = #000000 + tooltipbase = #ffffc0 + tooltiptext = #15150d + button = #efefef + buttontext = #000000 + brighttext = #ffffff + highlight = #3087c6 + highlightedtext = #ffffff + link = blue + linkvisited = blue [GUI] - helptext = 0, 0, 0 - fadedtext = 128, 128, 128 - errortext = 255, 0, 0 + helptext = #5c5c5c + fadedtext = #6c6c6c + errortext = red -In the Main section you must at least define the ``name`` settings. + [Syntax] + background = #ffffff + text = #000000 + link = blue + headertext = green + headertag = green:160 + emphasis = orange + dialog = blue + altdialog = blue + note = yellow + hidden = faded + shortcode = green + keyword = red + tag = green + value = blue + optional = green + spellcheckline = red + errorline = green + replacetag = green + modifier = green + texthighlight = #c8c80060 -The Palette values correspond to the Qt enum values for ``QPalette::ColorRole``, see the -`Qt documentation `_ for more details. The -colour values are RGB numbers on the format ``r, g, b`` where each is an integer from ``0`` to -``255``. Omitted values are not loaded and will use default values. If the ``helptext`` colour is -not defined, it is computed as a colour between the ``window`` and ``windowtext`` colour. -Additional shades of some of the colours are also computed. These are mainly used for 3D effects. + +Theme Sections +-------------- + +.. _ColorRole: https://doc.qt.io/qt-6/qpalette.html#ColorRole-enum + +The theme file is made up of different sections depending on what part of novelWriter the theme +affects. + +.. csv-table:: Theme Sections Overview + :header: "Section", "Description" + :class: "tight-table" + + "``[Main]``", "Meta data about the theme, You must at least set ``name`` and ``mode``, and ``mode`` must be either ``light`` or ``dark``." + "``[Base]``", "The base colours of the theme. These are also selectable colours in various places inside the app, like for icon colours in **Preferences**." + "``[Project]``", "The colours used for icons and markers for the different project item types." + "``[Palette]``", "The colours used for styling the user interface. The values correspond to the ColorRole_ values in the Qt library." + "``[GUI]``", "The colours used for styling additional elements of the user interface." + "``[Syntax]``", "The colours used for syntax highlighting in documents." + + +Colour Value Formats +-------------------- + +There are several ways to enter colour values: + +.. csv-table:: Colour Formats + :header: "Syntax", "Description" + :class: "tight-table" + + "``#RRGGBB``", "A CSS style hexadecimal values, like ``#ff0000`` for red." + "``#RRGGBBAA``", "A CSS style hexadecimal values with transparency, like ``#ff00007f`` for half-transparent red." + "``name``", "A name referring to one of the colours already specified under the ``[Base]`` section, like ``red``. Note that you should not use named colours in the ``[Base]`` section itself as that may have unintended results." + "``name:alpha``", "A name referring to one of the colours already specified under the ``[Base]`` section, with a transparency value added. The alpha value must be in the range ``0`` to ``255``, like ``red:127`` for half-transparent red." + "``r, g, b``", "A set of red, green and blue numbers in the range ``0`` to ``255``, like ``255, 0, 0`` for red." + "``r, g, b, a``", "A set of red, green, blue and alpha numbers in the range ``0`` to ``255``, like ``255, 0, 0, 127`` for half-transparent red." .. versionadded:: 2.5 The ``fadedtext`` and ``errortext`` theme colour entries were added. @@ -172,60 +165,84 @@ Additional shades of some of the colours are also computed. These are mainly use The ``icontheme`` setting was dropped as the icon theme is now its own setting. The ``[Icons]`` and ``[Project]`` sections were added, and the ``status*`` settings removed. +.. versionadded:: 2.8 + The ``[Syntax]`` section was moved into the main theme file. Previously, these settings were in + their own file. The ``[Icons]`` section was renamed to ``[Base]``. -Custom Syntax Theme -------------------- -A syntax theme ``.conf`` file consists of the following settings: +Icon Themes +=========== + +Icon themes are *not* straightforward to add, but if you want to make the effort, this section +describes how to do it. + +The existing icon themes are stored in +`novelwriter/assets/icons `_. + +As with colour themes, remember to change the name of your theme by modifying the ``name`` setting +at the top of the file, otherwise you may not be able to distinguish them in **Preferences**. + +For novelWriter to be able to locate the custom theme files, you must copy them to the +:ref:`docs_technical_locations_data` location in your home or user area. There should be a folder +there ``icons`` for icon themes. These folders are created the first time you start novelWriter. + + +The Icons File Format +--------------------- + +Icon themes are kept in files with the ``.icons`` file extension. The file format is a custom +format with entries on the form ``section:key = value``. .. code-block:: cfg + :caption: The icons file for "Material Symbols - Rounded Medium" (truncated) - [Main] - name = My Syntax Theme - author = Jane Doe - credit = John Doe - url = https://example.com - license = CC BY-SA 4.0 - licenseurl = https://creativecommons.org/licenses/by-sa/4.0/ + # Meta + meta:name = Material Symbols - Rounded Medium + meta:author = Google Inc + meta:license = Apache 2.0 - [Syntax] - background = 255, 255, 255 - text = 0, 0, 0 - link = 0, 0, 0 - headertext = 0, 0, 0 - headertag = 0, 0, 0 - emphasis = 0, 0, 0 - dialog = 0, 0, 0 - altdialog = 0, 0, 0 - note = 0, 0, 0 - hidden = 0, 0, 0 - shortcode = 0, 0, 0 - keyword = 0, 0, 0 - tag = 0, 0, 0 - value = 0, 0, 0 - optional = 0, 0, 0 - spellcheckline = 0, 0, 0 - errorline = 0, 0, 0 - replacetag = 0, 0, 0 - modifier = 0, 0, 0 - texthighlight = 255, 255, 255, 128 + # Icons + icon:alert_error = + icon:alert_info = + icon:alert_question = + icon:alert_warn = + icon:cls_archive = + icon:cls_character = + icon:cls_custom = + icon:cls_entity = + icon:cls_none = + icon:cls_novel = + icon:cls_object = + icon:cls_plot = + icon:cls_template = + icon:cls_timeline = + icon:cls_trash = + icon:cls_world = -In the Main section, you must define at least the ``name`` setting. The Syntax colour values are -RGB(A) numbers of the format ``r, g, b, a`` where each is an integer from ``0`` to ``255``. The -fourth value is the alpha channel, which can be omitted. +The icon keys are associated with icon placement locations inside novelWriter, and the template for +them is defined in the script that generates the default icon themes. -Omitted syntax colours default to black, except ``background`` which defaults to white, and -``texthighlight`` which defaults to white with half transparency. +The script can be found under +`utils/icon_themes.py `__ +in the source code. -.. versionadded:: 2.2 - The ``shortcode`` syntax colour entry was added. +This file includes all the code needed to generate the themes that are included in novelWriter. The +icon keys are mapped to icon keys from the specific themes in JSON files in the ``icon_themes`` +folder next to the script. This is the recommended way to generate these themes. Doing it manually +is not advisable. -.. versionadded:: 2.3 - The ``optional`` syntax colour entry was added. -.. versionadded:: 2.4 - The ``texthighlight`` syntax colour entry was added. +Icon Value Format +----------------- -.. versionadded:: 2.5 - The ``dialog``, ``altdialog``, ``note`` and ``tag`` syntax colour entries were added. - ``straightquotes``, ``doublequotes`` and ``singlequotes`` were removed. +As can be seen from the example, an icon is defined in the ``icon`` section with a key and an +in-line SVG XML block. The XML must fit on one line and obey the following rules: + +#. It must be single colour, that is, the fill colour attribute must be able to colourise the + entire icon. +#. The fill colour attribute *must* be defined and must be set to: ``fill="#000000"``. This value + is replaced by the relevant theme colour when the icon is processed in novelWriter. + +.. versionadded:: 2.7 + The icon theme files were added. Previously, icons were stored as individual SVG files with a + config file mapping the file names to the internal icon keys. diff --git a/docs/source/more/dictionaries.rst b/docs/source/more/dictionaries.rst new file mode 100644 index 00000000..1ca896d5 --- /dev/null +++ b/docs/source/more/dictionaries.rst @@ -0,0 +1,55 @@ +.. _docs_more_dictionaries: + +************************ +Spell Check Dictionaries +************************ + +.. _Enchant: https://rrthomas.github.io/enchant/ +.. _Free Desktop: https://cgit.freedesktop.org/libreoffice/dictionaries/tree/ + +Spell checking is provided by the Enchant_ library. Depending on your operating system, it may or +may not load all installed spell check dictionaries automatically. + + +Linux and MacOS +=============== + +On Linux and MacOS, you generally only have to install hunspell, aspell or myspell dictionaries on +your system like you do for other applications. See your distro or OS documentation for how to do +this. These dictionaries should show up as available spell check languages in novelWriter. + + +Windows +======= + +For Windows, English is included with the installation. For other languages you have to download +and add dictionaries yourself. + +**Install Tool** + +A small tool to assist with this can be found under **Tools > Add Dictionaries**. It will import +spell checking dictionaries from Free Office or Libre Office extensions. The dictionaries are then +installed in the install location for the Enchant library and should thus work for any application +that uses Enchant for spell checking. + +**Manual Install** + +If you prefer to do this manually or want to use a different source than the ones mentioned above, +You need to get compatible dictionary files for your language. You need two files 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. + +You can find the various dictionaries on the `Free Desktop`_ website. + +.. note:: + + The Free Desktop link points to a repository, and what may look like file links inside the + dictionary folder are actually links to web pages. If you right-click and download those, you + get HTML files, not dictionaries! + + In order to download the actual dictionary files, right-click the "plain" label at the end of + each line and download that. diff --git a/docs/source/user_interface/editor_viewer.rst b/docs/source/user_interface/editor_viewer.rst index 841be0b0..ee0c1eb3 100644 --- a/docs/source/user_interface/editor_viewer.rst +++ b/docs/source/user_interface/editor_viewer.rst @@ -55,7 +55,7 @@ edited from the **Project Word List** tool available from the **Tools** menu. .. note:: Generally, spell checking dictionaries are collected from your operating system, but on Windows - they are not. See :ref:`docs_more_custom_dict` for how to add spell checking dictionaries on + they are not. See :ref:`docs_more_dictionaries` for how to add spell checking dictionaries on Windows.