Made another pass of editing of the entire documentation
This commit is contained in:
Veronica K. B. Olsen
+82
-44
@@ -4,7 +4,8 @@
|
||||
User Interface
|
||||
***************
|
||||
|
||||
The user interface is kept as simple as possible to avoid distractions when writing.
|
||||
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:
|
||||
|
||||
@@ -16,12 +17,13 @@ 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`.
|
||||
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
|
||||
is a folder. If the counts seem incorrect, they can be updated by rebuilding the project index
|
||||
from the menu, or by pressing :kbd:`F9`.
|
||||
from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
|
||||
|
||||
:guilabel:`Inc`
|
||||
The third column indicates whether the file is included in the final project build or not. You
|
||||
@@ -31,13 +33,14 @@ project. It has four columns:
|
||||
: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. They can be changed in Project Settings. 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`).
|
||||
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 is a small details panel showing the full information of the currently
|
||||
selected item. This panel also includes the latest paragraph and character counts.
|
||||
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_edit:
|
||||
@@ -46,16 +49,16 @@ Editing and Viewing Documents
|
||||
=============================
|
||||
|
||||
To edit a document, double-click the file 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 simplified
|
||||
having it selected. This will open the file in the document editor. The editor uses a simplified
|
||||
markdown format. The format is described in the :ref:`a_ui_md` section below. The editor 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. If you *are* viewing
|
||||
the same document though, pressing :kbd:`Ctrl`:kbd:`R` again will update the document with your
|
||||
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
|
||||
panel next to the close button.
|
||||
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 file can be shown. This can be set
|
||||
@@ -68,15 +71,38 @@ and pressing :kbd:`Ctrl`:kbd:`Return`. In the viewer, the references become clic
|
||||
Clicking them will replace the content of the viewer with the content of the document the reference
|
||||
points to.
|
||||
|
||||
At the bottom of the viewer's panel there is a :guilabel:`References` panel (click the icon if it is
|
||||
hidden) that will show links to all documents referring back to it. 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.
|
||||
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.
|
||||
|
||||
.. note::
|
||||
The :guilabel:`References` panel relies on an up-to-date index of the project. If anything is
|
||||
missing, or seems wrong, the index can always be rebuilt from :guilabel:`Tools` >
|
||||
:guilabel:`Rebuild Index` or by pressing :kbd:`F9`.
|
||||
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_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`.
|
||||
|
||||
.. 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_ui_shortcuts_ins`.
|
||||
|
||||
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, but this feature isn't always
|
||||
accurate.
|
||||
|
||||
.. tip::
|
||||
If the editor 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_md:
|
||||
@@ -85,11 +111,11 @@ Markdown Format
|
||||
===============
|
||||
|
||||
The document editor uses a simplified markdown format. That is, it supports basic formatting like
|
||||
emphasis (italic), strong emphasis (bold) and strikethrough text, as well as four levels of
|
||||
emphasis (italic), strong importance (bold) and strikethrough text, as well as four levels of
|
||||
headings.
|
||||
|
||||
Some non-standard markdown features have been added. For instance, novelWriter allows for comments,
|
||||
a synopsis tag, and a set of keyword/value sets used for tags and references.
|
||||
a synopsis tag, and a set of keyword and value sets used for tags and references.
|
||||
|
||||
|
||||
.. _a_ui_md_head:
|
||||
@@ -102,20 +128,24 @@ fit, but for all other file layouts used for the novel text itself, they indicat
|
||||
level of the novel. See :ref:`a_struct_heads` for more details.
|
||||
|
||||
``# Title``
|
||||
Heading level one. The space after the # is mandatory. If the file is a novel file, the header
|
||||
level indicates the start of a new partition.
|
||||
Heading level one. If the file is a novel file, the header level indicates the start of a new
|
||||
partition. This heading level can also be used for the title page novel title.
|
||||
|
||||
``## Title``
|
||||
Heading level two. The space after the # is mandatory. If the file is a novel file, the header
|
||||
level indicates the start of a new chapter.
|
||||
Heading level two. If the file is a novel file, the header level indicates the start of a new
|
||||
chapter.
|
||||
|
||||
``### Title``
|
||||
Heading level three. The space after the # is mandatory. If the file is a novel file, the header
|
||||
level indicates the start of a new scene.
|
||||
Heading level three. If the file is a novel file, the header level indicates the start of a new
|
||||
scene.
|
||||
|
||||
``#### Title``
|
||||
Heading level four. The space after the # is mandatory. If the file is a novel file, the header
|
||||
level indicates the start of a new section.
|
||||
Heading level four. If the file is a novel file, the header level indicates the start of a new
|
||||
section.
|
||||
|
||||
.. note::
|
||||
The space after the ``#`` characters is mandatory. The syntaxhighlighter will change colour and
|
||||
font size when the heading is correctly formatted.
|
||||
|
||||
|
||||
.. _a_ui_md_emph:
|
||||
@@ -123,21 +153,23 @@ level of the novel. See :ref:`a_struct_heads` for more details.
|
||||
Text Emphasis
|
||||
-------------
|
||||
|
||||
In markdown it is often recommended to differentiate between strong emphasis and emphasis by using
|
||||
``**`` for strong emphasis and ``_`` for emphasis, although markdown generally supports also ``__``
|
||||
for strong emphasis and ``*`` fdr 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:
|
||||
A minimal set of text emphasis styles are supported.
|
||||
|
||||
``_text_``
|
||||
The text is rendered as emphasised text (italicised).
|
||||
|
||||
``**text**``
|
||||
The text is rendered as strongly emphasised text (bold).
|
||||
The text is rendered as strongly important text (bold).
|
||||
|
||||
``~~text~~``
|
||||
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 ``__``
|
||||
for strong and ``*`` fdr 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
|
||||
@@ -157,7 +189,7 @@ 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`.
|
||||
the comment is treated specially, and will show up in the :ref:`a_ui_outline` in a dedicated column.
|
||||
|
||||
``% text...``
|
||||
A comment. The text is not exported by default (this can be overridden), seen in the Viewer, or
|
||||
@@ -175,9 +207,9 @@ the comment is treated specially, and will show up in the :ref:`a_ui_outline`.
|
||||
Tags and References
|
||||
-------------------
|
||||
|
||||
The document editor supports a minimal set of keywords used for setting tags and references between
|
||||
files. The tags and references can be set once per section defined by a heading. Using them multiple
|
||||
times under the same heading will just override the previous setting.
|
||||
The document editor supports a minimal set of keywords used for setting tags, and making references
|
||||
between files. The tags and references can be set once per section defined by a heading. Using them
|
||||
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.
|
||||
@@ -190,8 +222,9 @@ The available tag and reference keywords are listed in the :ref:`a_struct_tags`
|
||||
Additional Markdown and Non-Standard Features
|
||||
---------------------------------------------
|
||||
|
||||
The Editor and Viewer also supports markdown standard hard line breaks, and preserves non-breaking
|
||||
spaces if running with Qt 5.9 or higher.
|
||||
The editor and viewer also supports markdown standard hard line breaks, and preserves non-breaking
|
||||
spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when
|
||||
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.
|
||||
@@ -213,11 +246,16 @@ Project Outline View
|
||||
|
||||
The project's Outline view is available as the second tab on the right hand side of the main window
|
||||
labelled :guilabel:`Outline`. The outline provides an overview of the novel structure, displaying a
|
||||
tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings.
|
||||
tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings, not the files.
|
||||
|
||||
The document file 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 file in the
|
||||
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. See the :ref:`a_struct` page for more details.
|
||||
tree, these will not necessarily look the same, depending how you chose 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.
|
||||
A default set of such columns is visible, but you can turn on or off more columns by right clicking
|
||||
@@ -258,7 +296,7 @@ altering the colour of the word.
|
||||
Keyboard Shortcuts
|
||||
==================
|
||||
|
||||
Most features are available as keyboard shortcuts. These are as following:
|
||||
Most features are available as keyboard shortcuts. These are as follows:
|
||||
|
||||
.. csv-table:: Keyboard Shortcuts
|
||||
:header: "Shortcut", "Description"
|
||||
|
||||
Reference in New Issue
Block a user