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

Fix typos, grammars and improve wording of the docs

Browse Source
This commit is contained in:
Veronica K. B. Olsen
2021-01-10 18:30:58 +01:00
parent e02d602341
commit 2ca4b15154
9 changed files with 197 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/int_interface.rst
+69 -59
View File
@@ -22,7 +22,7 @@ the project. It has four columns:
document text itself. document text itself.
:guilabel:`Words` :guilabel:`Words`
The second column shows the word count of the document, or the sum of words in the child items The second column shows the word count of the document, or the sum of words of the child items
if it is a folder. If the counts seem incorrect, they can be updated by rebuilding the project if it is a folder. If the counts seem incorrect, they can be updated by rebuilding the project
index from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`. index from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
@@ -36,16 +36,16 @@ the project. It has four columns:
the importance or status of the document. These are colour coded status levels that you control the importance or status of the document. These are colour coded status levels that you control
and define yourself. They can be changed in :guilabel:`Project Settings` from the and define yourself. They can be changed in :guilabel:`Project Settings` from the
:guilabel:`Project` menu. The first character after the icon indicates the class of the item, :guilabel:`Project` menu. The first character after the icon indicates the class of the item,
that is ``N`` for **Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`). The second that is ``N`` for **Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`). The
character indicates the document layout type (see :ref:`a_proj_roots`). characters after the dot indicate the document layout type (see :ref:`a_proj_roots`).
Right-clicking an item in the project tree will open a context menu under the cursor, displaying
a selection of actions that can be performed on the selected item.
Below the project tree you will find a small details panel showing the full information of the Below the project tree you will find a small details panel showing the full information of the
currently selected item. This panel also includes the latest paragraph and character counts in currently selected item. This panel also includes the latest paragraph and character counts in
addition to the word count. addition to the word count.
Right-clicking an item in the project tree will open a context menu under the cursor, displaying
a selection of actions that can be performed on the selected item.
.. _a_ui_tree_dnd: .. _a_ui_tree_dnd:
@@ -59,13 +59,13 @@ deliberate to avoid accidentally messing up your project. The project tree has n
Documents and their folders can be rearranged freely within their root folders. Novel documents Documents and their folders can be rearranged freely within their root folders. Novel documents
cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the
:guilabel:`Outtakes` folder. Notes can be moved freely between root folders. :guilabel:`Outtakes` folders. Notes can be moved freely between all root folders.
Folders cannot be moved at all outside their root tree. Neither can a folder containing documents Folders cannot be moved at all outside their root tree. Neither can a folder containing documents
be deleted. You must first delete the containing documents. be deleted. You must first delete the containing documents.
Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them, Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them,
you can move them up or down with respect to eachother from the :guilabel:`Tools` menu or the you can move them up or down with respect to eachother from the :guilabel:`Tools` menu, the
right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down`
key. key.
@@ -78,7 +78,7 @@ Editing and Viewing Documents
To edit a document, double-click it in the project tree, or press the :kbd:`Return` key while To edit a document, double-click it in the project tree, or press the :kbd:`Return` key while
having it selected. This will open the document in the document editor. The editor uses a having it selected. This will open the document in the document editor. The editor uses a
simplified markdown format. The format is described in the :ref:`a_ui_md` section below. The editor simplified markdown format. The format is described in the :ref:`a_ui_md` section below. The editor
has a maximise button (activates :guilabel:`Distraction Free Mode`) and a close button in the has a maximise button (toggles the :guilabel:`Distraction Free Mode`) and a close button in the
top-right corner. top-right corner.
Any document in the project tree can also be viewed in parallel in a right hand side document Any document in the project tree can also be viewed in parallel in a right hand side document
@@ -92,26 +92,28 @@ panel next to the close button to achieve the same thing.
Both the document editor and viewer will show the label of the document in the header at the top of Both the document editor and viewer will show the label of the document in the header at the top of
the edit or view panel. Optionally, the full project path to the document can be shown. This can be the edit or view panel. Optionally, the full project path to the document can be shown. This can be
set in the :guilabel:`Preferences` dialog from the :guilabel:`Tools` menu. Clicking on the document set in the :guilabel:`Preferences` dialog from the :guilabel:`Tools` menu. Clicking on the document
title bar will select and reveal its location in the project tree, making it easier to find in a title bar will select and reveal its location in the project tree, making it easier to locate in a
large project. large project.
Any reference to a tag in the editor can be opened in the viewer by moving the cursor to the label Any tag reference in the editor can be opened in the viewer by moving the cursor to the label and
and pressing :kbd:`Ctrl`:kbd:`Return`. In the viewer, the references become clickable links. pressing :kbd:`Ctrl`:kbd:`Return`. You can also control-click them with your mouse. In the viewer,
Clicking them will replace the content of the viewer with the content of the document the reference the references become clickable links. Clicking them will replace the content of the viewer with
points to. The document viewer keeps a history of viewed documents that you can navigate with the the content of the document the reference points to. The document viewer keeps a history of viewed
arrow buttons in the top-left corner of the viewer. If your mouse has navigation buttons, these can documents, which you can navigate with the arrow buttons in the top-left corner of the viewer. If
be used as well. your mouse has back and forward navigation buttons, these can be used as well.
At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click
the icon to reveal it.) This panel will show links to all documents referring back to it, if any the icon to reveal it.) This panel will show links to all documents referring back to it, if any
has been defined. The :guilabel:`Sticky` button will freeze the content of the panel to the current has been defined. The :guilabel:`Sticky` button will freeze the content of the panel to the current
document, even if you navigate to another document. This is convenient if you want to quickly look document, even if you navigate to another document. This is convenient if you want to quickly look
through all documents in the list in the :guilabel:`References` panel. through all documents in the list in the :guilabel:`References` panel without losing the list in
the process.
.. note:: .. note::
The :guilabel:`References` panel relies on an up-to-date index of the project. If anything is The :guilabel:`References` panel relies on an up-to-date index of the project. The index is
missing, or seems wrong, the index can always be rebuilt by selecting :guilabel:`Rebuild Index` maintained automatically. However, if anything is missing, or seems wrong, the index can always
from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`. be rebuilt by selecting :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu, or by
pressing :kbd:`F9`.
.. _a_ui_edit_auto: .. _a_ui_edit_auto:
@@ -120,7 +122,7 @@ Auto-Replace as You Type
======================== ========================
A few auto-replace features are supported by the editor. You can control every aspect of the A few auto-replace features are supported by the editor. You can control every aspect of the
auto-replace feature from :guilabel:`Preferences`. auto-replace feature from :guilabel:`Preferences`. You can also disable it entirely.
.. tip:: .. tip::
If you don't like auto-replacement, all symbols inserted by this feature are also available in If you don't like auto-replacement, all symbols inserted by this feature are also available in
@@ -128,12 +130,14 @@ auto-replace feature from :guilabel:`Preferences`.
The editor is able to replace two and three hyphens with short and long dashes, triple points with The editor is able to replace two and three hyphens with short and long dashes, triple points with
ellipsis, and replace straight single and double quotes with user-defined quote symbols. It will ellipsis, and replace straight single and double quotes with user-defined quote symbols. It will
also try to determine whether to use the opening or closing symbol, but this feature isn't always also try to determine whether to use the opening or closing symbol, although this feature isn't
accurate. always accurate. Especially distinguishing between closing single quote and apostrophe can be
tricky for languages that use the same symbol for these.
.. tip:: .. tip::
If the editor changes a symbol when you did not want it to change, pressing :kbd:`Ctrl`:kbd:`Z` If the auto-replace feature changes a symbol when you did not want it to change, pressing
immediately after the auto-replacement will undo it without undoing the character you typed. :kbd:`Ctrl`:kbd:`Z` immediately after the auto-replacement will undo it without undoing the
character you typed.
.. _a_ui_md: .. _a_ui_md:
@@ -154,25 +158,27 @@ a synopsis tag, and a set of keyword and value sets used for tags and references
Headings Headings
-------- --------
Four levels of headings are allowed. For documents of layout "Note", they are free to be used as Four levels of headings are allowed. For documents of layout ``Note``, they are free to be used as
you see fit, but for all other layouts used for the novel text itself, they indicate the structural you see fit, but for all other layouts used for the novel text itself, they indicate the structural
level of the novel. See :ref:`a_struct_heads` for more details. level of the novel. See :ref:`a_struct_heads` for more details.
``# Title`` ``# Title``
Heading level one. If the document is a novel file, the header level indicates the start of a Heading level one. If the document is a novel file, the header level indicates the start of a
new partition. This heading level can also be used for the title page novel title. new partition. This heading level can also be used for the title page's novel title.
``## Title`` ``## Title``
Heading level two. If the document is a novel file, the header level indicates the start of a Heading level two. If the document is a novel file, the header level indicates the start of a
new chapter. new chapter. Chapter numbers can be inserted automatically when exporting the manuscript.
``### Title`` ``### Title``
Heading level three. If the document is a novel file, the header level indicates the start of a Heading level three. If the document is a novel file, the header level indicates the start of a
new scene. new scene. Scene numbers or scene separators can be inserted automatically when exporting the
manuscript, so you can use the title field as a working title for your scenes.
``#### Title`` ``#### Title``
Heading level four. If the document is a novel file, the header level indicates the start of a Heading level four. If the document is a novel file, the header level indicates the start of a
new section. new section. Scene titles can be replaced by separators or removed when exporting the
manuscript, so you can use the title field as a working title for your sections.
.. note:: .. note::
The space after the ``#`` characters is mandatory. The syntax highlighter will change colour and The space after the ``#`` characters is mandatory. The syntax highlighter will change colour and
@@ -219,26 +225,28 @@ In addition, the following rules apply:
Comments and Synopsis Comments and Synopsis
--------------------- ---------------------
In addition to these standard markdown features, novelWriter also allows for comments in document. In addition to these standard markdown features, novelWriter also allows for comments in documents.
The text of the comment is ignored by the word counter and not exported or, optionally, hidden when The text of a comment is ignored by the word counter. The text can also be filtered out when
viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon), the comment exporting or viewing the document.
is treated specially and will show up in the :ref:`a_ui_outline` in a dedicated column. The word
``synopsis`` is not case sensitive. If it is correctly formatted, the syntax highlighter will If the first word of a comment is ``Synopsis:`` (with the colon), the comment is treated specially
indicate this by altering the colour of the word. and will show up in the :ref:`a_ui_outline` in a dedicated column. The word ``synopsis`` is not
case sensitive. If it is correctly formatted, the syntax highlighter will indicate this by altering
the colour of the word.
``% text...`` ``% text...``
A comment. The text is not exported by default (this can be overridden), seen in the Viewer, or This is a comment. The text is not exported by default (this can be overridden), seen in the
counted towards word counts. Viewer, or counted towards word counts.
``% Synopsis: text...`` ``% Synopsis: text...``
A synopsis comment. It is generally treated in the same way as a regular comment, except that it This is a synopsis comment. It is generally treated in the same way as a regular comment, except
is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It can also that it is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It
be filtered separately when exporting the project to for instance generate an outline document can also be filtered separately when exporting the project to for instance generate an outline
of the whole project. document of the whole project.
.. note:: .. note::
Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are
flagged as synopsis comments, the last one will be used. flagged as synopsis comments, the last one will be used and the rest ignored.
.. _a_ui_md_tags: .. _a_ui_md_tags:
@@ -262,13 +270,14 @@ also be inserted at the cursor position in the editor via the :guilabel:`Insert`
Additional Markdown and Non-Standard Features Additional Markdown and Non-Standard Features
--------------------------------------------- ---------------------------------------------
The editor and viewer also supports markdown standard hard line breaks, and preserves non-breaking The editor and viewer also support markdown standard hard line breaks, and preserves non-breaking
spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when
the document is saved. This is unfortunately hard-coded in the Qt text editor. the document is saved. This is unfortunately hard-coded in the Qt text editor.
* A hard line break is achieved by leaving two or more spaces at the end of the line. * A hard line break can be achieved by leaving two or more spaces at the end of the line. This is
Alternatively, the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to insert this. standard markdown syntax. Alternatively, the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to
* A non-breaking space is inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`. insert this type of space.
* A non-breaking space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`.
* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`, * Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`,
:kbd:`Shift`:kbd:`Space`. :kbd:`Shift`:kbd:`Space`.
* Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`. * Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`.
@@ -287,7 +296,8 @@ Project Outline View
The project's Outline view is available as the second tab on the right hand side of the main window The project's Outline view is available as the second tab on the right hand side of the main window
labelled :guilabel:`Outline`. The outline provides an overview of the novel structure, displaying a labelled :guilabel:`Outline`. The outline provides an overview of the novel structure, displaying a
tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings. tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings representing
partitions, chapters, scenes and sections.
The document containing the heading can also be displayed as a separate column, as well as the line The document containing the heading can also be displayed as a separate column, as well as the line
number where it occurs. Double-clicking an entry will open the corresponding document in the number where it occurs. Double-clicking an entry will open the corresponding document in the
@@ -295,7 +305,7 @@ editor.
.. note:: .. note::
Since the internal structure of the novel does not depend directly on the folder and document Since the internal structure of the novel does not depend directly on the folder and document
structure of the project tree, these will not necessarily look the same, depending how you structure of the project tree, these will not necessarily look the same, depending on how you
choose to organise your documents. See the :ref:`a_struct` page for more details. choose to organise your documents. See the :ref:`a_struct` page for more details.
Various meta data and information extracted from tags can be displayed in columns in the outline. Various meta data and information extracted from tags can be displayed in columns in the outline.
@@ -409,7 +419,7 @@ Insert Shortcuts
A set of insert features are also available through shortcuts, but they require a double A set of insert features are also available through shortcuts, but they require a double
combination of key sequences. The insert feature is activated with :kbd:`Ctrl`:kbd:`K`, followed by combination of key sequences. The insert feature is activated with :kbd:`Ctrl`:kbd:`K`, followed by
a key or combination for the inserted character or punctuation. a key or key combination for the inserted content.
.. csv-table:: Keyboard Shortcuts .. csv-table:: Keyboard Shortcuts
:header: "Shortcut", "Description" :header: "Shortcut", "Description"
@@ -428,12 +438,12 @@ a key or combination for the inserted character or punctuation.
":kbd:`Ctrl`:kbd:`K`, :kbd:`Space`", "Insert a non-breaking space." ":kbd:`Ctrl`:kbd:`K`, :kbd:`Space`", "Insert a non-breaking space."
":kbd:`Ctrl`:kbd:`K`, :kbd:`Shift`:kbd:`Space`", "Insert a thin space." ":kbd:`Ctrl`:kbd:`K`, :kbd:`Shift`:kbd:`Space`", "Insert a thin space."
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`", "Insert a thin non-breaking space." ":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`", "Insert a thin non-breaking space."
":kbd:`Ctrl`:kbd:`K`, :kbd:`G`", "Insert a @tag keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`G`", "Insert a ``@tag`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`V`", "Insert a @pov keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`V`", "Insert a ``@pov`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`C`", "Insert a @char keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`C`", "Insert a ``@char`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`P`", "Insert a @plot keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`P`", "Insert a ``@plot`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`T`", "Insert a @time keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`T`", "Insert a ``@time`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`L`", "Insert a @location keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`L`", "Insert a ``@location`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`O`", "Insert a @object keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`O`", "Insert an ``@object`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`E`", "Insert a @entity keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`E`", "Insert an ``@entity`` keyword."
":kbd:`Ctrl`:kbd:`K`, :kbd:`X`", "Insert a @custom keyword." ":kbd:`Ctrl`:kbd:`K`, :kbd:`X`", "Insert a ``@custom`` keyword."
docs/source/int_introduction.rst
+11 -11
View File
@@ -7,20 +7,20 @@ Introduction
novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply
simple formatting to the text. It is designed for writing novels, and allows for the component simple formatting to the text. It is designed for writing novels, and allows for the component
documents to be ordered freely to create the desired structure of the novel. More details about how documents to be ordered freely to create the desired structure of the novel. More details about how
projects are structured is covered on the :ref:`a_struct` page. projects are structured is covered in :ref:`a_struct`.
In addition, the project can contain notes on the various plot elements, characters, locations, In addition, the project can contain notes on the various plot elements, characters, locations,
etc, that make up the story. These notes are organised in a set of category-specific top-level etc, that make up the story. These notes are organised in a set of category-specific top-level
folders (root folders), and each entry can be tagged and cross-referenced from within the novel folders (root folders), and each entry can be tagged and cross-referenced from within the novel
documents and notes. These tags make it possible to inter-link documents, and generate an overview documents and notes. These tags make it possible to inter-link documents, and generate an overview
of the entire novel project and how the various documents and plot elements are interconnected. of the entire novel project and how the various documents and plot elements are interconnected.
This is covered on the :ref:`a_proj` and :ref:`a_notes` pages. This is covered in :ref:`a_proj` and :ref:`a_notes`.
These additional features are not standard in markdown, but are available through special meta These additional features are not standard in markdown, but are available through special meta
keywords described in :ref:`a_struct_tags`. Syntax highlighting is provided to make it easier to keywords described in :ref:`a_struct_tags`. Syntax highlighting is provided to make it easier to
verify that the markdown tags are used correctly. verify that the markdown tags are used correctly.
An overview of the supported markdown syntax is covered on the :ref:`a_ui` page. An overview of the supported markdown syntax is covered in :ref:`a_ui`.
.. _a_intro_design: .. _a_intro_design:
@@ -36,7 +36,7 @@ at the same time provide a complete set of features needed for writing a novel.
links, tables, and other complex structures and objects often needed for such documents. links, tables, and other complex structures and objects often needed for such documents.
Formatting is limited to headers, and bold, italicised and strikethrough text. Formatting is limited to headers, and bold, italicised and strikethrough text.
The main window does not have a toolbar like most other applications do. This reduces clutter, and The main window does not have a toolbar like many other applications do. This reduces clutter, and
since the documents are formatted with markdown tags, is more or less redundant. However, all since the documents are formatted with markdown tags, is more or less redundant. However, all
formatting features supported are available through convenient keyboard shortcuts. They are also formatting features supported are available through convenient keyboard shortcuts. They are also
available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts` available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts`
@@ -51,9 +51,10 @@ menu. A number of syntax highlighting themes are also available in :guilabel:`Pr
of icon themes in colour and greyscale are also offered. The icons are based on the Typicons_ icon of icon themes in colour and greyscale are also offered. The icons are based on the Typicons_ icon
set designed by Stephen Hutchings. set designed by Stephen Hutchings.
The main window is split in two, or optionally three, panels. The left-most contains the project The main window is split in two, or optionally three, panels. The left-most panel contains the
tree and all the documents in your project. The second panel is the document editor, and the project tree and all the documents in your project. The second panel is the document editor, and
optional third panel is a document viewer which can view any document in your project. the optional third panel is a document viewer which can view any document in your project
independently of the document editor.
A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the
entire novel structure can be displayed, with all the tags and references listed. Depending on how entire novel structure can be displayed, with all the tags and references listed. Depending on how
@@ -69,7 +70,7 @@ itself as it appears in the text of the documents.
Project Layout Project Layout
============== ==============
You are free to structure your project documents as you wish in subfolders, and split the text You are free to organise your project documents as you wish into subfolders, and split the text
between documents in whatever way suits you. All that matters to novelWriter is the linear order between documents in whatever way suits you. All that matters to novelWriter is the linear order
the documents appear at in the project tree (top to bottom). The chapters, scenes and sections of the documents appear at in the project tree (top to bottom). The chapters, scenes and sections of
the novel are determined by the headings within those documents. the novel are determined by the headings within those documents.
@@ -83,7 +84,7 @@ The four heading levels (**H1** to **H4**) are treated as follows:
This header level structure is only taken into account for novel documents. For the project notes, This header level structure is only taken into account for novel documents. For the project notes,
the header levels have no structural meaning, and the user is free to do whatever they want. See the header levels have no structural meaning, and the user is free to do whatever they want. See
the :ref:`a_struct` and :ref:`a_notes` pages for more details. :ref:`a_struct` and :ref:`a_notes` for more details.
.. _a_intro_export: .. _a_intro_export:
@@ -106,8 +107,7 @@ Python dictionary with a couple of lines of code.
A number of filter options can be applied to the produced document, allowing you to export a draft A number of filter options can be applied to the produced document, allowing you to export a draft
manuscript, a reference document of notes, an outline based on chapter and scene titles with a manuscript, a reference document of notes, an outline based on chapter and scene titles with a
synopsis each, and so on. See the :ref:`a_export` page for more details on export features and synopsis each, and so on. See :ref:`a_export` for more details on export features and formats.
formats.
.. _a_intro_screenshots: .. _a_intro_screenshots:
docs/source/int_started.rst
+9 -8
View File
@@ -7,7 +7,7 @@ Getting Started
This is a brief guide to how you can get novelWriter running on your computer. These are the This is a brief guide to how you can get novelWriter running on your computer. These are the
methods currently supported by the developer. Packages may also be available in other package methods currently supported by the developer. Packages may also be available in other package
managers, but those are not managed by the developer. A Windows installer file is also provided on managers, but those are not managed by the developer. A Windows installer file is also provided on
the GitHub page and on the main website. the GitHub releases page and linked from the `main website`_.
As novelWriter matures, more options for how to install it and get it running will be added. For As novelWriter matures, more options for how to install it and get it running will be added. For
non-Windows users the install process is at the present time best suited for people used to working non-Windows users the install process is at the present time best suited for people used to working
@@ -19,6 +19,8 @@ with the command line. But even if you're not, the install process is fairly str
Linux, the scripts can also be made executable and run without the ``python`` command. Likewise, Linux, the scripts can also be made executable and run without the ``python`` command. Likewise,
``pip`` may need to be replaced with ``pip3``. ``pip`` may need to be replaced with ``pip3``.
.. _main website: https://novelwriter.io
.. _a_started_install: .. _a_started_install:
@@ -26,7 +28,7 @@ Installing and Running
====================== ======================
The application is written in Python 3 using Qt5 via PyQt5. It is developed on Linux, but it should The application is written in Python 3 using Qt5 via PyQt5. It is developed on Linux, but it should
in principle work fine on other operating systems as well as long as dependencies are met. in principle work fine on other operating systems as long as dependencies are met.
You can download the latest version of novelWriter from the source repository on GitHub_. You can download the latest version of novelWriter from the source repository on GitHub_.
novelWriter is also hosted on PyPi_, and can be installed on all operating systems that support Qt5 novelWriter is also hosted on PyPi_, and can be installed on all operating systems that support Qt5
@@ -177,11 +179,9 @@ Windows Installer
You can install novelWriter with the Windows installer for 64-bit Windows available on the You can install novelWriter with the Windows installer for 64-bit Windows available on the
`main website`_ and GitHub_ page. This installer bundles all that is needed for novelWriter to run, `main website`_ and GitHub_ page. This installer bundles all that is needed for novelWriter to run,
including Python and the xml and Qt libraries. When installing novelWriter this way, you don't need including Python and the XML and Qt libraries. When installing novelWriter this way, you don't need
to install any of the dependencies manually. The installer is made with pyinstaller and Inno Setup. to install any of the dependencies manually. The installer is made with pyinstaller and Inno Setup.
.. _main website: https://novelwriter.io
.. _a_started_win_source: .. _a_started_win_source:
@@ -192,7 +192,8 @@ To run from source, you may first need to install Python. If you don't have it i
download it from the python.org_ website. novelWriter should work with Python 3.6 or higher, but it download it from the python.org_ website. novelWriter should work with Python 3.6 or higher, but it
is recommended that you install the latest version of Python. is recommended that you install the latest version of Python.
Also, make sure you select the "Add Python to PATH" option during installation. Also, make sure you select the "Add Python to PATH" option during installation, otherwise the
``python`` command will not work in the command line window.
.. image:: images/python_win_install.png .. image:: images/python_win_install.png
:width: 600 :width: 600
@@ -245,7 +246,8 @@ The documentation can then be built from the ``docs`` folder in the source code
make html make html
If successful, the documentation should be available in the ``docs/build/html`` folder. If successful, the documentation should be available in the ``docs/build/html`` folder and you can
open the ``index.html`` file in your browser.
The documentation can also be built for the Qt Assistant. To build the help packages from the The documentation can also be built for the Qt Assistant. To build the help packages from the
documentation source, run the following from the root source folder: documentation source, run the following from the root source folder:
@@ -263,4 +265,3 @@ locally first, then send you to the website as a fallback.
In order for the local version of help to work, the Qt Assistant must be installed on the local In order for the local version of help to work, the Qt Assistant must be installed on the local
computer. If it isn't available, or novelWriter cannot find it, the help feature will fall back computer. If it isn't available, or novelWriter cannot find it, the help feature will fall back
to redirecting you to the documentation website. to redirecting you to the documentation website.
docs/source/int_typography.rst
+7 -7
View File
@@ -34,10 +34,10 @@ Single and Double Quotes
All the different quotation marks listed on the `Quotation Mark`_ Wikipedia page are available, and 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 can be selected as auto-replaced symbols for straight single and double quote key strokes. The
settings can be found in the :guilabel:`Preferences`. settings can be found in :guilabel:`Preferences`.
Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience 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 the for highlighting dialogue between characters. This feature can be disabled in
:guilabel:`Preferences` if this feature isn't wanted. :guilabel:`Preferences` if this feature isn't wanted.
The editor distinguishes between text wrapped in straight quotes and with the user-selected double The editor distinguishes between text wrapped in straight quotes and with the user-selected double
@@ -48,21 +48,21 @@ re-format a selected section of text with the correct quote symbols.
.. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark .. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark
Modifier Letter Apostrophes Modifier Letter Apostrophe
--------------------------- --------------------------
The auto-replace feature will consider any right-facing single straight quote as a quote symbol, The auto-replace feature will consider any right-facing single straight quote as a quote symbol,
even if it's intended as an apostrophe. This also includes the syntax highlighter, which may assume even if it's 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. 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 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 renderred the same way as right is not categorised as punctuation, but as a modifier. It is usually renderred the same way as the
single quotation marks, but not always, depending on the font. There is a Wikipedia article for the right single quotation marks, depending on the font. There is a Wikipedia article for the
`Modifier letter apostrophe`_ with more details. `Modifier letter apostrophe`_ with more details.
.. note:: .. note::
On export with the :guilabel:`Build Novel Project` tool, these apostrophes will be replaced On export with the :guilabel:`Build Novel Project` tool, these apostrophes will be replaced
automatically with the corresponding right hand quote symbols as is generally recommended. 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 highlighting. Therefore it doesn't really matter if you only use them to correct highlighting.
.. _Modifier letter apostrophe: https://en.wikipedia.org/wiki/Modifier_letter_apostrophe .. _Modifier letter apostrophe: https://en.wikipedia.org/wiki/Modifier_letter_apostrophe
docs/source/tech_technical.rst
+8 -7
View File
@@ -7,8 +7,8 @@ Technical Information
This section contains details of how novelWriter stores and handles the project data. This section contains details of how novelWriter stores and handles the project data.
How Data is Stored How Project Data is Stored
================== ==========================
All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix
line endings to Windows line endings on Windows systems, novelWriter does not make any adaptations line endings to Windows line endings on Windows systems, novelWriter does not make any adaptations
@@ -20,13 +20,14 @@ operating systems.
Main Project File Main Project File
----------------- -----------------
The project itself requires a dedicated folder for storing its files, where novelWriter will create The project itself requires a dedicated folder for storing its files where novelWriter will create
its own "file system" where the folder and file hierarchy is described in a project XML file. This its own "file system" where the folder and file hierarchy is described in a project XML file. This
is the main project file in the project's root folder with the name ``nwProject.nwx``. This file is the main project file in the project's root folder with the name ``nwProject.nwx``. This file
also contains all the meta data required for the project, and a number of related project settings. also contains all the meta data required for the project, and a number of related project settings.
If this file is lost or corrupted, the structure of the project is lost. It is important to keep If this file is lost or corrupted, the structure of the project is lost, although not the text
this file backed up, either through the built-in backup tool, or your own backup solution. itself. It is important to keep this file backed up, either through the built-in backup tool, or
your own backup solution.
.. tip:: .. tip::
The novelWriter project folder is structured so that it can easily be added to a version control The novelWriter project folder is structured so that it can easily be added to a version control
@@ -36,7 +37,7 @@ this file backed up, either through the built-in backup tool, or your own backup
The project XML file is indent-formatted, suitable for diff tools and version control since most of The project XML file is indent-formatted, suitable for diff tools and version control since most of
the file will stay static, although a timesetamp is set in the meta section on line 2 each time the the file will stay static, although a timesetamp is set in the meta section on line 2 each time the
file is saved. file is saved, and various meta data entries are incremented on each save.
Project Documents Project Documents
@@ -50,7 +51,7 @@ hash and the file extension ``.nwd``.
If you wish to find the physical location of a document in the project, you can either look it up If you wish to find the physical location of a document in the project, you can either look it up
in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu
when having the document open, or look in the ``ToC.txt`` file in the root of the project folder. when having the document open, or look in the ``ToC.txt`` file in the root of the project folder.
The ``ToC.txt`` file has a list of all document files in the project and where they are saved. The ``ToC.txt`` file has a list of all documents in the project and where they are saved.
The reason for this cryptic file naming is to avoid issues with file naming conventions and The reason for this cryptic file naming is to avoid issues with file naming conventions and
restrictions on different operating systems, and also to have a file name that does not depend on restrictions on different operating systems, and also to have a file name that does not depend on
docs/source/write_export.rst
+28 -27
View File
@@ -14,7 +14,7 @@ Header Formatting
================= =================
The titles for the five types of titles (the chapter headings come in a numbered and unnumbered The titles for the five types of titles (the chapter headings come in a numbered and unnumbered
version) of story structure can be formatted collectively in the export tool. This is done through version) of story structure can be formatted collectively in the build tool. This is done through
a series of keyword–replace steps. They are all on the format ``%keyword%``. a series of keyword–replace steps. They are all on the format ``%keyword%``.
``%title%`` ``%title%``
@@ -22,20 +22,20 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``.
your document. your document.
``%ch%`` ``%ch%``
This is replaced by a chapter number. The number is incremented by one each time the build tool This will be replaced by a chapter number. The number is incremented by one each time the build
sees a new heading of level two in a document with layout :guilabel:`Chapter`. If the document tool sees a new heading of level two in a document with layout :guilabel:`Chapter`. If the
has layout :guilabel:`Unnumbered`, the counter is *not* incremented. The latter is useful for document has layout :guilabel:`Unnumbered`, the counter is *not* incremented. The latter is
for instance Prologue and Epilogue chapters. useful for for instance Prologue and Epilogue chapters. Adding an asterisk (``*``) in front of
the title text of a level two heading will also disable the chapter counter for that heading.
``%chw%`` ``%chw%``
This is like ``%ch%``, but the number is expressed as a word like for instance "One", "Two", Behaves like ``%ch%``, but the number is represented as a number word.
etc.
``%chi%`` ``%chi%``
This is also like ``%ch%``, but the number is represented as a lower case Roman number. Begaves like ``%ch%``, but the number is represented as a lower case Roman number.
``%chI%`` ``%chI%``
This is also like ``%ch%``, but the number is represented as an upper case Roman number. Behaves like ``%ch%``, but the number is represented as an upper case Roman number.
``%sc%`` ``%sc%``
This is the number counter equivalent for scenes. These are incremented each time a heading of This is the number counter equivalent for scenes. These are incremented each time a heading of
@@ -43,8 +43,8 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``.
used for counting scenes within a chapter. used for counting scenes within a chapter.
``%sca%`` ``%sca%``
This is like ``%sc%``, but the number is *not* reset to 1 for each chapter. Instead it runs from Behaves like ``%sc%``, but the number is *not* reset to 1 for each chapter. Instead it runs from
1 from the beginning of the novel. 1 from the beginning of the novel to produce an absolute scene count.
``\\`` ``\\``
This inserts a line break within the title. This inserts a line break within the title.
@@ -67,11 +67,12 @@ Scene Separators
================ ================
If you don't want any titles for your scenes (or for your sections if you have them), you can leave If you don't want any titles for your scenes (or for your sections if you have them), you can leave
the boxes empty. If so, an empty paragraph will be inserted between the scenes or sections instead. the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or
sections instead.
Alternatively, if you want a separator between them, like the common ``* * *``, you can also enter Alternatively, if you want a separator between them, like the common ``* * *``, you can enter the
that in the box. In fact, if the format is a piece of static text, it will always be treated as a desired separator text in the formatting box. In fact, if the format is a piece of static text, it
separator. will always be treated as a separator.
.. _a_export_files: .. _a_export_files:
@@ -82,8 +83,8 @@ File Selection
Which documents and notes are selected for export can be controlled from the options on the left Which documents and notes are selected for export can be controlled from the options on the left
side of the dialog window. The switch for :guilabel:`Include novel files` will select any document side of the dialog window. The switch for :guilabel:`Include novel files` will select any document
that isn't classified as a note. The switch for :guilabel:`Include note files` will select any that isn't classified as a note. The switch for :guilabel:`Include note files` will select any
document that *is* a note. This is allows for exporting just the novel, just your notes, or both, document that *is* a note. This allows for exporting just the novel, just your notes, or both, as
as you see fit. you see fit.
In addition, you can select to export the synopsis comments, regular comments, keywords, and even In addition, you can select to export the synopsis comments, regular comments, keywords, and even
exclude the body text itself. exclude the body text itself.
@@ -111,23 +112,23 @@ Currently, six formats are supported for exporting.
OpenDocument Format OpenDocument Format
This produces an open document ``.odt`` file. The document produced has very little formatting, This produces an open document ``.odt`` file. The document produced has very little formatting,
and may require further editing afterwards. For a better formatted office document, you may get and may require further editing afterwards. For a better formatted office document, you may get
a better result with exporting to HTML and then import that HTML document into your office word a better result by exporting to HTML and then importing that HTML document into your office word
processor. They are generally very good at importing HTML documents. processor. They are generally good at importing HTML documents.
PDF Format PDF Format
The PDF export is just a shortcut for print to file. For a better PDF result, you may instead The PDF export is just a shortcut for print-to-file. For a better PDF result, you may instead
want to export to HTML, and use a word processor to convert the HTML document to PDF. want to export to HTML and use a word processor to convert the HTML document to PDF.
novelWriter HTML novelWriter HTML
The HTML export format writes a single ``.htm`` file with minimal style formatting. The exported The HTML export format writes a single ``.htm`` file with minimal style formatting. The exported
HTML document is suitable for further processing by document conversion tools like Pandoc, for HTML document is suitable for further processing by document conversion tools like Pandoc, for
importing in word processors, or for printing from browser. It is generally the best formatted importing in word processors, or for printing from browser. It is generally the best formatted
export option and supports all features of novelWriter since it is entirely geenrated by the export option and supports all features of novelWriter since it is entirely generated by the
application and doesn't depend on Qt library features. application and doesn't depend on Qt library features.
novelWriter Markdown novelWriter Markdown
This is simply a concatenation of the project documents selected by the filters. The documents This is simply a concatenation of the project documents selected by the filters. The documents
are stacked together in the order they appear in the project tree, with comments, tags, etc. are stacked together in the order they appear in the project tree, with comments, tags, etc.
included if they are selected. This is a useful format for exporting the project for later included if they are selected. This is a useful format for exporting the project for later
import back into novelWriter. import back into novelWriter.
@@ -146,11 +147,11 @@ Additional Export Options
In addition to the above document formats, the novelWriter HTML and Markdown formats can also be In addition to the above document formats, the novelWriter HTML and Markdown formats can also be
wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also
accompanying css styles are exported. the accompanying css styles are exported.
The text body is saved in a two-level list. The outer list contains one entry per exported file, in The text body is saved in a two-level list. The outer list contains one entry per exported
the order they appear in the project tree. Each file is then split up into a list as well, with one document, in the order they appear in the project tree. Each document is then split up into a list
entry per paragraph in the document. as well, with one entry per paragraph it contains.
These files are mainly intended for scripted post-processing for those who want that option. A JSON These files are mainly intended for scripted post-processing for those who want that option. A JSON
file can be imported directly into a Python dict object or a PHP array, to mentions a few options. file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
docs/source/write_notes.rst
+9 -9
View File
@@ -4,16 +4,16 @@
Project Notes Project Notes
************* *************
novelWriter doesn't have a database and complicated forms to fill in all details about plot novelWriter doesn't have a database and complicated forms for filling in details about plot
elements, characters, and all sorts of additional information that isn't a part of the novel text elements, characters, and all sorts of additional information that isn't a part of the novel text
itself. Instead, all such information is saved in notes. The relation between all these additional itself. Instead, all such information is saved in notes. The relation between all these additional
elements is extracted from these documents by the project indexer based on the tags and references elements is extracted from the documents and notes by the project indexer, based on the tags and
you set. references you set within them.
These notes are not required, but making at least minimal files for each such plot element, and Using notes is not required, but making at least minimal notes for each plot element, and adding a
adding a tag to them, makes it possible to use the :guilabel:`Outline` feature to see how each tag to them, makes it possible to use the :guilabel:`Outline` feature to see how each element
element intersects with each section of the novel itself, and adds clickable cross-references intersects with each section of the novel itself, and adds clickable cross-references between
between documents in the editor and viewer. documents in the editor and viewer.
.. _a_notes_tags: .. _a_notes_tags:
@@ -43,5 +43,5 @@ meaningful if you want to be able to click-navigate between them.
.. tip:: .. tip::
If you cross-reference between notes and export your project as an HTML document using the If you cross-reference between notes and export your project as an HTML document using the
:guilabel:`Build Novel Project` tool, the cross-references become clickable in the exported :guilabel:`Build Novel Project` tool, the cross-references become clickable links in the
HTML document as well. exported HTML document.
docs/source/write_projects.rst
+30 -24
View File
@@ -5,7 +5,7 @@ Novel Projects
************** **************
A novelWriter project requires a dedicated folder for storing its files on the local file system. A novelWriter project requires a dedicated folder for storing its files on the local file system.
See the :ref:`a_tech` page for further details on how files are organised. See :ref:`a_tech` for further details on how files are organised.
A new project can be created from the :guilabel:`Project` menu by selecting A new project can be created from the :guilabel:`Project` menu by selecting
:guilabel:`New Project`. This will open the :guilabel:`New Project Wizard` that will assist you in :guilabel:`New Project`. This will open the :guilabel:`New Project Wizard` that will assist you in
@@ -14,8 +14,8 @@ creating a barebone project suited to your needs.
A list of recently opened projects is maintained, and displayed in the :guilabel:`Open Project` A list of recently opened projects is maintained, and displayed in the :guilabel:`Open Project`
dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key. dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key.
The project specific settings are available in :guilabel:`Project Settings` in the Project-specific settings are available in :guilabel:`Project Settings` in the :guilabel:`Project`
:guilabel:`Project` menu. See further details below in the :ref:`a_proj_settings` section. menu. See further details below in the :ref:`a_proj_settings` section.
.. _a_proj_roots: .. _a_proj_roots:
@@ -28,7 +28,7 @@ the project tree at the left side of the main window.
The core novel documents go into a root folder of type :guilabel:`Novel`. Other supporting The core novel documents go into a root folder of type :guilabel:`Novel`. Other supporting
documents go into the other root folders. These other root folder types are intended for your notes documents go into the other root folders. These other root folder types are intended for your notes
on the various elements of your story. Using these is of course entirely optional. on the various elements of your story. Using them is of course entirely optional.
A new project may not have all of the root folders present, but you can add the ones you want from A new project may not have all of the root folders present, but you can add the ones you want from
:guilabel:`Create Root Folder` in the :guilabel:`Project` menu. :guilabel:`Create Root Folder` in the :guilabel:`Project` menu.
@@ -38,8 +38,8 @@ no restrictions are enforced by the application. You can use them however you wa
:guilabel:`Novel` :guilabel:`Novel`
This is the root folder of all text that goes into the final novel. This class of documents have This is the root folder of all text that goes into the final novel. This class of documents have
other rules and features than other documents in the project. See the :ref:`a_struct` page for other rules and features than other documents in the project. See :ref:`a_struct` for more
more details. details.
:guilabel:`Plot` :guilabel:`Plot`
This is the root folder where main plots can be outlined. It is optional, but adding at least This is the root folder where main plots can be outlined. It is optional, but adding at least
@@ -79,8 +79,8 @@ information about the tags listed, see :ref:`a_struct_tags`.
.. tip:: .. tip::
You can rename root folders to whatever you want. The first character in the :guilabel:`Flags` You can rename root folders to whatever you want. The first character in the :guilabel:`Flags`
column will still indicate what type they are, and so will the icon if you are using one of the column in the project tree will still indicate what type they are, and so will the icon if you
Typicons icon sets. are using one of the optional icon sets.
.. _a_proj_roots_del: .. _a_proj_roots_del:
@@ -157,7 +157,8 @@ this warning, and continue opening the project at your own risk.
If you choose to ignore the warning and continue opening the project, and multiple instances of If you choose to ignore the warning and continue opening the project, and multiple instances of
the project are in fact open, you are likely to cause inconsistencies and create diverging the project are in fact open, you are likely to cause inconsistencies and create diverging
project files, potentially resulting in loss of data and orphaned files. You are not likely to project files, potentially resulting in loss of data and orphaned files. You are not likely to
lose any actual text unless both instances have the same document open in the editor, lose any actual text unless both instances have the same document open in the editor, and
novelWriter will try to resolve inconsistencies the next time you open the project.
.. _a_proj_roots_dirs: .. _a_proj_roots_dirs:
@@ -174,9 +175,9 @@ and to be able to collapse and hide them in the project tree when you're not wor
documents. documents.
.. tip:: .. tip::
You can use folders to sort your scene documents into chapters. You will then need to add a You can use folders to sort your scene documents into chapters. You will still need to add a
chapter documents as the first item of your folder, and the scene documents as the following chapter document as the first item of your chapter folder, and the scene documents as the
items. following items.
.. _a_proj_files: .. _a_proj_files:
@@ -243,13 +244,17 @@ The :guilabel:`Book Title` and :guilabel:`Book Authors` settings are currently n
anything, so setting then is just for the benefit of the author. Future features may be using them, anything, so setting then is just for the benefit of the author. Future features may be using them,
and they are exported on some export formats in the :guilabel:`Build Novel Project` tool. and they are exported on some export formats in the :guilabel:`Build Novel Project` tool.
If your project is in a different language than your main spell checking is set to, you can
override the default spell checking language here. You can also override the automatic backup
setting.
Details Tab Details Tab
----------- -----------
This tab presents an overview of meta data for the project. It states where on your file system the This tab presents an overview of technical meta data for the project. It states where on your file
project is saved, how may times it has been saved, how many folders and documents it contains, and system the project is saved, how may times it has been saved, how many folders and documents it
how many words exist in the entire project. contains, and how many words exist in the entire project.
Status and Importance Tabs Status and Importance Tabs
@@ -277,13 +282,14 @@ A set of automatically replaced keywords can be added in this tab. The keywords
will be replaced by the text in the right column when documents are opened in the viewer. They will will be replaced by the text in the right column when documents are opened in the viewer. They will
also be applied to exports. also be applied to exports.
The auto-replace feature will replace text in angle brackets that are also in this list. The syntax The auto-replace feature will replace text in angle brackets that are in this list. The syntax
highlighter will add an alternate colour to text marching the syntax. highlighter will add an alternate colour to text marching the syntax, but it doesn't check if the
text is in this list.
.. note:: .. note::
A keyword cannot contain any spaces. The angle brackets are added by default, and when used in A keyword cannot contain spaces. The angle brackets are added by default, and when used in the
the text are a part of the keyword to be replaced. This is to ensure that parts of the text text are a part of the keyword to be replaced. This is to ensure that parts of the text aren't
aren't unintentionally replaced by the content of the list. unintentionally replaced by the content of the list.
.. _a_proj_backup: .. _a_proj_backup:
@@ -295,9 +301,9 @@ An automatic backup system is built into novelWriter. In order to use it, a back
the backup files are to be stored must be provided in :guilabel:`Preferences`. the backup files are to be stored must be provided in :guilabel:`Preferences`.
Backups can be run automatically when a project is closed, which also implies it is run when the Backups can be run automatically when a project is closed, which also implies it is run when the
application is closed. Backups are date stamped zip files of the entire project folder, and are application itself is closed. Backups are date stamped zip files of the entire project folder, and
stored in a subfolder of the backup path with the same name as the project :guilabel:`Working are stored in a subfolder of the backup path. The subfolder will have the same name as the project
Title` set in :ref:`a_proj_settings`. :guilabel:`Working Title` set in :ref:`a_proj_settings`.
The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu. The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu.
It is also possible to disable automated backup for a given project in :guilabel:`Project It is also possible to disable automated backup for a given project in :guilabel:`Project
@@ -306,7 +312,7 @@ Settings`.
.. note:: .. note::
For the backup to be able to run, the :guilabel:`Working Title` must be set in For the backup to be able to run, the :guilabel:`Working Title` must be set in
:guilabel:`Project Settings`. This value is used to generate the folder name for the zip files. :guilabel:`Project Settings`. This value is used to generate the folder name for the zip files.
Without it, the backup will not run at all, but produce a warning message. Without it, the backup will not run at all, but it will produce a warning message.
.. _a_proj_stats: .. _a_proj_stats:
docs/source/write_structure.rst
+26 -25
View File
@@ -18,20 +18,21 @@ Importance of Headings
Subfolders under root folders have no impact on the structure of the novel itself. The structure is Subfolders under root folders have no impact on the structure of the novel itself. The structure is
instead dictated by the heading level of the headers within the documents. instead dictated by the heading level of the headers within the documents.
Four levels of headings are supported, signified by the number of hashes preceding the title. See Four levels of headings are supported, signified by the number of hashes (``#``) preceding the
also the :ref:`a_ui_md` section for more details about the markdown syntax. title. See also the :ref:`a_ui_md` section for more details about the markdown syntax.
.. note:: .. note::
The header levels are not only important when generating the exported novel file, they are also The header levels are not only important when generating the exported novel file, they are also
used by the indexer when building the outline tree in the :guilabel:`Outline` tab. Each heading used by the indexer when building the outline tree in the :guilabel:`Outline` tab. Each heading
also starts a new region where new references to tags can be set. also starts a new region where new references and tags can be set.
The different header levels are interpreted as specific section types of the novel in the following The different header levels are interpreted as specific section types of the novel in the following
way: way:
``# Header1`` ``# Header1``
Header level one signifies that the text refers to either the novel title or the name of a top Header level one signifies that the text refers to either the novel title or the name of a top
level partition useful when you want to split the manuscript up into books, parts, or acts. level partition. The latter is useful when you want to split the manuscript up into books,
parts, or acts.
``## Header2`` ``## Header2``
Header level two signifies a chapter level partition. Each time you want to start a new chapter, Header level two signifies a chapter level partition. Each time you want to start a new chapter,
@@ -47,8 +48,8 @@ way:
manuscript. manuscript.
``#### Header4`` ``#### Header4``
Header level four signifies a sub-scene level partition, usually called just a section in the Header level four signifies a sub-scene level partition, usually called a "section" in the
documentation and user interface. These can be useful if you want to change tag references documentation and the user interface. These can be useful if you want to change tag references
mid-scene, like if you change the point-of-view character. You are free to use sections as you mid-scene, like if you change the point-of-view character. You are free to use sections as you
wish, and can filter the titles out of the final manuscript just like with scene titles. wish, and can filter the titles out of the final manuscript just like with scene titles.
@@ -67,7 +68,7 @@ If you use layout types for your documents, the automatic numbering feature for
controlled by whether you use the :guilabel:`Chapter` or :guilabel:`Unnumbered` layout type for controlled by whether you use the :guilabel:`Chapter` or :guilabel:`Unnumbered` layout type for
your document. However, if you have a different document layout where this isn't practical, you can your document. However, if you have a different document layout where this isn't practical, you can
also switch off chapter numbering for a chapter by making the first character of the chapter title also switch off chapter numbering for a chapter by making the first character of the chapter title
an ``*``. Like so: an asterisk (``*``). Like so:
``## *Unnumbered Chapter Title`` ``## *Unnumbered Chapter Title``
@@ -87,7 +88,7 @@ Tag References
Each text partition indicated by a heading of any level, can contain references to tags set in the Each text partition indicated by a heading of any level, can contain references to tags set in the
supporting notes of the project. The references are gathered by the indexer and used to generate supporting notes of the project. The references are gathered by the indexer and used to generate
the outline view on the :guilabel:`Outline` tab of how the different parts of the novel are an outline view on the :guilabel:`Outline` tab of how the different parts of the novel are
connected. connected.
References and tags are also clickable in the document editor and viewer, making it easy to References and tags are also clickable in the document editor and viewer, making it easy to
@@ -103,7 +104,7 @@ allow multiple values.
``@char`` ``@char``
Other characters in the current section. The target must be a note tag in a Other characters in the current section. The target must be a note tag in a
:guilabel:`Character` type root folder. This should not include the point-of-view character(s). :guilabel:`Character` type root folder. This should not include the point-of-view character.
``@plot`` ``@plot``
The plot or subplot advanced in the current section. The target must be a note tag in a The plot or subplot advanced in the current section. The target must be a note tag in a
@@ -142,15 +143,15 @@ the index for a document is regenerated when it is saved, so this shouldn't norm
Novel Document Layout Novel Document Layout
===================== =====================
All documents in a novelWriter project can have a layout format set. These layouts are important All documents in the project can have a layout format set. These layouts are important when the
when the project is exported as they indicate how to treat the content in terms of formatting, project is exported as they indicate how to treat the content in terms of text formatting,
headings, and page breaks. The layout for each document is indicated as the last set of characters headings, and page breaks. The layout for each document is indicated as the last set of characters
in the :guilabel:`Flags` column of the project tree. in the :guilabel:`Flags` column of the project tree.
Not all layout types are actually treated differently, they also help to indicate what each Not all layout types are actually treated differently, they also help to indicate what each
document is for in your project. The :guilabel:`Book` layout is a generic novel document layout document is intended for in your project. The :guilabel:`Book` layout is a generic novel document
that is formatted identically to :guilabel:`Chapter` and :guilabel:`Scene` layout documents, but layout that is formatted identically to :guilabel:`Chapter` and :guilabel:`Scene` layout documents,
may help to indicate what each document does in your project. but may help to indicate what each document does in your project.
You can for instance lay out your project using :guilabel:`Book` documents for each act, and then You can for instance lay out your project using :guilabel:`Book` documents for each act, and then
later split those into chapter or scene documents by using the :guilabel:`Split Document` tool. later split those into chapter or scene documents by using the :guilabel:`Split Document` tool.
@@ -163,15 +164,15 @@ Some layouts *do* have implications on how the project is exported. Documents wi
contained within it. The latter is convenient for Prologue and Epilogue type chapters. contained within it. The latter is convenient for Prologue and Epilogue type chapters.
The above layout formats are only usable in the Novel root folder. Documents that are not a part of The above layout formats are only usable in the Novel root folder. Documents that are not a part of
the novel itself should have the Note layout. These documents are not getting any special the novel itself should have the :guilabel:`Note` layout. These documents are not getting any
formatting, and it is possible to collectively filter them out during export. Notes can be used special formatting, and it is possible to collectively filter them out during export. Notes can be
anywhere in the project, also in the Novel root folder. used anywhere in the project, also in the :guilabel:`Novel` root folder.
Below is an overview of all available layout formats. Below is an overview of all available layout formats.
:guilabel:`Title Page` :guilabel:`Title Page`
The title page layout. The title should be formatted as a heading level one. All text is The title page layout. The title should be formatted as a heading level one. All text is centred
automatically centred on exports. on export.
:guilabel:`Plain Page` :guilabel:`Plain Page`
A plain page layout useful for instance for front matter pages. Heading levels are ignored for A plain page layout useful for instance for front matter pages. Heading levels are ignored for
@@ -184,7 +185,7 @@ Below is an overview of all available layout formats.
produce the same result as a collection of :guilabel:`Partition`, :guilabel:`Chapter` and produce the same result as a collection of :guilabel:`Partition`, :guilabel:`Chapter` and
:guilabel:`Scene` layout documents. However, it does not provide the functionality of the :guilabel:`Scene` layout documents. However, it does not provide the functionality of the
:guilabel:`Unnumbered` layout format by default, but this can still be achieved by prefixing the :guilabel:`Unnumbered` layout format by default, but this can still be achieved by prefixing the
chapter title with a ``*``. chapter title with an asterisk (``*``).
:guilabel:`Partition` :guilabel:`Partition`
A partition can be used to split the novel into parts. Partition titles are indicated with a A partition can be used to split the novel into parts. Partition titles are indicated with a
@@ -200,7 +201,7 @@ Below is an overview of all available layout formats.
text. text.
:guilabel:`Unnumbered` :guilabel:`Unnumbered`
Same as :guilabel:`Chapter`, but when exporting the documents and automatic chapter numbering is Same as :guilabel:`Chapter`, but when exporting the project, and automatic chapter numbering is
enabled, documents with this layout will not increment the chapter number. It also has a enabled, documents with this layout will not increment the chapter number. It also has a
separate title formatting setting. This makes the layout suitable for Prologue and Epilogue type separate title formatting setting. This makes the layout suitable for Prologue and Epilogue type
chapters. chapters.
@@ -210,10 +211,10 @@ Below is an overview of all available layout formats.
headers of level four, but there are no layout specifically for sections. headers of level four, but there are no layout specifically for sections.
:guilabel:`Note` :guilabel:`Note`
A generic document that is optionally ignored when the novel is exported. Use this layout for A generic document that is optionally ignored when the novel project is exported. Use this
descriptions of content in the supporting root folders. Notes can also be added to the layout for descriptions of content in the supporting root folders. Notes can also be added to
:guilabel:`Novel` root folder if you need to insert notes there. Note headers receive no special the :guilabel:`Novel` root folder if you need to insert notes there. Note headers receive no
formatting when building the project. They are always exported as-is. special formatting when building the project. They are always exported as-is.
.. note:: .. note::
The layout granularity is entirely optional. In principle, you can write the entire novel in a The layout granularity is entirely optional. In principle, you can write the entire novel in a