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/images/fig_editor.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

docs/source/images/fig_editor_search.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

docs/source/images/fig_header_levels.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

docs/source/images/fig_novel_tree_view.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

docs/source/images/fig_outline_view.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

docs/source/images/fig_project_tree_detailed.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 147 KiB

docs/source/images/fig_project_tree_view.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

docs/source/images/fig_references.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

docs/source/images/fig_viewer.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 133 KiB

docs/source/index.rst
+7 -10
View File
@@ -22,14 +22,9 @@ project structure is stored in a single project XML file. Other meta data is pri
JSON files. See the :ref:`a_breakdown_storage` section for more details.
Any operating system that can run Python 3 and has the Qt 5 libraries should be able to run
novelWriter. It runs fine on Linux, Windows and macOS, and users have tested it on other platforms
novelWriter. It runs fine on Linux, Windows and MacOS, and users have tested it on other platforms
as well. novelWriter can also be run directly from the Python source, or installed from packages or
the pip tool. See :ref:`a_started` for more details.
.. note::
Release 1.5 introduced a few changes that will require you to make some minor modifications to
some of the headings in your project. It should be fairly quick and straightforward. Please see
the :ref:`a_prjfmt_1_3` section for more details.
from pip. See :ref:`a_started` for more details.
**Useful Links**
@@ -56,9 +51,9 @@ the pip tool. See :ref:`a_started` for more details.
int_introduction
int_overview
int_started
int_source
int_howto
int_customise
int_glossary
.. toctree::
:maxdepth: 1
@@ -66,7 +61,8 @@ the pip tool. See :ref:`a_started` for more details.
:hidden:
usage_breakdown
usage_interface
usage_project
usage_writing
usage_format
usage_shortcuts
usage_typography
@@ -84,9 +80,10 @@ the pip tool. See :ref:`a_started` for more details.
.. toctree::
:maxdepth: 1
:caption: Under the Hood
:caption: Additional Topics
:hidden:
tech_locations
tech_storage
tech_source
tech_tests
docs/source/int_customise.rst
+5 -5
View File
@@ -79,11 +79,11 @@ folders are created the first time you start novelWriter.
Once the files are copied there, they should show up in :guilabel:`Preferences` with the label you
set as ``name`` inside the file.
.. note::
In novelWriter 2.0 the ``icontheme`` value was added to GUI themes. Make sure you set this value
in existing custom themes. Otherwise it defaults to ``typicons_light``, which may not match your
theme colour scheme. Otherwise, novelWriter will try to guess your icon theme, and may not pick
the most suitable one.
.. versionadded:: 2.0
The ``icontheme`` value was added to GUI themes. Make sure you set this value in existing custom
themes. Otherwise it defaults to ``typicons_light``, which may not match your theme colour
scheme. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most
suitable one.
Gustom GUI and Icons Theme
docs/source/int_glossary.rst
+30
View File
@@ -0,0 +1,30 @@
.. _a_glossary:
********
Glossary
********
.. glossary::
Root Folder
A "Root Folder" is a top level folder of the project tree in novelWriter. Each type of root
folder has a specific icon to identify it. For an overview of available root folder types,
see :ref:``
Novel Documents
These are documents that are created under a "Novel" :term:`root folder`.
Project Notes
...
Tag
...
Reference
...
Project Index
...
Context Menu
...
docs/source/int_overview.rst
+6 -3
View File
@@ -34,9 +34,12 @@ read on.
:ref:`a_breakdown` – Essential Information
This section explains the basics of how the application works and what it can and cannot do.
:ref:`a_ui` – Recommended Reading
This section will give you a more detailed explanation of what the various elements on the user
interface do and how you can use them more effectively.
:ref:`a_ui_project` – Recommended Reading
This section will give you a more detailed explanation of how you the user interface components
to organise and view your project work.
:ref:`a_ui_writing` – Recommended Reading
This section will give you a more detailed explanation of how the text editor and viewer work.
:ref:`a_fmt` – Essential Information
This section covers how you should format your text. The editor is plain text, so text
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.
docs/source/usage_format.rst
+47 -18
View File
@@ -10,8 +10,8 @@ values and allowing for some text formatting. The syntax is based on Markdown, b
(bold) and strikethrough text, as well as four levels of headings.
In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a set of
keyword and value sets used for tags and references. There are also some codes that apply two whole
paragraphs. See :ref:`a_fmt_text` below for more details.
keyword and value sets used for :term:`tags<tag>` and :term:`references<reference>`. There are also
some codes that apply to whole paragraphs. See :ref:`a_fmt_text` below for more details.
.. _a_fmt_hlight:
@@ -24,8 +24,13 @@ formtatting tags or other features correctly. It will change the colour and font
headings, change the text colour of emphasised text, and it can also show you where you have
dialogue in your text.
.. figure:: images/fig_references.png
An example of the colour highlighting of references. "Bob" is not defined, and "@blabla" is not
a valid reference type.
When you use the commands to set tags and references, these also change colour. Correct commands
have a dedicated colour, and the references themselves will get a colour if they are valid. Invalid
have a distinct colour, and the references themselves will get a colour if they are valid. Invalid
references will get a squiggly error line underneath. The same applies to duplicate tags.
There are a number of syntax highlighter colour themes available, both for light and dark GUIs. You
@@ -37,10 +42,14 @@ can select them for :guilabel:`Preferences`.
Headings
========
Four levels of headings are allowed. For project notes, they are free to be used as you see fit.
That is, novelWriter doesn't assign the different headings any particular meaning. However, for
novel documents they indicate the structural level of the novel and must be used correctly to
produce the intended result. See :ref:`a_struct_heads` for more details.
.. figure:: images/fig_header_levels.png
An illustration of how header levels correspond to the novel structure.
Four levels of headings are allowed. For :term:`project notes`, they are free to be used as you see
fit. That is, novelWriter doesn't assign the different headings any particular meaning. However,
for :term:`novel documents` they indicate the structural level of the novel and must be used
correctly to produce the intended result. See :ref:`a_struct_heads` for more details.
``# Title Text``
Heading level one. For novel documents, the header level indicates the start of a new partition.
@@ -87,10 +96,9 @@ paragraph.
In addition, the editor supports a few additional types of whitespaces:
* 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`,
:kbd:`Shift`:kbd:`Space`.
* Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`.
* A non-breaking space can be inserted with :kbd:`Ctrl+K`, :kbd:`Space`.
* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl+K`, :kbd:`Shift+Space`.
* Non-breaking thin space can be inserted with :kbd:`Ctrl+K`, :kbd:`Ctrl+Space`.
These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed
in :ref:`a_kb_ins`.
@@ -141,7 +149,6 @@ In addition, the following rules apply:
allow for formatting, and any formatting markup will be renderred as-is.
.. tip::
novelWriter supports standard escape syntax for the emphasis markup characters in case the
editor misunderstands your intended usage of them. That is, ``\*``, ``\_`` and ``\~`` will
generate a plain ``*``, ``_`` and ``~``, respectively, without interpreting them as part of the
@@ -183,15 +190,22 @@ Tags and References
===================
The document editor supports a set of keywords used for setting tags, and making references between
documents. The tag can be set once per section defined by a heading. Setting it multiple times
under the same heading will just override the previous setting. References can be set anywhere
within a section, and are collected according to their category.
documents.
Tags use the command ``@tag:`` to define a tag. The tag can be set once per section defined by a
heading. Setting it multiple times under the same heading will just override the previous setting.
``@tag: value``
A tag commad followed by the tag value, like for instance the name of a character.
References can be set anywhere within a section, and are collected according to their category.
References are on the form:
``@keyword: value``
A keyword argument followed by a value, or a comma separated list of values.
A reference keyword followed by a value, or a comma separated list of values.
The available tag and reference keywords are listed in the :ref:`a_struct_tags` section. They can
also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu.
The available reference keywords are listed in the :ref:`a_struct_tags` section. They can also be
inserted at the cursor position in the editor via the :guilabel:`Insert` menu.
.. _a_fmt_align:
@@ -255,3 +269,18 @@ documents. If you want such breaks for scenes and sections, you must add them ma
The page break code is applied to the text that follows it. It adds a "page break before" mark
to the text when exporting to HTML or Open Document. This means that a ``[NEW PAGE]`` which has
no text following it, it will not result in a page break.
**Example:**
.. code-block:: markdown
This is a text paragraph.
[VSPACE:2]
This is another text paragraph, but there will be two empty paragraphs
in-between them.
[NEWPAGE]
This text will always start on a new page if the build format has pages.
docs/source/usage_interface.rst
-277
View File
@@ -1,277 +0,0 @@
.. _a_ui:
******************
The User Interface
******************
.. _Compose Key: https://en.wikipedia.org/wiki/Compose_key
This sections covers in more detail what all the information on the user interface is for, and how
you can organise your project, and how you use the editor, viewer and outline panel.
.. _a_ui_tree:
The Project Tree
================
The main window contains a project tree in the left-most panel. It shows the entire structure of
the project, and has four columns:
**Column 1**
The first column shows the icon and label of each folder, document, or note in your project. The
label is not the same as the title you set inside the document. However, the document's label
will appear in the header above the document text itself so you know where in the project an
open document belongs. The icon is selected based on the type of item, and for novel documents,
the level of the first header in the document text.
**Column 2**
The second column shows the word count of the document, or the sum of words of the child items
for folders and documents with subdocuments. If the counts seem incorrect, they can be updated
by rebuilding the project index from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
**Column 3**
The third column indicates whether the document is considered active or inactive in the project.
You can use this flag to indicate that a document is still in the project, but should not be
considered an active part of it. When you run the :guilabel:`Build Novel Project` tool, you can
filter based on this flag. You can change this value from the context menu.
**Column 4**
The fourth column shows the user-defined status or importance labels you've assigned to each
project item. See :ref:`a_ui_tree_status` for more details. You can change these labels from the
context menu.
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.
At the top of the tree, you will find a set of buttons.
* The first button is a quick links button that will show you a dropdown menu of all the root
folders in your project. Selecting one will move to that position in the tree. You can also
activate this menu by pressing :kbd:`Ctrl`:kbd:`L`.
* The next two buttons can be used to move items up and down in the project tree. This is the only
way to move root folders.
* The next button opens a dropdown menu for adding new items to the tree. This includes root
folders. You can also activate this dropdown menu by pressing :kbd:`Ctrl`:kbd:`N`.
* The last button is a menu of further actions on the entire project tree.
.. tip::
Under the :guilabel:`Transform` submenu in the context menu of an item, you will find several
options on how to change a document or folder. This includes changing between document and note,
splitting them into multiple documents, or merging child items into a single document.
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
addition to the word count.
.. _a_ui_tree_novel:
The Novel Tree
--------------
An alternative way to view the project structure is the novel tree. You can switch to this view by
selecting the :guilabel:`Novel Tree View` button in the sidebar. This view is a simplified version
of the view in the :guilabel:`Outline`. It is convenient when you want to browse the structure of
the story itself rather than the document files.
.. note::
You cannot reorganise the entries in the novel tree, or add any new documents, as that would
imply restructuring the content of the document files. Any editing must be done in the project
tree. However, you can add new headings to existing documents, or change references, which will
be updated in this view.
.. _a_ui_tree_status:
Document Importance and Status
------------------------------
Each document or folder in your project can have either a "Status" or "Importance" flag set. These
are flags that you control and define yourself. The app doesn't do anything with them at all. To
modify the labels, go to their respective tabs in :guilabel:`Project Settings`.
The "Status" flag is intended to tag a Novel document as for instance a draft or as completed, and
the "Importance" flag is intended to tag character notes, or other notes, as for instance a main,
major or minor character.
Whether a document uses a "Status" or "Importance" flag depends on which root folder it lives in.
If it's in the :guilabel:`Novel` folder, it uses the "Status" flag, otherwise it uses an
"Importance" flag. Some folders, like :guilabel:`Trash` and :guilabel:`Archive` allow both.
.. _a_ui_tree_dnd:
Project Tree Drag & Drop
------------------------
The project tree allows drag & drop to a certain extent to allow you to reorder your documents and
folders. Moving a document in the project tree will affect the text's position when you assemble
your manuscript in the build tool.
Drag & drop has only limited support for moving documents. In general, bulk actions are not
allowed. This is deliberate to avoid accidentally messing up your project. If you make a mistake,
the last move action can be undone by pressing :kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`.
Documents and their folders can be rearranged freely within their root folders. If you move a Novel
documents out of a Novel folder, it will be converted to a project note. Notes can be moved freely
between all root folders, but keep in mind that if you move a note into a :guilabel:`Novel` root
folder, its "Importance" setting will be switched with a "Status" setting. See
:ref:`a_ui_tree_status`. The old value will not be overwritten though, and should be restored if
you move it back at some point.
Root folders in the project tree cannot be dragged & dropped at all. If you want to reorder them,
you can move them up or down with respect to eachother from the arrow buttons at the top of the
project tree, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` key.
.. _a_ui_edit:
Editing and Viewing Documents
=============================
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
Markdown-like syntax for some features, and a novelWriter-specific syntax for others. The syntax
format is described in the :ref:`a_fmt` section.
The editor has a maximise button (toggles the :guilabel:`Focus Mode`) and a close button in the
top–right corner. On the top–left side you will find an edit button that opens the
:guilabel:`Item Label` dialog for the currently open document, and a search button to open the
search dialog.
Any document in the project tree can also be viewed in parallel in a right hand side document
viewer. To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the
menu or context menu. If you have a middle mouse button, middle-clicking on the document will also
open it in the viewer.
The document viewed does not have to be the same document as currently being edited. However, If
you *are* viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the document
with your latest changes. You can also press the reload button in the top–right corner of the view
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
the edit or view panel. Optionally, the full project path to the document can be shown. This can be
set in :guilabel:`Preferences`.
.. tip::
Clicking on the document title bar will select the document in the project tree and reveal its
location, making it easier to locate in a large project.
Any tag reference in the editor can be opened in the viewer by moving the cursor to the label and
pressing :kbd:`Ctrl`:kbd:`Return`. You can also control-click them with your mouse. In the viewer,
the references become clickable links. Clicking them will replace the content of the viewer with
the content of the document the reference points to.
The document viewer keeps a history of viewed documents, which you can navigate with the arrow
buttons in the top–left corner of the viewer. If your mouse has backward and forward navigation
buttons, these can be used as well. They work just like the backward and forward features in a
browser.
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 the one
you're currently viewing, if any 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 through all documents in the list in the
:guilabel:`References` panel without losing the list in the process.
.. note::
The :guilabel:`References` panel relies on an up-to-date index of the project. The index is
maintained automatically. However, if anything is missing, or seems wrong, the index can always
be rebuilt by selecting :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu, or by
pressing :kbd:`F9`.
.. _a_ui_edit_search:
Search & Replace
----------------
The document editor has a search and replace tool that can be activated with :kbd:`Ctrl`:kbd:`F`
for search mode or :kbd:`Ctrl`:kbd:`H` for search and replace mode.
Pressing :kbd:`Return` while in the search box will search for the next occurrence of the word, and
:kbd:`Shift`:kbd:`Return` for the previous. Pressing :kbd:`Return` in the replace box, will replace
the highlighted text and move to the next result.
There are a number of settings for the search tool available as toggle switches above the search
box. They allow you to search for, in order: matched case only, whole word results only, search
using regular expressions, loop search when reaching the end of the document, and move to the next
document when reaching the end. There is also a switch that will try to match the case of the word
when the replacement is made. That is, it will try to keep the word upper, lower, or capitalised to
match the word being replaced.
The regular expression search is somewhat dependant on which version of Qt your system has. If you
have Qt 5.13 or higher, there is better support for unicode symbols in the search.
.. seealso::
For more information on the capabilities of the Regular Expression option, see the Qt
documentation for the `QRegularExpression <https://doc.qt.io/qt-5/qregularexpression.html>`_
class.
.. _a_ui_edit_auto:
Auto-Replace as You Type
========================
A few auto-replace features are supported by the editor. You can control every aspect of the
auto-replace feature from :guilabel:`Preferences`. You can also disable this feature entirely if
you wish.
.. tip::
If you don't like auto-replacement, all symbols inserted by this feature are also available in
the :guilabel:`Insert` menu, and via convenient :ref:`a_kb_ins`. You may also be using a
`Compose Key`_ setup, which means you may not need the auto-replace feature.
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
also try to determine whether to use the opening or closing symbol, although this feature isn't
always accurate. Especially distinguishing between closing single quote and apostrophe can be
tricky for languages that use the same symbol for these, like English does.
.. tip::
If the auto-replace feature changes a symbol when you did not want it to change, pressing
:kbd:`Ctrl`:kbd:`Z` immediately after the auto-replacement will undo it without undoing the
character you typed.
.. _a_ui_outline:
Project Outline View
====================
The project's Outline view is available as another view option from the views bar. 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 representing partitions, chapters, scenes and sections.
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
editor.
You can select which novel folder to display from the dropdown menu. You can optionally also choose
to show a combination of all novel folders.
.. note::
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 on how you
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.
A default set of such columns is visible, but you can turn on or off more columns from the menu
button in the toolbar. The order of the columns can also be rearranged by dragging them to a
different position. You column settings are saved between sessions on a per-project basis.
.. note::
The :guilabel:`Title` column cannot be disabled or moved.
The information viewed in the outline is based on the project's main index. While novelWriter does
its best to keep the index up to date when contents change, you can always rebuild it manually by
pressing :kbd:`F9` if something isn't right.
The outline view itself can be regenerated by pressing the refresh button. By default, the content
is refreshed each time you switch to this view.
The :guilabel:`Synopsis` column of the outline view takes its information from a specially
formatted comment. See :ref:`a_fmt_comm`.
docs/source/usage_project.rst
+177
View File
@@ -0,0 +1,177 @@
.. _a_ui_project:
*************
Project Views
*************
This sections covers in more detail the different project views available in novelWriter.
.. figure:: images/fig_project_tree_detailed.png
The Project Tree as it appears when loading a sample project.
.. _a_ui_tree:
The Project Tree
================
The main window contains a project tree in the left-most panel. It shows the entire structure of
the project, and has four columns.
**Column 1**
The first column shows the icon and label of each folder, document, or note in your project. The
label is not the same as the title you set inside the document. However, the document's label
will appear in the header above the document text itself so you know where in the project an
open document belongs. The icon is selected based on the type of item, and for novel documents,
the level of the first header in the document text.
**Column 2**
The second column shows the word count of the document, or the sum of words of the child items
for folders and documents with subdocuments. If the counts seem incorrect, they can be updated
by rebuilding the :term:`project index` from the :guilabel:`Tools` menu, or by pressing
:kbd:`F9`.
**Column 3**
The third column indicates whether the document is considered active or inactive in the project.
You can use this flag to indicate that a document is still in the project, but should not be
considered an active part of it. When you run the :guilabel:`Build Manuscript` tool, you can
include or exclude documents based on this flag. You can change this value from the
:term:`context menu`.
**Column 4**
The fourth column shows the user-defined status or importance labels you've assigned to each
project item. See :ref:`a_ui_tree_status` for more details on how to uses these labels. You can
change these labels from the :term:`context menu`.
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.
At the top of the tree, you will find a set of buttons.
* The first button is a quick links button that will show you a dropdown menu of all the
:term:`root folders<root folder>` in your project. Selecting one will move to that position in
the tree. You can also activate this menu by pressing :kbd:`Ctrl+L`.
* The next two buttons can be used to move items up and down in the project tree. This is the only
way to move root folders.
* The next button opens a dropdown menu for adding new items to the tree. This includes root
folders. You can also activate this dropdown menu by pressing :kbd:`Ctrl+N`.
* The last button is a menu of further actions you can apply to the project tree.
.. tip::
Under the :guilabel:`Transform` submenu in the context menu of an item, you will find several
options on how to change a document or folder. This includes changing between document and note,
splitting them into multiple documents, or merging child items into a single document.
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
addition to the word count.
.. _a_ui_tree_status:
Document Importance and Status
------------------------------
Each document or folder in your project can have either a "Status" or "Importance" flag set. These
are flags that you control and define yourself. novelWriter doesn't do anything with them at all.
To modify the labels, go to their respective tabs in :guilabel:`Project Settings`.
The "Status" flag is intended to tag a :term:`Novel document<novel documents>` as for instance a
draft or as completed, and the "Importance" flag is intended to tag character notes, or other
:term:`project notes`, as for instance a main, major or minor character.
Whether a document uses a "Status" or "Importance" flag depends on which :term:`root folder` it
lives in. If it's in a :guilabel:`Novel` folder, it uses the "Status" flag, otherwise it uses an
"Importance" flag. Some folders, like :guilabel:`Trash` and :guilabel:`Archive` allow both.
.. _a_ui_tree_dnd:
Project Tree Drag & Drop
------------------------
The project tree allows drag & drop to a certain extent to allow you to reorder your documents and
folders. Moving a document in the project tree will affect the text's position when you assemble
your manuscript in the :guilabel:`Manuscript Build` tool.
Drag & drop has only limited support for moving documents. In general, bulk actions are not
allowed. This is deliberate to avoid accidentally messing up your project. If you make a mistake,
the last move action can be undone by pressing :kbd:`Ctrl+Shift+Z`.
Documents and their folders can be rearranged freely within their root folders. If you move a Novel
documents out of a Novel folder, it will be converted to a project note. Notes can be moved freely
between all root folders, but keep in mind that if you move a note into a :guilabel:`Novel` root
folder, its "Importance" setting will be switched with a "Status" setting. See
:ref:`a_ui_tree_status`. The old value will not be overwritten though, and should be restored if
you move it back at some point.
Root folders in the project tree cannot be dragged & dropped at all. If you want to reorder them,
you can move them up or down with respect to eachother from the arrow buttons at the top of the
project tree, or by pressing :kbd:`Ctrl+Shift+Up` or :kbd:`Ctrl+Shift+Down` when they are selected.
.. _a_ui_tree_novel:
The Novel Tree
==============
.. figure:: images/fig_novel_tree_view.png
A screenshot of the Novel Tree View.
An alternative way to view the project structure is the novel tree. You can switch to this view by
selecting the :guilabel:`Novel Tree View` button in the sidebar. This view is a simplified version
of the view in the :guilabel:`Outline View`. It is convenient when you want to browse the structure
of the story itself rather than the document files.
.. note::
You cannot reorganise the entries in the novel tree, or add any new documents, as that would
imply restructuring the content of the document files themselves. Any such editing must be done
in the project tree. However, you can add new headings to existing documents, or change
references, which will be updated in this view.
.. _a_ui_outline:
Project Outline View
====================
.. figure:: images/fig_outline_view.png
A screenshot of the Novel Outline View.
The project's :guilabel:`Outline View` is available as another view option from the sidebar. 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 representing partitions, chapters, scenes and
sections.
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
editor.
You can select which novel folder to display from the dropdown menu. You can optionally also choose
to show a combination of all novel folders.
.. note::
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 on how you
choose to organise your documents. See the :ref:`a_struct` page for more details.
Various meta data and information extracted from :term:`tags<tag>` can be displayed in columns in
the outline. A default set of such columns is visible, but you can turn on or off more columns from
the menu button in the toolbar. The order of the columns can also be rearranged by dragging them to
a different position. You column settings are saved between sessions on a per-project basis.
.. note::
The :guilabel:`Title` column cannot be disabled or moved.
The information viewed in the outline is based on the :term:`project index`. While novelWriter does
its best to keep the index up to date when contents change, you can always rebuild it manually by
pressing :kbd:`F9` if something isn't right.
The outline view itself can be regenerated by pressing the refresh button. By default, the content
is refreshed each time you switch to this view.
The :guilabel:`Synopsis` column of the outline view takes its information from a specially
formatted comment. See :ref:`a_fmt_comm`.
docs/source/usage_projectformat.rst
+1 -1
View File
@@ -8,7 +8,7 @@ Project Format Changes
.. _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
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 below, as well as the user actions required, where
docs/source/usage_shortcuts.rst
+114 -114
View File
@@ -19,24 +19,24 @@ Main Window Shortcuts
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F1`", "Open the online user manual"
":kbd:`F5`", "Open the :guilabel:`Build Manuscript` tool"
":kbd:`F6`", "Open the :guilabel:`Writing Statistics` tool"
":kbd:`F8`", "Toggle :guilabel:`Focus Mode`"
":kbd:`F9`", "Re-build the project index"
":kbd:`F11`", "Toggle full screen mode"
":kbd:`Alt`:kbd:`1`", "Switch focus to the project tree (Windows :kbd:`Ctrl`:kbd:`Alt`:kbd:`1`)"
":kbd:`Alt`:kbd:`2`", "Switch focus to document editor (Windows :kbd:`Ctrl`:kbd:`Alt`:kbd:`2`)"
":kbd:`Alt`:kbd:`3`", "Switch focus to document viewer (Windows :kbd:`Ctrl`:kbd:`Alt`:kbd:`3`)"
":kbd:`Alt`:kbd:`4`", "Switch focus to outline view (Windows :kbd:`Ctrl`:kbd:`Alt`:kbd:`4`)"
":kbd:`Ctrl`:kbd:`,`", "Open the :guilabel:`Preferences` dialog"
":kbd:`Ctrl`:kbd:`Q`", "Exit novelWriter"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`,`", "Open the :guilabel:`Project Settings` dialog"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`O`", "Open a project"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`S`", "Save the current project"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`W`", "Close the current project"
":kbd:`Shift`:kbd:`F1`", "Open the local user manual (PDF) if it is available"
":kbd:`Shift`:kbd:`F6`", "Open the :guilabel:`Project Details` dialog"
":kbd:`F1`", "Open the online user manual"
":kbd:`F5`", "Open the :guilabel:`Build Manuscript` tool"
":kbd:`F6`", "Open the :guilabel:`Writing Statistics` tool"
":kbd:`F8`", "Toggle :guilabel:`Focus Mode`"
":kbd:`F9`", "Re-build the project index"
":kbd:`F11`", "Toggle full screen mode"
":kbd:`Alt+1`", "Switch focus to the project tree (Windows :kbd:`Ctrl+Alt+1`)"
":kbd:`Alt+2`", "Switch focus to document editor (Windows :kbd:`Ctrl+Alt+2`)"
":kbd:`Alt+3`", "Switch focus to document viewer (Windows :kbd:`Ctrl+Alt+3`)"
":kbd:`Alt+4`", "Switch focus to outline view (Windows :kbd:`Ctrl+Alt+4`)"
":kbd:`Ctrl+,`", "Open the :guilabel:`Preferences` dialog"
":kbd:`Ctrl+Q`", "Exit novelWriter"
":kbd:`Ctrl+Shift+,`", "Open the :guilabel:`Project Settings` dialog"
":kbd:`Ctrl+Shift+O`", "Open a project"
":kbd:`Ctrl+Shift+S`", "Save the current project"
":kbd:`Ctrl+Shift+W`", "Close the current project"
":kbd:`Shift+F1`", "Open the local user manual (PDF) if it is available"
":kbd:`Shift+F6`", "Open the :guilabel:`Project Details` dialog"
.. _a_kb_tree:
@@ -46,21 +46,21 @@ Project Tree Shortcuts
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F2`", "Edit the label of the selected item"
":kbd:`Return`", "Open the selected document in the editor"
":kbd:`Alt`:kbd:`Up`", "Jump or go to the previous item at same level in the tree"
":kbd:`Alt`:kbd:`Down`", "Jump or go to the next item at same level in the tree"
":kbd:`Alt`:kbd:`Left`", "Jump to the parent item in the tree"
":kbd:`Alt`:kbd:`Right`", "Jump to the first child item in the project tree"
":kbd:`Ctrl`:kbd:`.`", "Open the context menu on the selected item"
":kbd:`Ctrl`:kbd:`L`", "Open the :guilabel:`Quick Links` menu"
":kbd:`Ctrl`:kbd:`N`", "Open the :guilabel:`Create New Item` menu"
":kbd:`Ctrl`:kbd:`O`", "Open selected document"
":kbd:`Ctrl`:kbd:`R`", "Open the selected document in the viewer"
":kbd:`Ctrl`:kbd:`Up`", "Move selected item one step up in the tree"
":kbd:`Ctrl`:kbd:`Down`", "Move selected item one step down in the tree"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`", "Undo the last move of a project item, if possible"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`", "Move the selected item to Trash"
":kbd:`F2`", "Edit the label of the selected item"
":kbd:`Return`", "Open the selected document in the editor"
":kbd:`Alt+Up`", "Jump or go to the previous item at same level in the tree"
":kbd:`Alt+Down`", "Jump or go to the next item at same level in the tree"
":kbd:`Alt+Left`", "Jump to the parent item in the tree"
":kbd:`Alt+Right`", "Jump to the first child item in the project tree"
":kbd:`Ctrl+.`", "Open the context menu on the selected item"
":kbd:`Ctrl+L`", "Open the :guilabel:`Quick Links` menu"
":kbd:`Ctrl+N`", "Open the :guilabel:`Create New Item` menu"
":kbd:`Ctrl+O`", "Open selected document"
":kbd:`Ctrl+R`", "Open the selected document in the viewer"
":kbd:`Ctrl+Up`", "Move selected item one step up in the tree"
":kbd:`Ctrl+Down`", "Move selected item one step down in the tree"
":kbd:`Ctrl+Shift+Z`", "Undo the last move of a project item, if possible"
":kbd:`Ctrl+Shift+Del`", "Move the selected item to Trash"
.. _a_kb_editor:
@@ -75,13 +75,13 @@ Text Search Shortcuts
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F3`", "Find the next occurrence of the search word"
":kbd:`Ctrl`:kbd:`F`", "Open the search bar and search for the selected word, if any is selected"
":kbd:`Ctrl`:kbd:`G`", "Find next occurrence of search word in current document"
":kbd:`Ctrl`:kbd:`H`", "Open the search tool and populate with the selected word (Mac :kbd:`Cmd`:kbd:`=`)"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`1`", "Replace selected occurrence of the search word, and move to the next"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`G`", "Find previous occurrence of the search word"
":kbd:`Shift`:kbd:`F3`", "Find the previous occurrence of the search word"
":kbd:`F3`", "Find the next occurrence of the search word"
":kbd:`Ctrl+F`", "Open the search bar and search for the selected word, if any is selected"
":kbd:`Ctrl+G`", "Find next occurrence of search word in current document"
":kbd:`Ctrl+H`", "Open the search tool and populate with the selected word (Mac :kbd:`Cmd+=`)"
":kbd:`Ctrl+Shift+1`", "Replace selected occurrence of the search word, and move to the next"
":kbd:`Ctrl+Shift+G`", "Find previous occurrence of the search word"
":kbd:`Shift+F3`", "Find the previous occurrence of the search word"
Text Formatting Shortcuts
@@ -90,23 +90,23 @@ Text Formatting Shortcuts
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`Ctrl`:kbd:`/`", "Toggle block format as comment"
":kbd:`Ctrl`:kbd:`0`", "Remove block formatting for block under cursor"
":kbd:`Ctrl`:kbd:`1`", "Change block format to header level 1"
":kbd:`Ctrl`:kbd:`2`", "Change block format to header level 2"
":kbd:`Ctrl`:kbd:`3`", "Change block format to header level 3"
":kbd:`Ctrl`:kbd:`4`", "Change block format to header level 4"
":kbd:`Ctrl`:kbd:`5`", "Change block alignment to left-aligned"
":kbd:`Ctrl`:kbd:`6`", "Change block alignment to centred"
":kbd:`Ctrl`:kbd:`7`", "Change block alignment to right-aligned"
":kbd:`Ctrl`:kbd:`8`", "Add a left margin to the block"
":kbd:`Ctrl`:kbd:`9`", "Add a right margin to the block"
":kbd:`Ctrl`:kbd:`B`", "Format selected text, or word under cursor, with strong emphasis (bold)"
":kbd:`Ctrl`:kbd:`D`", "Strikethrough selected text, or word under cursor"
":kbd:`Ctrl`:kbd:`I`", "Format selected text, or word under cursor, with emphasis (italic)"
":kbd:`Ctrl`:kbd:`'`", "Wrap selected text, or word under cursor, in single quotes"
":kbd:`Ctrl`:kbd:`""`", "Wrap selected text, or word under cursor, in double quotes"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`/`", "Remove block formatting for block under cursor"
":kbd:`Ctrl+/`", "Toggle block format as comment"
":kbd:`Ctrl+0`", "Remove block formatting for block under cursor"
":kbd:`Ctrl+1`", "Change block format to header level 1"
":kbd:`Ctrl+2`", "Change block format to header level 2"
":kbd:`Ctrl+3`", "Change block format to header level 3"
":kbd:`Ctrl+4`", "Change block format to header level 4"
":kbd:`Ctrl+5`", "Change block alignment to left-aligned"
":kbd:`Ctrl+6`", "Change block alignment to centred"
":kbd:`Ctrl+7`", "Change block alignment to right-aligned"
":kbd:`Ctrl+8`", "Add a left margin to the block"
":kbd:`Ctrl+9`", "Add a right margin to the block"
":kbd:`Ctrl+B`", "Format selected text, or word under cursor, with strong emphasis (bold)"
":kbd:`Ctrl+D`", "Strikethrough selected text, or word under cursor"
":kbd:`Ctrl+I`", "Format selected text, or word under cursor, with emphasis (italic)"
":kbd:`Ctrl+'`", "Wrap selected text, or word under cursor, in single quotes"
":kbd:`Ctrl+""`", "Wrap selected text, or word under cursor, in double quotes"
":kbd:`Ctrl+Shift+/`", "Remove block formatting for block under cursor"
Other Editor Shortcuts
@@ -115,24 +115,24 @@ Other Editor Shortcuts
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F7`", "Re-run the spell checker"
":kbd:`Ctrl`:kbd:`.`", "Open the context menu at the current cursor location"
":kbd:`Ctrl`:kbd:`A`", "Select all text in the document"
":kbd:`Ctrl`:kbd:`C`", "Copy selected text to clipboard"
":kbd:`Ctrl`:kbd:`K`", "Activate the insert commands (see list in :ref:`a_kb_ins`)"
":kbd:`Ctrl`:kbd:`R`", "Open or reload the current document in the viewer"
":kbd:`Ctrl`:kbd:`S`", "Save the current document"
":kbd:`Ctrl`:kbd:`V`", "Paste text from clipboard to cursor position"
":kbd:`Ctrl`:kbd:`W`", "Close the current document"
":kbd:`Ctrl`:kbd:`X`", "Cut selected text to clipboard"
":kbd:`Ctrl`:kbd:`Y`", "Redo latest undo"
":kbd:`Ctrl`:kbd:`Z`", "Undo latest changes"
":kbd:`Ctrl`:kbd:`Del`", "Delete the word after the cursor"
":kbd:`Ctrl`:kbd:`Backspace`", "Delete the word before the cursor"
":kbd:`Ctrl`:kbd:`Return`", "Open the tag or reference under the cursor in the viewer"
":kbd:`Ctrl`:kbd:`F7`", "Toggle spell checking"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`A`", "Select all text in the current paragraph"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`I`", "Import text to the current document from a text file"
":kbd:`F7`", "Re-run the spell checker"
":kbd:`Ctrl+.`", "Open the context menu at the current cursor location"
":kbd:`Ctrl+A`", "Select all text in the document"
":kbd:`Ctrl+C`", "Copy selected text to clipboard"
":kbd:`Ctrl+K`", "Activate the insert commands (see list in :ref:`a_kb_ins`)"
":kbd:`Ctrl+R`", "Open or reload the current document in the viewer"
":kbd:`Ctrl+S`", "Save the current document"
":kbd:`Ctrl+V`", "Paste text from clipboard to cursor position"
":kbd:`Ctrl+W`", "Close the current document"
":kbd:`Ctrl+X`", "Cut selected text to clipboard"
":kbd:`Ctrl+Y`", "Redo latest undo"
":kbd:`Ctrl+Z`", "Undo latest changes"
":kbd:`Ctrl+Del`", "Delete the word after the cursor"
":kbd:`Ctrl+Backspace`", "Delete the word before the cursor"
":kbd:`Ctrl+Return`", "Open the tag or reference under the cursor in the viewer"
":kbd:`Ctrl+F7`", "Toggle spell checking"
":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph"
":kbd:`Ctrl+Shift+I`", "Import text to the current document from a text file"
.. _a_kb_ins:
@@ -140,45 +140,45 @@ Insert Shortcuts
----------------
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+K`, followed by
a key or key combination for the inserted content.
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`Ctrl`:kbd:`K`, :kbd:`−`", "Insert a short dash (en dash)"
":kbd:`Ctrl`:kbd:`K`, :kbd:`_`", "Insert a long dash (em dash)"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`_`", "Insert a horizontal bar (quotation dash)"
":kbd:`Ctrl`:kbd:`K`, :kbd:`~`", "Insert a figure dash (same width as a number)"
":kbd:`Ctrl`:kbd:`K`, :kbd:`1`", "Insert a left single quote"
":kbd:`Ctrl`:kbd:`K`, :kbd:`2`", "Insert a right single quote"
":kbd:`Ctrl`:kbd:`K`, :kbd:`3`", "Insert a left double quote"
":kbd:`Ctrl`:kbd:`K`, :kbd:`4`", "Insert a right double quote"
":kbd:`Ctrl`:kbd:`K`, :kbd:`'`", "Insert a modifier apostrophe"
":kbd:`Ctrl`:kbd:`K`, :kbd:`.`", "Insert an ellipsis"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`'`", "Insert a prime"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`""`", "Insert a double prime"
":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:`Ctrl`:kbd:`Space`", "Insert a thin non-breaking space"
":kbd:`Ctrl`:kbd:`K`, :kbd:`*`", "Insert a list bullet"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`−`", "Insert a hyphen bullet (alternative bullet)"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`*`", "Insert a flower mark (alternative bullet)"
":kbd:`Ctrl`:kbd:`K`, :kbd:`%`", "Insert a per mille symbol"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`O`", "Insert a degree symbol"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`X`", "Insert a times sign"
":kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`D`", "Insert a division sign"
":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:`F`", "Insert a ``@focus`` 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:`S`", "Insert a synopsis comment"
":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:`O`", "Insert an ``@object`` keyword"
":kbd:`Ctrl`:kbd:`K`, :kbd:`E`", "Insert an ``@entity`` keyword"
":kbd:`Ctrl`:kbd:`K`, :kbd:`X`", "Insert a ``@custom`` keyword"
":kbd:`Ctrl+K`, :kbd:`−`", "Insert a short dash (en dash)"
":kbd:`Ctrl+K`, :kbd:`_`", "Insert a long dash (em dash)"
":kbd:`Ctrl+K`, :kbd:`Ctrl+_`", "Insert a horizontal bar (quotation dash)"
":kbd:`Ctrl+K`, :kbd:`~`", "Insert a figure dash (same width as a number)"
":kbd:`Ctrl+K`, :kbd:`1`", "Insert a left single quote"
":kbd:`Ctrl+K`, :kbd:`2`", "Insert a right single quote"
":kbd:`Ctrl+K`, :kbd:`3`", "Insert a left double quote"
":kbd:`Ctrl+K`, :kbd:`4`", "Insert a right double quote"
":kbd:`Ctrl+K`, :kbd:`'`", "Insert a modifier apostrophe"
":kbd:`Ctrl+K`, :kbd:`.`", "Insert an ellipsis"
":kbd:`Ctrl+K`, :kbd:`Ctrl+'`", "Insert a prime"
":kbd:`Ctrl+K`, :kbd:`Ctrl+""`", "Insert a double prime"
":kbd:`Ctrl+K`, :kbd:`Space`", "Insert a non-breaking space"
":kbd:`Ctrl+K`, :kbd:`Shift+Space`", "Insert a thin space"
":kbd:`Ctrl+K`, :kbd:`Ctrl+Space`", "Insert a thin non-breaking space"
":kbd:`Ctrl+K`, :kbd:`*`", "Insert a list bullet"
":kbd:`Ctrl+K`, :kbd:`Ctrl+−`", "Insert a hyphen bullet (alternative bullet)"
":kbd:`Ctrl+K`, :kbd:`Ctrl+*`", "Insert a flower mark (alternative bullet)"
":kbd:`Ctrl+K`, :kbd:`%`", "Insert a per mille symbol"
":kbd:`Ctrl+K`, :kbd:`Ctrl+O`", "Insert a degree symbol"
":kbd:`Ctrl+K`, :kbd:`Ctrl+X`", "Insert a times sign"
":kbd:`Ctrl+K`, :kbd:`Ctrl+D`", "Insert a division sign"
":kbd:`Ctrl+K`, :kbd:`G`", "Insert a ``@tag`` keyword"
":kbd:`Ctrl+K`, :kbd:`V`", "Insert a ``@pov`` keyword"
":kbd:`Ctrl+K`, :kbd:`F`", "Insert a ``@focus`` keyword"
":kbd:`Ctrl+K`, :kbd:`C`", "Insert a ``@char`` keyword"
":kbd:`Ctrl+K`, :kbd:`P`", "Insert a ``@plot`` keyword"
":kbd:`Ctrl+K`, :kbd:`S`", "Insert a synopsis comment"
":kbd:`Ctrl+K`, :kbd:`T`", "Insert a ``@time`` keyword"
":kbd:`Ctrl+K`, :kbd:`L`", "Insert a ``@location`` keyword"
":kbd:`Ctrl+K`, :kbd:`O`", "Insert an ``@object`` keyword"
":kbd:`Ctrl+K`, :kbd:`E`", "Insert an ``@entity`` keyword"
":kbd:`Ctrl+K`, :kbd:`X`", "Insert a ``@custom`` keyword"
.. _a_kb_viewer:
@@ -189,8 +189,8 @@ Document Viewer Shortcuts
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`Alt`:kbd:`Left`", "Move backward in the view history"
":kbd:`Alt`:kbd:`Right`", "Move forward in the view history"
":kbd:`Ctrl`:kbd:`C`", "Copy selected text to clipboard"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`A`", "Select all text in the current paragraph"
":kbd:`Ctrl`:kbd:`Shift`:kbd:`R`", "Close the document viewer"
":kbd:`Alt+Left`", "Move backward in the view history"
":kbd:`Alt+Right`", "Move forward in the view history"
":kbd:`Ctrl+C`", "Copy selected text to clipboard"
":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph"
":kbd:`Ctrl+Shift+R`", "Close the document viewer"
docs/source/usage_typography.rst
+3 -3
View File
@@ -30,8 +30,8 @@ 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`:kbd:`Z`, reverting the text to what you typed
before the automatic replacement occurred.
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
@@ -79,7 +79,7 @@ right single quotation marks, depending on the font. There is a Wikipedia articl
`Modifier letter apostrophe`_ with more details.
.. note::
On export with the :guilabel:`Build Novel Project` tool, these apostrophes will be replaced
On export with the :guilabel:`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 highlighting.
docs/source/usage_writing.rst
+139
View File
@@ -0,0 +1,139 @@
.. _a_ui_writing:
*********************
The Editor and Viewer
*********************
.. _Compose Key: https://en.wikipedia.org/wiki/Compose_key
This sections covers in more detail how the document editor and viewer panels work.
.. _a_ui_edit:
Editing a Document
==================
.. figure:: images/fig_editor.png
A screenshot of the Document Editor panel.
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
Markdown-like syntax for some features, and a novelWriter-specific syntax for others. The syntax
format is described in the :ref:`a_fmt` section.
The editor has a maximise button (toggles the :guilabel:`Focus Mode`) and a close button in the
top--right corner. On the top--left side you will find an edit button that opens the
:guilabel:`Item Label` dialog for the currently open document, and a search button to open the
search dialog.
Both the document editor and viewer will show the label of the currently open 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 set in :guilabel:`Preferences`.
.. tip::
Clicking on the document title bar will select the document in the project tree and reveal its
location, making it easier to locate in a large project.
Any :term:`references<reference>` in the editor can be opened in the viewer by moving the cursor to
the label and pressing :kbd:`Ctrl+Return`. You can also control-click them with your mouse.
.. _a_ui_view:
Viewing a Document
==================
.. figure:: images/fig_viewer.png
A screenshot of the Document Viewer panel.
Any document in the project tree can also be viewed in parallel in a right hand side document
viewer. To view a document, press :kbd:`Ctrl+R`, or select :guilabel:`View Document` in the menu or
context menu. If you have a middle mouse button, middle-clicking on the document will also open it
in the viewer.
The document viewed does not have to be the same document as currently being edited. However, If
you *are* viewing the same document, pressing :kbd:`Ctrl+R` again will update the document with
your latest changes. You can also press the reload button in the top--right corner of the view
panel, next to the close button, to achieve the same thing.
In the viewer :term:`references<reference>` become clickable links. Clicking them will replace the
content of the viewer with the content of the document the reference points to.
The document viewer keeps a history of viewed documents, which you can navigate with the arrow
buttons in the top--left corner of the viewer. If your mouse has backward and forward navigation
buttons, these can be used as well. They work just like the backward and forward features in a
browser.
At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click
the icon next to it to reveal it.) This panel will show links to all documents referring back to
the one you're currently viewing, if any 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 through all documents in the list in the
:guilabel:`References` panel without losing the list in the process.
.. note::
The :guilabel:`References` panel relies on an up-to-date index of the project. The index is
maintained automatically. However, if anything is missing, or seems wrong, the index can always
be rebuilt by selecting :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu, or by
pressing :kbd:`F9`.
.. _a_ui_edit_search:
Search & Replace
================
.. figure:: images/fig_editor_search.png
A screenshot of the Document Editor search box.
The document editor has a search and replace tool that can be activated with :kbd:`Ctrl+F` for
search mode or :kbd:`Ctrl+H` for search and replace mode.
Pressing :kbd:`Return` while in the search box will search for the next occurrence of the word, and
:kbd:`Shift+Return` for the previous. Pressing :kbd:`Return` in the replace box, will replace the
highlighted text and move to the next result.
There are a number of settings for the search tool available as toggle switches above the search
box. They allow you to search for, in order: matched case only, whole word results only, search
using regular expressions, loop search when reaching the end of the document, and move to the next
document when reaching the end. There is also a switch that will try to match the case of the word
when the replacement is made. That is, it will try to keep the word upper, lower, or capitalised to
match the word being replaced.
The regular expression search is somewhat dependant on which version of Qt your system has. If you
have Qt 5.13 or higher, there is better support for Unicode symbols in the search.
.. seealso::
For more information on the capabilities of the Regular Expression option, see the Qt
documentation for the `QRegularExpression <https://doc.qt.io/qt-5/qregularexpression.html>`_
class.
.. _a_ui_edit_auto:
Auto-Replace as You Type
========================
A few auto-replace features are supported by the editor. You can control every aspect of the
auto-replace feature from :guilabel:`Preferences`. You can also disable this feature entirely if
you wish.
.. tip::
If you don't like auto-replacement, all symbols inserted by this feature are also available in
the :guilabel:`Insert` menu, and via convenient :ref:`a_kb_ins`. You may also be using a
`Compose Key`_ setup, which means you may not need the auto-replace feature.
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
also try to determine whether to use the opening or closing symbol, although this feature isn't
always accurate. Especially distinguishing between closing single quote and apostrophe can be
tricky for languages that use the same symbol for these, like English does.
.. tip::
If the auto-replace feature changes a symbol when you did not want it to change, pressing
:kbd:`Ctrl+Z` immediately after the auto-replacement will undo it without undoing the character
you typed.