diff --git a/docs/source/images/fig_editor.png b/docs/source/images/fig_editor.png new file mode 100644 index 00000000..ba7181be Binary files /dev/null and b/docs/source/images/fig_editor.png differ diff --git a/docs/source/images/fig_editor_search.png b/docs/source/images/fig_editor_search.png new file mode 100644 index 00000000..020ef0e1 Binary files /dev/null and b/docs/source/images/fig_editor_search.png differ diff --git a/docs/source/images/fig_header_levels.png b/docs/source/images/fig_header_levels.png new file mode 100644 index 00000000..e427e3a2 Binary files /dev/null and b/docs/source/images/fig_header_levels.png differ diff --git a/docs/source/images/fig_novel_tree_view.png b/docs/source/images/fig_novel_tree_view.png new file mode 100644 index 00000000..f2938842 Binary files /dev/null and b/docs/source/images/fig_novel_tree_view.png differ diff --git a/docs/source/images/fig_outline_view.png b/docs/source/images/fig_outline_view.png new file mode 100644 index 00000000..467fa89a Binary files /dev/null and b/docs/source/images/fig_outline_view.png differ diff --git a/docs/source/images/fig_project_tree_detailed.png b/docs/source/images/fig_project_tree_detailed.png new file mode 100644 index 00000000..e46c5d30 Binary files /dev/null and b/docs/source/images/fig_project_tree_detailed.png differ diff --git a/docs/source/images/fig_project_tree_view.png b/docs/source/images/fig_project_tree_view.png new file mode 100644 index 00000000..667229ca Binary files /dev/null and b/docs/source/images/fig_project_tree_view.png differ diff --git a/docs/source/images/fig_references.png b/docs/source/images/fig_references.png new file mode 100644 index 00000000..3ffb9afa Binary files /dev/null and b/docs/source/images/fig_references.png differ diff --git a/docs/source/images/fig_viewer.png b/docs/source/images/fig_viewer.png new file mode 100644 index 00000000..05d4c459 Binary files /dev/null and b/docs/source/images/fig_viewer.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index c7c1180f..825c1b50 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 diff --git a/docs/source/int_customise.rst b/docs/source/int_customise.rst index 4c82cc80..c151322c 100644 --- a/docs/source/int_customise.rst +++ b/docs/source/int_customise.rst @@ -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 diff --git a/docs/source/int_glossary.rst b/docs/source/int_glossary.rst new file mode 100644 index 00000000..7d6fc105 --- /dev/null +++ b/docs/source/int_glossary.rst @@ -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 + ... diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst index a43e7949..c877777a 100644 --- a/docs/source/int_overview.rst +++ b/docs/source/int_overview.rst @@ -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 diff --git a/docs/source/usage_breakdown.rst b/docs/source/usage_breakdown.rst index 5b84b080..c1f3b6a6 100644 --- a/docs/source/usage_breakdown.rst +++ b/docs/source/usage_breakdown.rst @@ -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. - diff --git a/docs/source/usage_format.rst b/docs/source/usage_format.rst index 63a860c9..98000f83 100644 --- a/docs/source/usage_format.rst +++ b/docs/source/usage_format.rst @@ -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` and :term:`references`. 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. diff --git a/docs/source/usage_interface.rst b/docs/source/usage_interface.rst deleted file mode 100644 index 1b560743..00000000 --- a/docs/source/usage_interface.rst +++ /dev/null @@ -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 `_ - 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`. diff --git a/docs/source/usage_project.rst b/docs/source/usage_project.rst new file mode 100644 index 00000000..a86ecd4f --- /dev/null +++ b/docs/source/usage_project.rst @@ -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` 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` 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` 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`. diff --git a/docs/source/usage_projectformat.rst b/docs/source/usage_projectformat.rst index 6d357a69..3a0265f5 100644 --- a/docs/source/usage_projectformat.rst +++ b/docs/source/usage_projectformat.rst @@ -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 diff --git a/docs/source/usage_shortcuts.rst b/docs/source/usage_shortcuts.rst index 3eda423d..09e0b485 100644 --- a/docs/source/usage_shortcuts.rst +++ b/docs/source/usage_shortcuts.rst @@ -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" diff --git a/docs/source/usage_typography.rst b/docs/source/usage_typography.rst index 66910e75..8604f724 100644 --- a/docs/source/usage_typography.rst +++ b/docs/source/usage_typography.rst @@ -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. diff --git a/docs/source/usage_writing.rst b/docs/source/usage_writing.rst new file mode 100644 index 00000000..3373af18 --- /dev/null +++ b/docs/source/usage_writing.rst @@ -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` 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` 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 `_ + 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.