Reproog/novelWriter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move documentation files to keep into new structure

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2025-05-24 20:17:14 +02:00
parent b2f30565b1
commit 0c2d392166
26 changed files with 85 additions and 964 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/more/counting.rst
+98
View File
@@ -0,0 +1,98 @@
.. _docs_more_counting:
********************
Word and Text Counts
********************
This is an overview of how words and other counts of your text are performed. The counting rules
should be relatively standard, and are compared to Libre Office Writer rules.
The counts provided in the app on the raw text is meant to be approximate. For more accurate
counts, you need to build your manuscript in the **Manuscript Tool** and check the counts on the
generated preview.
Text Word Counts and Stats
==========================
These are the rules for the main counts available for for each document in a project.
For all counts, the following rules apply.
#. Short (–) and long (—) dashes are considered word separators.
#. Any line starting with ``%`` or ``@`` is ignored.
#. Trailing white spaces are ignored, including line breaks.
#. Leading ``>`` and trailing ``<`` are ignored with any spaces next to them.
#. Valid shortcodes and other commands wrapped in brackets ``[]`` are ignored.
#. In-line Markdown syntax in text paragraphs is treated as part of the text.
After the above preparation of the text, the following counts are available.
**Character Count**
The character count is the sum of characters per line, including leading and in-text white space
characters, but excluding trailing white space characters. Shortcodes in the text are not
included, but Markdown codes are. Only headings and text are counted.
**Word Count**
The words count is the sum of blocks of continuous character per line separated by any number of
white space characters or dashes. Only headings and text are counted.
**Paragraph Count**
The paragraph count is the number of text blocks separated by one or more empty line. A line
consisting only of white spaces is considered empty.
Manuscript Counts
=================
These are the rules for the counts available for a manuscript in the **Manuscript Tool**. The rules
have been tuned to agree with LibreOffice Writer, but will vary slightly depending on the content
of your text. LibreOffice Writer also counts the text in the page header, which the **Manuscript
Tool** does not.
The content of each line is counted after all formatting has been processed, so the result will be
more accurate than the counts for text documents elsewhere in the app. The following rules apply:
#. Short (–) and long (—) dashes are considered word separators.
#. Leading and trailing white spaces are generally included, but paragraph breaks are not.
#. Hard line breaks within paragraph are considered white space characters.
#. All formatting codes are ignored, including shortcodes, commands and Markdown.
#. Scene and section separators are counted.
#. Comments and meta data lines are counted after they are formatted.
#. Headers are counted after they are formatted with custom formats.
The following counts are available:
**Headings**
The number of headings in the manuscript.
**Paragraphs**
The number of body text paragraphs in the manuscript.
**Words**
The number of words in the manuscript, including any comments and meta data text.
**Words in Text**
The number of words in body text paragraphs, excluding all other text.
**Words in Headings**
The number of words in headings, including inserted formatting like chapter numbers, etc.
**Characters**
The number of characters in all lines, including any comments and meta data text. Paragraph
breaks are not counted, but in-paragraph hard line breaks are.
**Character in Text**
The number of characters in body text paragraphs. Paragraph breaks are not counted, but
in-paragraph hard line breaks are.
**Characters in Headings**
The number of characters in headings.
**Character in Text, No Spaces**
The number of characters in body text paragraphs considered part of a word or punctuation. That
is, white space characters are not counted.
**Character in Headings, No Spaces**
The number of characters in headings considered part of a word or punctuation. That is, white
space characters are not counted.
docs/source/more/customise.rst
+211
View File
@@ -0,0 +1,211 @@
.. _docs_more_custom:
**************
Customisations
**************
.. _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\<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.
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.
.. _docs_more_custom_theme:
Syntax and GUI 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.
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>`_.
* The existing icon themes are stored in
`novelwriter/assets/icons <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/icons>`_.
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.
Once the files are copied there, they should show up in **Preferences** with the label you
set as ``name`` inside the file.
.. versionadded:: 2.0
The ``icontheme`` value was added to GUI themes. Make sure you set this value in existing custom
themes. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most
suitable one.
Custom GUI and Icons Theme
--------------------------
A GUI theme ``.conf`` file consists of the following settings:
.. code-block:: cfg
[Main]
name = My Custom Theme
description = A description of my custom 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/
icontheme = typicons_light
[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
[GUI]
helptext = 0, 0, 0
fadedtext = 128, 128, 128
errortext = 255, 0, 0
statusnone = 120, 120, 120
statussaved = 2, 133, 37
statusunsaved = 200, 15, 39
In the Main section you must at least define the ``name`` and ``icontheme`` settings. The
``icontheme`` settings should correspond to one of the internal icon themes, either
``typicons_light`` or ``typicons_dark``, or to an icon theme in your custom icons directory. The
setting must match the icon theme's folder name.
The Palette values correspond to the Qt enum values for ``QPalette::ColorRole``, see the
`Qt documentation <https://doc.qt.io/qt-6/qpalette.html#ColorRole-enum>`_ 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.
.. versionadded:: 2.5
The ``fadedtext`` and ``errortext`` theme colour entries were added.
Custom Syntax Theme
-------------------
A syntax theme ``.conf`` file consists of the following settings:
.. code-block:: cfg
[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/
[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
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.
Omitted syntax colours default to black, except ``background`` which defaults to white, and
``texthighlight`` which defaults to white with half transparency.
.. versionadded:: 2.2
The ``shortcode`` syntax colour entry was added.
.. versionadded:: 2.3
The ``optional`` syntax colour entry was added.
.. versionadded:: 2.4
The ``texthighlight`` syntax colour entry was added.
.. versionadded:: 2.5
The ``dialog``, ``altdialog``, ``note`` and ``tag`` syntax colour entries were added.
``straightquotes``, ``doublequotes`` and ``singlequotes`` were removed.
docs/source/more/howto.rst
+119
View File
@@ -0,0 +1,119 @@
.. _docs_more_howto:
*************
Tips & Tricks
*************
.. _Discussions Page: https://github.com/vkbo/novelWriter/discussions
This is a list of hopefully helpful little tips on how to get the most out of novelWriter.
.. note::
This section will be expanded over time. If you would like to have something added, feel free to
contribute, or start a discussion on the project's `Discussions Page`_.
Managing the Project
====================
.. dropdown:: How do I create a project from a template?
:animate: fade-in-slide-down
On the Welcome dialog's **Create New Project** form, you can select to "Prefill Project" from
the content of a different project. This feature is most useful if you copy a project you have
dedicated to be a template project. If you have a structure and settings you want to use for
every new project, this is the best solution.
.. dropdown:: How do I merge multiple documents into one?
:animate: fade-in-slide-down
If you need to merge a selection of documents in your project into a single document, you can
achieve this by first making a new folder for just that purpose, and drag all the documents you
want merged into this folder. Then you can right click the folder, select :guilabel:`Transform`
and :guilabel:`Merge Documents in Folder`.
In the dialog that pops up, the documents will be in the same order as in the folder, but you
can rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details.
.. dropdown:: How do I share status or importance labels between projects?
:animate: fade-in-slide-down
The status or importance labels you have defined in a project can be exported from **Project
Settings** from the respective configuration tabs. You can then import these labels in another
project.
Layout Tricks
=============
.. dropdown:: How do I create a table?
:animate: fade-in-slide-down
The formatting tools available in novelWriter don't allow for complex structures like tables.
However, the editor does render tabs in a similar way that regular word processors do. You can
set the width of a tab in **Preferences**.
The tab key should have the same distance in the editor as in the viewer, so you can align text
in columns using the tab key, and it should look the same when viewed next to the editor.
This is most suitable for your notes, as the result in exported documents cannot be guaranteed
to match. Especially if you don't use the same font in your manuscript as in the editor.
.. dropdown:: How do I force a line break when line breaks are ignored in my manuscript?
:animate: fade-in-slide-down
In the **Manuscript Build Settings** you can choose to ignore line breaks within paragraphs in
your text. However, some times you still need those breaks. Like for instance on the cover page
where you may need to add your name and address. In such cases, you can add ``[br]`` where you
want line breaks. These breaks cannot be ignored by any settings and will always be respected.
.. versionadded:: 2.6
.. dropdown:: How do I turn off first line indent for a specific paragraph?
:animate: fade-in-slide-down
If you have first line indent enabled, but have a specific paragraph that you don't want
indented, you can disable the indentation by explicitly adding text alignment. For instance by
adding ``<<`` to the end to left-align it. Aligned paragraphs are not indented.
See :ref:`docs_usage_align_indent` for more details.
Organising Your Text
====================
.. dropdown:: How do I add introductory text to chapters?
:animate: fade-in-slide-down
Sometimes chapters have a short preface, like a brief piece of text or a quote to set the stage
before the first scene begins.
If you add separate files for chapters and scenes, the chapter file is the perfect place to add
such text. Separating chapter and scene files also allows you to make scene files child
documents of the chapter.
.. dropdown:: How do I distinguishing between soft and hard scene breaks?
:animate: fade-in-slide-down
Depending on your writing style, you may need to separate between soft and hard scene breaks
within chapters. Like for instance if you switch point-of-view character often.
In such cases you may want to use different scene headings for hard and soft scene breaks. The
**Build Manuscript** tool will let you define a different format for scenes using the ``###``
and ``###!`` heading codes when you generate your manuscript. You can for instance add the
common "``* * *``" for hard breaks and select to hide soft scene breaks, which will just insert
an empty paragraph in their place. See :ref:`a_manuscript_settings` for more details.
.. versionadded:: 2.4
Other Tools
===========
.. dropdown:: How do I convert my project to/from the yWriter format?
:animate: fade-in-slide-down
There is a tool available that lets you convert a `yWriter <http://spacejock.com/yWriter7.html>`_
project to a novelWriter project, and vice versa.
The tool is available at `peter88213.github.io/yw2nw <https://peter88213.github.io/yw2nw/>`__
docs/source/more/project_format.rst
+122
View File
@@ -0,0 +1,122 @@
.. _docs_more_project_formats:
**********************
Project Format Changes
**********************
.. _File Format Spec 1.5: _static/fileformatspec15.pdf
.. _documentation: https://docs.novelwriter.io/
Most of the changes to the file formats over the history of novelWriter have no impact on the
user side of things. The project files are generally updated automatically. However, some of the
changes require minor actions from the user.
The key changes in the formats are listed in this chapter, as well as the user actions required,
where applicable.
A full project file format specification is available under "More Documents".
.. caution::
When you update a project from one format version to the next, the project can no longer be
opened by a version of novelWriter prior to the version where the new file format was
introduced. You will get a notification about any updates to your project file format and will
have the option to decline the upgrade.
.. _docs_more_project_formats_1_5:
Format 1.5 Changes
==================
This project format was introduced in novelWriter version 2.0 RC 2.
This is a modification of the 1.4 format. It makes the XML more consistent in that meta data have
been moved to their respective section nodes as attributes, and key/value settings now have a
consistent format. Logical flags are saved as yes/no instead of Python True/False, and the main
heading of the document is now saved to the item rather than in the index. The conversion is done
automatically the first time a project is loaded. No user action is required.
.. _docs_more_project_formats_1_4:
Format 1.4 Changes
==================
This project format was introduced in novelWriter version 2.0 RC 1. Since this was a release
candidate, it is unlikely that your project uses it, but it may be the case if you've installed a
pre-release.
This format changes the way project items (folders, documents and notes) are stored. It is a more
compact format that is simpler and faster to parse, and easier to extend. The conversion is done
automatically the first time a project is loaded. No user action is required.
.. _docs_more_project_formats_1_3:
Format 1.3 Changes
==================
This project format was introduced in novelWriter version 1.5.
With this format, the number of document layouts was reduced from eight to two. The conversion of
document layouts is performed automatically when the project is opened.
Due to the reduction of layouts, some features that were previously controlled by these layouts
will be lost. These features are instead now controlled by syntax codes, so to recover these
features, some minor modification must be made to select documents by the user.
The manual changes the user must make should be very few as they apply to document layouts that
should be used only a few places in any given project. These are as follows:
**Title Pages**
* The formatting of the level one title on the title page must be changed from ``# Title Text`` to
``#! Title Text`` in order to retain the previous functionality.
See :ref:`docs_usage_headers_levels`.
* Any text that was previously centred on the page must be manually centred using the text
alignment feature. See :ref:`docs_usage_align_indent`.
**Unnumbered Chapters**
* Since the specific layout for unnumbered chapters has been dropped, such chapters must all use
the ``##! Chapter Name`` formatting code instead of ``## Chapter Name``. This also includes
chapters marked by an asterisk: ``## *Chapter Name``, as this feature has also been dropped.
See :ref:`docs_usage_headers_levels`.
**Plain Pages**
* The layout named "Plain Page" has also been removed. The only feature of this layout was that it
ensured that the content always started on a fresh page. In the new format, fresh pages can be
set anywhere in the text with the ``[NEW PAGE]`` code. See :ref:`docs_usage_formatting_breaks`.
.. _docs_more_project_formats_1_2:
Format 1.2 Changes
==================
This project format was introduced in novelWriter version 0.10.
With this format, the way auto-replace entries were stored in the main project XML file changed.
.. _docs_more_project_formats_1_1:
Format 1.1 Changes
==================
This project format was introduced in novelWriter version 0.7.
With this format, the ``content`` folder was introduced in the project storage. Previously, all
novelWriter documents were saved in a series of folders numbered from ``data_0`` to ``data_f``.
It also reduces the number of meta data and cache files. These files are automatically deleted if
an old project is opened. This was also when the Table of Contents file was introduced.
.. _docs_more_project_formats_1_0:
Format 1.0 Changes
==================
This is the original file format and project structure. It was in use up to version 0.6.3.
docs/source/more/typography.rst
+101
View File
@@ -0,0 +1,101 @@
.. _docs_more_typographical:
*******************
Typographical Notes
*******************
.. _Prime: https://en.wikipedia.org/wiki/Prime_(symbol)
.. _thin space: https://en.wikipedia.org/wiki/Thin_space
.. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark
.. _Modifier letter apostrophe: https://en.wikipedia.org/wiki/Modifier_letter_apostrophe
novelWriter has some support for typographical symbols that are not usually easily available in
many text editors. This includes for instance the proper unicode quotation marks, dashes, ellipsis,
thin spaces, etc. All these symbols are available from the **Insert** menu, and via
keyboard shortcuts. See :ref:`a_kb_ins`.
This chapter provides some additional information on how novelWriter handles these symbols.
.. _a_typ_notes:
Special Notes on Symbols
========================
This section contains additional notes on the available special symbols.
Dashes and Ellipsis
-------------------
With the auto-replace feature enabled (see :ref:`a_ui_edit_auto`), multiple hyphens are converted
automatically to short and long dashes, and three dots to ellipsis. The last auto-replace can
always be reverted with the undo command :kbd:`Ctrl+Z`, reverting the text to what you typed before
the automatic replacement occurred.
In addition, "Figure Dash" is available. The Figure Dash is a dash that has the same width as the
numbers of the same font, for most fonts. It helps to align numbers nicely in columns when you need
to use a dash in them.
Single and Double Quotes
------------------------
All the different quotation marks listed on the `Quotation Mark`_ Wikipedia page are available, and
can be selected as auto-replaced symbols for straight single and double quote key strokes. The
settings can be found in **Preferences**.
Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience
for highlighting dialogue between characters. This feature can be disabled in
**Preferences** if this feature isn't wanted.
The editor distinguishes between text wrapped in regular straight double quotes and the
user-selected double quote symbols. This is to help the writer recognise which parts of the text
are not using the chosen quote symbols. Two convenience functions in the **Format** menu
can be used to re-format a selected section of text with the correct quote symbols.
Single and Double Prime
------------------------
Both single and double prime symbols are available in the **Insert** menu. These symbols
are the correct symbols to use for unit symbols for feet, inches, minutes, and seconds. The usage
of these is described in more detail on the Wikipedia Prime_ page. They look very similar to single
and double straight quotes, and may be rendered similarly by the font, but they have different
codes. Using these correctly will also prevent the auto-replace and dialogue highlighting features
misunderstanding their meaning in the text.
Modifier Letter Apostrophe
--------------------------
The auto-replace feature will consider any right-facing single straight quote as a quote symbol,
even if it is intended as an apostrophe. This also includes the syntax highlighter, which may
assume the first following apostrophe is the closing symbol of a single quoted region of text.
To get around this, an alternative apostrophe is available. It is a special Unicode character that
is not categorised as punctuation, but as a modifier. It is usually rendered the same way as the
right single quotation marks, depending on the font. There is a Wikipedia article for the
`Modifier letter apostrophe`_ with more details.
.. note::
On export with the **Build Manuscript** tool, these apostrophes will be replaced
automatically with the corresponding right hand single quote symbol as is generally recommended.
Therefore it doesn't really matter if you only use them to correct syntax highlighting.
Special Space Symbols
---------------------
A few variations of the regular space character is supported. The correct typographical way to
separate a number from its unit is with a `thin space`_. It is usually 2/3 the width of a regular
space. For numbers and units, this should in addition be a non-breaking space, that is, the text
wrapping should not add a line break on this particular space.
A regular space can also be made into a non-breaking space if needed.
All non-breaking spaces are highlighted with a differently coloured background to make it easier to
spot them in the text. The colour will depend on the selected colour theme.
The thin and non-breaking spaces are converted to their corresponding HTML codes on export to HTML
format.