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

Updated the introduction section of the docs

Browse Source
This commit is contained in:
Veronica K. B. Olsen
2021-01-01 18:37:11 +01:00
parent 176c25004c
commit 92f44f0aaa
5 changed files with 191 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/int_interface.rst
+64 -61
View File
@@ -4,21 +4,22 @@
User Interface
**************
The user interface is kept as simple as possible to avoid distractions when writing. This page lists
all the main GUI elements, and explains what they do.
The user interface is kept as simple as possible to avoid distractions when writing. This page
lists all the main GUI elements, and explains what they do.
.. _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. It has four columns:
The main window contains a project tree in the left-most panel. It shows the entire structure of
the project. It has four columns:
:guilabel:`Label`
The first column shows the item icon and its label. The labels can be edited from the menu, or by
pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the same as the title you set inside
the document, but it will appear in the header above the document text itself.
The first column shows the item icon and its label. The labels can be edited from the menu
:guilabel:`Project` menu, or by pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the
same as the title you set inside the document, but it will appear in the header above the
document text itself.
:guilabel:`Words`
The second column shows the word count of the file, or the sum of words in the child items if it
@@ -27,42 +28,46 @@ project. It has four columns:
:guilabel:`Inc`
The third column indicates whether the file is included in the final project build or not. You
may want to filter out files that you no longer want to keep in the final manuscript, but want to
keep in the project for reference.
may want to filter out files that you no longer want to keep in the final manuscript, but want
to keep in the project for reference.
:guilabel:`Flags`
The fourth column shows various meta data flags for the item. The first is an icon indicating the
importance or status of the file. These are colour coded status levels that you control 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, that is ``N`` for
**Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`. The second character indicates
the file layout type (see :ref:`a_proj_roots`).
The fourth column shows various meta data flags for the item. The first is an icon indicating
the importance or status of the file. These are colour coded status levels that you control 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,
that is ``N`` for **Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`). The second
character indicates the file layout type (see :ref:`a_proj_roots`).
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.
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:
Project Tree Drag and Drop
--------------------------
The project tree allows dragging and drop to a certain extent. This feature is primarily intended
for rearranging the order of your files within each root folder, and has only limited support for
The project tree allows drag and drop to a certain extent. This feature is primarily intended for
rearranging the order of your files within each root folder, and has only limited support for
moving files elsewhere in the project tree. In general, bulk actions are not allowed. This is
deliberate to avoid accidentally messing up your project. The project tree has no undo function.
Document files and their folders can be rearranged freely within their root folders. Novel files
cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the
:guilabel:`Outtakes` folder. Note files can be moved freely anywhere.
:guilabel:`Outtakes` folder. Note files can be moved freely between root folders.
Folders cannot be moved at all outside their root tree. Neither can a folder containing files be
deleted. You must first delete the files.
Root folders in the project tree cannot be dragged and dropped at all. However, if you want to
reorder them, you can move them up or down with respect to eachother from the :guilabel:`Tools`
menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` key.
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
right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down`
key.
.. _a_ui_edit:
@@ -75,11 +80,12 @@ having it selected. This will open the file in the document editor. The editor u
markdown format. The format is described in the :ref:`a_ui_md` section below. The editor has a
maximise button (activates :guilabel:`Focus Mode`) and a close button in the top-right corner.
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. The
document viewed does not have to be the same document 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 little reload button in the top-right corner of the view
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. 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 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
@@ -91,11 +97,13 @@ location of the file in a large project.
Any reference to a tag in the editor can be opened in the viewer by moving the cursor to the label
and pressing :kbd:`Ctrl`:kbd:`Return`. 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.
points to. The document viewer keeps a history of viewed documents that you can navigate with the
arrow buttons in the top-left corner of the viewer. If your mouse has 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 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
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
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.
@@ -187,13 +195,11 @@ A minimal set of text emphasis styles are supported.
Strikethrough text.
In markdown guides it is often recommended to differentiate between strong importance and emphasis
by using ``**`` for strong and ``_`` for emphasis, although markdown generally supports also ``__``
by using ``**`` for strong and ``_`` for emphasis, although markdown generally also supports ``__``
for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and
conversion significantly simpler and faster, in novelWriter this is a rule, not just a
recommendation. The following is therefore the only supported formatting syntax:
There are also some additional rules:
1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag
itself. That is, ``**text**`` is valid, ``**text **`` is not.
2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in
@@ -201,6 +207,8 @@ There are also some additional rules:
3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper.
This is due to the underscore also being a valid word character, so if they are on the outside,
they violate rule 2.
4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or
paragraphs, you must apply it to each of them in turn.
.. _a_ui_md_comm:
@@ -211,17 +219,23 @@ Comments and Synopsis
In addition to these standard markdown features, novelWriter also allows for comments in the text
files. The text of the comment is ignored by the word counter and not exported or, optionally,
hidden when viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon),
the comment is treated specially, and will show up in the :ref:`a_ui_outline` in a dedicated column.
the comment 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 indicate this by altering the colour of the word.
``% text...``
A comment. The text is not exported by default (this can be overridden), seen in the Viewer, or
counted towards word counts.
``% Synopsis: text...``
A synopsis comment. It is generally treated in the same way as regular comments, except that it
is captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It can also be
filtered separately when exporting the project to for instance generate an outline document of
the whole project.
A synopsis comment. It is generally treated in the same way as a regular comment, except that it
is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It can also
be filtered separately when exporting the project to for instance generate an outline document
of the whole project.
.. note::
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.
.. _a_ui_md_tags:
@@ -236,7 +250,8 @@ multiple times under the same heading will just override the previous setting.
``@keyword: value``
A keyword argument 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.
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.
.. _a_ui_md_add:
@@ -248,10 +263,11 @@ The editor and viewer also supports markdown standard hard line breaks, and pres
spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when
the file 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. Alternatively,
the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to insert this.
* A hard line break is achieved by leaving two or more spaces at the end of the line.
Alternatively, the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to insert this.
* A non-breaking space is 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`.
* 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`.
These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed
@@ -276,7 +292,7 @@ editor.
.. note::
Since the internal structure of the novel does not depend on the file structure of the project
tree, these will not necessarily look the same, depending how you chose to organise your files.
tree, these will not necessarily look the same, depending how you choose to organise your files.
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.
@@ -296,21 +312,8 @@ updating in the :guilabel:`Tools` menu, which will trigger an update whenever th
and the :guilabel:`Outline` tab is active. You may want to disable this feature if your project is
very large,
.. _a_ui_outline_synopsis:
Synopsis Column
---------------
The :guilabel:`Synopsis` column of the outline view takes its information from a specially formatted
comment. See :ref:`a_ui_md_comm`. In order to flag a comment as a synopsis, add the word
``Synopsis:`` as the first word of the comment. The ``:`` is required, and 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.
.. note::
Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are
flagged as a synopsis comment, the last one will be used.
The :guilabel:`Synopsis` column of the outline view takes its information from a specially
formatted comment. See :ref:`a_ui_md_comm`.
.. _a_ui_shortcuts:
@@ -401,9 +404,9 @@ Most features are available as keyboard shortcuts. These are as follows:
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-K`, followed by a key or
combination for the inserted character or punctuation.
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-K`, followed by a key
or combination for the inserted character or punctuation.
.. csv-table:: Keyboard Shortcuts
:header: "Shortcut", "Description"