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

Update the Using novelWriter section of the docs

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2023-10-08 20:54:14 +02:00
parent a3fdb3cfc4
commit 328216d9e5
21 changed files with 599 additions and 488 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/usage_breakdown.rst
+70 -57
View File
@@ -6,12 +6,11 @@ How it Works
.. _Fusion: https://doc.qt.io/qt-6/gallery.html
.. _Pandoc: https://pandoc.org/
.. _Typicons: https://github.com/stephenhutchings/typicons.font
.. _Open Document: https://en.wikipedia.org/wiki/OpenDocument
The main features of novelWriter are listed in the :ref:`a_intro` section. Here, we go into some
more details on how they are implemented. This is intended as an overview. Later on in this
documentation, these features will be covered in even more detail.
documentation, these features will be covered in more detail.
.. _a_breakdown_design:
@@ -23,9 +22,9 @@ The user interface of novelWriter is intended to be as minimalistic as practical
at the same time provide a complete set of features needed for writing a novel.
The main window does not have an editor toolbar like many other applications do. This reduces
clutter, and since the documents are formatted with style tags, is more or less redundant. However,
most formatting features supported are available through convenient keyboard shortcuts. They are
also available in the main menu so you don't have to look up formatting codes every time you need
clutter, and since the documents are formatted with style tags, it is more or less redundant.
Most formatting features supported are available through convenient keyboard shortcuts. They are
also available in the main menu, so you don't have to look up formatting codes every time you need
them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` section.
.. note::
@@ -34,46 +33,55 @@ them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` sec
Formatting is limited to headers, emphasis, text alignment, and a few other simple features.
On the left edge of the main window, you will find a sidebar. This bar has buttons for the standard
views you can switch between, a quick link to the :guilabel:`Build Novel Project` tool, and a set
of project-related tools as well as quick access to settings at the bottom.
views you can switch between, a quick link to the :guilabel:`Build Manuscript` tool, and a set of
project-related tools and quick access to settings at the bottom.
Project Tree View
-----------------
.. figure:: images/fig_project_tree_view.png
A screenshot of the Project Tree View.
When in :guilabel:`Project Tree View` mode, the main work area of the main window is split in two,
or optionally three, panels. The left-most panel contains the project tree and all the documents in
your project. The second panel is the document editor. An optional third panel on the right is a
document viewer which can view any document in your project independently of what is open in the
document editor. This panel is not intended as a preview window, although you can use it for this
if you wish as it will apply the formatting tags you have specified. The main purpose of the viewer
is for viewing your notes next to your editor while you're writing.
your project. The second panel is the document editor. An optional third panel on the right
contains a document viewer which can view any document in your project independently of what is
open in the document editor. This panel is not intended as a preview window, although you can use
it for this purpose if you wish as it will apply the formatting tags you have specified. The main
purpose of the viewer is for viewing your notes next to your editor while you're writing.
The editor also has a :guilabel:`Focus Mode` you can toggle either from the menu, from the icon in
the editor header, or by pressing :kbd:`F8`. When :guilabel:`Focus Mode` is enabled, all the user
the editor's header, or by pressing :kbd:`F8`. When :guilabel:`Focus Mode` is enabled, all the user
interface elements other than the document editor itself are hidden away.
Novel Tree View
---------------
.. figure:: images/fig_novel_tree_view.png
A screenshot of the Novel Tree View.
When in :guilabel:`Novel Tree View` mode, the project tree is replaced by an overview of your novel
structure. Instead of showing individual documents, the tree now shows all headings of your novel
text. This includes multiple headings within the same document.
structure for a specific Novel :term:`root folder`. Instead of showing individual documents, the
tree now shows all headings of your novel text. This includes multiple headings within the same
document.
Each heading is indented according to the heading level. You can open and edit your novel documents
from this view as well. All headings contained in the currently open document should be highlighted
in the view to indicate which ones belong together.
in the view to indicate which ones belong together in the same document.
If you have multiple Novel root folders, the header of the novel view becomes a dropdown box. You
can then switch between them by clicking the "Outline of ..." text. You can also click the novel
icon button next to it.
can then switch between them by clicking the :guilabel:`Outline of ...` text. You can also click
the novel icon button next to it.
Generally, the novel view should update when you make changes to the novel structure, including
edits of the current document in the editor. The information is only updated when the automatic
save of the document is initiated though. You can adjust the aut-save interval in
:guilabel:`Preferences`. You can also regenerate the whole novel view by pressing the refresh
button at the top.
save of the document is triggered, or you manually press :kbd:`Ctrl+S` to save changes. You can
adjust the auto-save interval in :guilabel:`Preferences`. You can also regenerate the whole novel
view by pressing the refresh button at the top of the side panel.
It is possible to show an optional third column in the novel view, The settings are available from
the menu button ath the top.
@@ -85,6 +93,10 @@ meta data collected for that heading entry.
Novel Outline View
------------------
.. figure:: images/fig_outline_view.png
A screenshot of the Novel Outline View.
When in :guilabel:`Novel Outline View` mode, the tree, editor and viewer will be replaced by a
large table that shows the entire novel structure with all the tags and references listed. Pretty
much all collected meta data is available here in different columns.
@@ -97,20 +109,18 @@ The app will remember you column order and size between sessions, and for each i
Colour Themes
-------------
The default colour theme of the user interface is the default theme from the Qt library. By
default, novelWriter is loaded with the Fusion_ style setting. (You can override this with the
``--style=`` setting when starting novelWriter.)
By default, novelWriter will use the colour theme provided by the Qt library, which is determined
by the Fusion_ style setting. You can also choose between a standard dark and light theme that have
neutral colours from :guilabel:`Preferences`. Other colour themes are also available, and more can
be contributed by users to the project.
There is a standard dark theme provided as well, which is similar to the default Qt theme. Some
other light and dark colour themes are also provided. You can select which one you prefer from in
:guilabel:`Preferences` .
A number of syntax highlighting themes are also available in :guilabel:`Preferences`. These are
separate settings because there are a lot more options for syntax highlighting.
Switching the GUI colour theme does not affect the colours of the editor and viewer. They have
separate colour themes called :guilabel:`Editor Themes`. They are separated because there are a lot
more options to choose from for the editor and viewer.
.. note::
If you switch to dark mode on the GUI, you should also switch syntax highlighting theme to
match, otherwise icons may be hard to see in the editor and viewer.
If you switch to dark mode on the GUI, you should also switch editor theme to match, otherwise
icons may be hard to see in the editor and viewer.
.. _a_breakdown_project:
@@ -127,6 +137,10 @@ you. All that matters to novelWriter is the linear order the documents appear at
tree (top to bottom). The chapters, scenes and sections of the novel are determined by the headings
within those documents.
.. figure:: images/fig_header_levels.png
An illustration of how header levels correspond to the novel structure.
The four heading levels (**H1** to **H4**) are treated as follows:
* **H1** is used for the book title, and for partitions.
@@ -136,14 +150,14 @@ The four heading levels (**H1** to **H4**) are treated as follows:
The project tree will select an icon for the document based on the first heading in it.
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
:ref:`a_struct` and :ref:`a_notes` for more details.
This header level structure is only taken into account for :term:`novel documents`. For
:term:`project notes`, the header levels have no structural meaning, and the user is free to do
whatever they want. See :ref:`a_struct` and :ref:`a_notes` for more details.
.. note::
You can add documents as child items of other documents if you wish. This is often more useful
than adding folders, since you anyway may want to have the chapter heading in a separate
document from your individual scene documents.
.. versionadded:: 2.0
You can add documents as child items of other documents. This is often more useful than adding
folders, since you anyway may want to have the chapter heading in a separate document from your
individual scene documents so that you can rearrange scene documents freely.
.. _a_breakdown_export:
@@ -152,23 +166,23 @@ Building the Manuscript
=======================
The project can at any time be assembled into a range of different formats through the
:guilabel:`Build Novel Project` tool. Natively, novelWriter supports `Open Document`_, HTML5, and
:guilabel:`Build Manuscript` tool. Natively, novelWriter supports `Open Document`_, HTML5, and
various flavours of Markdown.
The HTML5 format is suitable for conversion by a number of other tools like Pandoc_, or for
importing into word processors if the Open Document format isn't suitable. In addition, printing
and printing to PDF is also possible.
is also possible. Print to PDF is available from the print dialog.
You can also export the content of the project to a JSON file. This is useful if you want to write
your own processing script in for instance Python, as the entire novel can be read into a Python
dictionary with a couple of lines of code. The JSON file can be populated either with HTML
formatted text, or with the raw text as typed into the novel documents. See :ref:`a_export_options`
for more details.
In addition, you can export the content of the project to a JSON file. This is useful if you want
to write your own custom processing script in for instance Python, as the entire novel can be read
into a Python dictionary with a couple of lines of code. The JSON file can be populated with either
HTML formatted text, or with the raw text as typed into the novel documents.
See :ref:`a_export_options` for more details.
A number of filter options can be applied to the :guilabel:`Build Novel Project` tool, allowing you
to make a draft manuscript, a reference document of notes, an outline based on chapter and scene
titles with a synopsis each, and so on. See :ref:`a_export` for more details on build features and
formats.
.. versionadded:: 2.1
You can now define multiple build definitions in the :guilabel:`Build Manuscript` tool. This
allows you to define specific settings for various types of draft documents, outline documents,
and manuscript formats. See :ref:`a_export` for more details.
.. _a_breakdown_storage:
@@ -184,10 +198,10 @@ details about what all the files mean and how they're organised, see the :ref:`a
This way of storing data was chosen for several reasons. Firstly, all the text you add to your
project is saved directly to your project folder in separate files. Only the project structure and
the text you are currently editing is stored in memory at any given time. Secondly, having multiple
small files means it is very easy to sync them between computers with standard file synchronisation
tools. Thirdly, if you use version control software to track the changes to your project, the file
formats used for the files are well suited. Also the JSON documents have line breaks and indents,
which makes it easier to track them with version control software.
small files means it is very easy to synchronise them between computers with standard file
synchronisation tools. Thirdly, if you use version control software to track the changes to your
project, the file formats used for the files are well suited. Also the JSON documents have line
breaks and indents, which makes it easier to track them with version control software.
.. note::
@@ -200,10 +214,9 @@ which makes it easier to track them with version control software.
You should not add additional files to the project folder yourself. Nor should you manually edit
files within it as a general rule. If you really must manually edit the text files, e.g. with
some automated task you want to perform, you need to rebuild the index when you open the project
again.
some automated task you want to perform, you need to rebuild the :term:`Project Index` when you
open the project again.
Editing text files in the ``content`` folder is less risky as they are just plain text. Editing
the main project XML file, however, may make the project file unreadable and you may crash
novelWriter and lose project structure information and project settings.