novelWriter/docs/source/interface.txt

***************
User Interface
***************

The user interface is kept as simple as possible to avoid distractions when writing.
The main window contains a tree view pane with the entire structure of the project, and a small details panel below it to display additional information about the currently selected item.

Editing a document can be done by either double-clicking on it, or hitting the return key when a file is selected.
This will open the document editor, which uses a simplified markdown format, described in the section below.

The document currently being edited can also be viewed in parallel in a right hand side view pane.
To view a document, simply press :kbd:`Ctrl-R`, or select a file and go to :menuselection:`Document --> View Document` in the menu.
The document viewed does not need to be the same document currently being edited.

References to tags can also be opened in the view pane from the document editor by moving the cursor to a reference to a tag and hitting :kbd:`Ctrl-Enter`.
In the view panel, the references become clickable links, and the "Referenced By" panel at the bottom will show links to all documents referring back to it.

.. note::
   The "Referenced By" 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 :menuselection:`Tools --> Rebuild Index` or by pressing :kbd:`F9`.

Markdown Format
===============

The document editor uses a simplified markdown format.
That is, it supports basic formatting like bold, italics and underline, as well as four levels of headings.
The formats are listed below.

In addition to these standard markdown features, the editor also allows for comments, that is text that is ignored by the word counter and not exported or, optionally, hidden in the document viewer.
The editor also has a minimal set of keywords used for setting tags and references between files.

.. csv-table:: Formatting Syntax
   :header: "Format", "Description"
   :widths: 15, 50

   "``# Title``",         "Heading level one. The space after the # is mandatory."
   "``## Title``",        "Heading level two. The space after the # is mandatory."
   "``### Title``",       "Heading level three. The space after the # is mandatory."
   "``#### Title``",      "Heading level four. The space after the # is mandatory."
   "``**text**``",        "The text is rendered as bold text."
   "``_text_``",          "The text is rendered as italicized text."
   "``__text__``",        "The text is rendered as underlined text."
   "``% text...``",       "A comment. The text is not exported, seen in viewer, or counted towards word counts."
   "``@keyword: value``", "A keyword argument followed by a value, or a comma separated list of values."

The editor and viewer also supports markdown standard hard line breaks, and preserves non-breaking spaces.
A hard line break is achieved by leaving two or more spaces at the end of the line.
Alternatively, the user can press :kbd:`Shift-Enter` to insert this.
A non-breaking space is inserted with :kbd:`Shift-Space`.

Both hard line breaks and non-breaking spaces are highlighted by the syntax highlighter as an alternate coloured background, depending on the selected theme.

Keyboard Shortcuts
==================

All features are available as keyboard shortcuts.
These are as following:

.. csv-table:: Keyboard Shortcuts
   :header: "Shortcut", "Description"
   :widths: 15, 50

   ":kbd:`Alt-1`",           "Switch focus to tree view pane."
   ":kbd:`Alt-2`",           "Switch focus to document editor pane."
   ":kbd:`Alt-3`",           "Switch focus to document viewer pane."
   ":kbd:`Ctrl-.`",          "Correct word under cursor."
   ":kbd:`Ctrl-/`",          "Change block format to 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-A`",          "Select all text in document."
   ":kbd:`Ctrl-B`",          "Format selected text, or word under cursor, as bold."
   ":kbd:`Ctrl-C`",          "Copy selected text to clipboard."
   ":kbd:`Ctrl-D`",          "Wrap selected text, or word under cursor, in double quotes."
   ":kbd:`Ctrl-E`",          "If in tree view, edit a document or folder settings. (Same as :kbd:`F2`)"
   ":kbd:`Ctrl-F`",          "Open the search bar and search for selected word, if any is selected."
   ":kbd:`Ctrl-G`",          "Find next occurrence of word in current document. (Same as :kbd:`F3`)"
   ":kbd:`Ctrl-H`",          "Open the search and replace bar and search for selected word, if any is selected. (On Mac, this is :kbd:`Cmd+=`)"
   ":kbd:`Ctrl-I`",          "Format selected text, or word under cursor, as italic."
   ":kbd:`Ctrl-N`",          "Create new document."
   ":kbd:`Ctrl-O`",          "Open selected document."
   ":kbd:`Ctrl-Q`",          "Exit novelWriter."
   ":kbd:`Ctrl-R`",          "If in tree view, open a document for viewing. If in editor pane, open current document for viewing."
   ":kbd:`Ctrl-S`",          "Save the current document in the editor."
   ":kbd:`Ctrl-T`",          "Show project timeline."
   ":kbd:`Ctrl-U`",          "Format selected text, or word under cursor, as underline."
   ":kbd:`Ctrl-V`",          "Paste text from clipboard to cursor position."
   ":kbd:`Ctrl-W`",          "Close the current document in the editor."
   ":kbd:`Ctrl-X`",          "Cut selected text to clipboard."
   ":kbd:`Ctrl-Y`",          "Redo latest undo."
   ":kbd:`Ctrl-Z`",          "Undo latest changes."
   ":kbd:`Ctrl-F7`",         "Toggle spell checking."
   ":kbd:`Ctrl-Del`",        "If in tree view, move a document to trash, or delete a folder."
   ":kbd:`Ctrl-Enter`",      "Open the tag or reference under the cursor in the view panel."
   ":kbd:`Ctrl-Shift-,`",    "Change project settings."
   ":kbd:`Ctrl-Shift-/`",    "Remove block formatting for block under cursor."
   ":kbd:`Ctrl-Shift-1`",    "Replace occurrence of word in current document, and search for next occurrence."
   ":kbd:`Ctrl-Shift-A`",    "Select all text in current paragraph."
   ":kbd:`Ctrl-Shift-D`",    "Wrap selected text, or word under cursor, in single quotes."
   ":kbd:`Ctrl-Shift+G`",    "Find previous occurrence of word in current document. (Same as :kbd:`Shift-F3`"
   ":kbd:`Ctrl-Shift-I`",    "Import text to the current document from a text file."
   ":kbd:`Ctrl-Shift-N`",    "Create new folder."
   ":kbd:`Ctrl-Shift-O`",    "Open a project."
   ":kbd:`Ctrl-Shift-R`",    "Close the document view pane."
   ":kbd:`Ctrl-Shift-S`",    "Save the current project."
   ":kbd:`Ctrl-Shift-W`",    "Close the current project."
   ":kbd:`Ctrl-Shift-Up`",   "Move item one step up in the tree view."
   ":kbd:`Ctrl-Shift-Down`", "Move item one step down in the tree view."
   ":kbd:`F1`",              "Open documentation."
   ":kbd:`F2`",              "If in tree view, edit a document or folder settings. (Same as :kbd:`Ctrl-E`)"
   ":kbd:`F3`",              "Find next occurrence of word in current document. (Same as :kbd:`Ctrl-G`)"
   ":kbd:`F5`",              "Export project dialog."
   ":kbd:`F7`",              "Re-run spell checker."
   ":kbd:`F8`",              "Activate Zen Mode, hiding project tree and view panel."
   ":kbd:`F9`",              "Re-build project indices."
   ":kbd:`F11`",             "Activate full screen mode."
   ":kbd:`Shift-Enter`",     "Insert a hard line break at the cursor position."
   ":kbd:`Shift-F3`",        "Find previous occurrence of word in current document. (Same as :kbd:`Ctrl-Shift-G`"
   ":kbd:`Shift-Space`",     "Insert a non-breaking space at the cursor position."
   ":kbd:`Enter`",           "If in tree view, open a document for editing."

.. note::
   On macOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.