Update documentation for 2.5 (#1928)

Author: vkbo

docs/source/images/fig_project_tree_detailed.png

@@ -39,6 +39,23 @@ Managing the Project
 Layout Tricks
 =============
 
+.. dropdown:: Align Paragraphs with Line Breaks
+   :animate: fade-in-slide-down
+
+   If you have line breaks in you paragraphs, and also want to apply additional text alignment or
+   indentation, you must apply the alignment tags to the first line.
+
+   For example, this will centre the two lines.
+
+   .. code-block:: md
+
+      >> Line one is centred. <<
+      Line two is also centred.
+
+      This text is not centred, because it is a new paragraph.
+
+   See :ref:`a_fmt_align` for more details.
+
 .. dropdown:: Create a Simple Table
    :animate: fade-in-slide-down
 
@@ -52,6 +69,15 @@ Layout Tricks
    This is most suitable for your notes, as the result in exported documents cannot be guaranteed
    to match. Especially if you don't use the same font in your manuscript as in the editor.
 
+.. dropdown:: Turn Off First Line Indent for a Paragraph
+   :animate: fade-in-slide-down
+
+   If you have first line indent enabled, but have a specific paragraph that you don't want
+   indented, you can disable the indentation by explicitly add text alignment. Aligned paragraphs
+   are not indented. For instance by adding ``<<`` to the end to left-align it,
+
+   See :ref:`a_fmt_align` for more details.
+
 
 Organising Your Text
 ====================

docs/source/int_howto.rst

@@ -12,16 +12,17 @@ text without having to deal with formatting until you generate a draft document
 Instead, you can focus on the writing right from the start.
 
 Of course, you probably need *some* formatting for your text. At the very least you need emphasis.
-Most people are familiar with adding emphasis using underscores and asterisks. This formatting
-standard comes from Markdown_ and is supported by novelWriter. It also uses Markdown formatting for
-defining document headings. If you need more specialised formatting, additional formatting options
-are available using a shortcode format. See :ref:`a_fmt_shortcodes` for more details.
+Most people are familiar with adding emphasis using ``_underscores_`` and ``**asterisks**``. This
+formatting standard comes from Markdown_ and is supported by novelWriter. It also uses Markdown
+formatting for defining document headings. If you need more specialised formatting, additional
+formatting options are available using a shortcode format. See :ref:`a_fmt_shortcodes` for more
+details.
 
 .. admonition:: Limitations
 
    novelWriter is designed for writing fiction, so the formatting features available are limited to
-   those relevant for this purpose. It is **not** suitable for technical writing, and it is **not**
-   a full-featured Markdown editor.
+   those relevant for this purpose. It is *not* suitable for technical writing, and it is *not* a
+   full-featured Markdown editor.
 
    It is also not intended as a tool for organising research for writing, and therefore lacks
    formatting features you may need for this purpose. The notes feature in novelWriter is mainly
@@ -32,7 +33,7 @@ instead of a single, large document. The idea is to make it easier to reorganise
 structure without having to cut and paste text between chapters and scenes.
 
 There are two kinds of documents in your project: :term:`Novel Documents` are documents that are
-part of your story. The other kind of documents are :term:`Project Notes`. These are intended for
+part of your story. The other kind of documents are :term:`Project Notes`, which are intended for
 your notes about your characters, your world building, and so on.
 
 You can at any point split the individual documents by their headings up into multiple documents,
@@ -51,9 +52,12 @@ Below are some key features of novelWriter.
 **Focus on writing**
    The aim of the user interface is to let you focus on writing instead of spending time formatting
    text. Formatting is therefore limited to a small set of formatting tags for simple things like
-   text emphasis and paragraph alignment. When you really want to focus on just writing, you can
-   switch the editor into **Focus Mode** where only the text editor panel itself is visible, and
-   the project structure view is hidden away.
+   text emphasis and paragraph alignment. Additional shortcodes are available for special
+   formatting cases.
+
+   When you really want to focus on just writing, you can switch the editor into **Focus Mode**
+   where only the text editor panel itself is visible, and the project structure view is hidden
+   away.
 
 **Keep an eye on your notes**
    The main window can optionally show a document viewer to the right of the editor. The viewer
@@ -72,19 +76,22 @@ Below are some key features of novelWriter.
 **Multi-novel project support**
    The main parts of your project is split up into top level special folders called "Root" folders.
    Your main story text lives in the "Novel" root folder. You can have multiple such folders in a
-   project. This allows you to keep a series of individual novels with the same characters and
-   world building in the same project, and create manuscripts for them individually.
+   project, and rename them to whatever you want. This allows you to keep a series of individual
+   novels with the same characters and world building in the same project, and create manuscripts
+   for them individually.
 
 **Keep track of your story elements**
    All notes in your project can be assigned a :term:`tag` that you can then :term:`reference` from
    any other document or note. In fact, you can add a new tag under each heading of a note if you
-   need to be able to reference specific sections of it.
+   need to be able to reference specific sections of it, or you want to keep several topics in the
+   same note.
 
 **Get an overview of your story**
    It is not the documents themselves that define the chapters and scenes of your story, but the
    headings that separate them. In the **Outline View** on the main window you can see an outline
-   of all the chapter and scene headings of your project. If they have any references in them, like
-   which character is in what chapter and scene, these are listed in additional columns.
+   of all the chapter and scene headings of each novel root folder in your project. If they have
+   any references in them, like which character is in what chapter and scene, these are listed in
+   additional columns.
 
    You can also add a synopsis to each chapter or scene, which can be listed here as well. You have
    the option to add or remove columns of information from this outline. A subset of the outline
@@ -100,9 +107,9 @@ Below are some key features of novelWriter.
    Whether you want to assemble a manuscript, or export all your notes, or generate an outline of
    your chapters and scenes with a synopsis included, you can use the **Build Manuscript** tool to
    do so. The tool lets you select what information you want to include in the generated document,
-   and how it is formatted. You can send the result to a printer, a PDF, or to an Open Document
-   file that can be opened by most office type word processors. You can also generate the result
-   as HTML, or Markdown, both suitable for further conversion to other formats.
+   and how it is formatted. You can send the result to a printer or PDF, or generate an Open
+   Document file that can be opened by most office type word processors. You can also generate the
+   result as HTML, or Markdown, both suitable for further conversion to other formats.
 
 
 .. _a_intro_screenshots:

docs/source/int_introduction.rst

@@ -10,7 +10,7 @@ but you don't need all of them to get started.
 The chapters below labelled "Essential Information" are the ones you need to know to use the
 application correctly. By "correctly", it is meant: in a way so novelWriter understands the basic
 structure of your text. It collects a lot of information from your text and uses it to display the
-structure of it in various ways to help you get an overview of your project.
+structure of it in various ways to help you get an overview of your writing.
 
 The chapters labelled "Recommended Reading" includes additional information on how the different
 parts if the application work and what the features do. 

docs/source/int_overview.rst

@@ -306,7 +306,8 @@ Status and Importance Tabs
 --------------------------
 
 Each document or folder of type **Novel** can be given a "Status" label accompanied by a coloured
-icon, and each document or folder of the remaining types can be given an "Importance" label.
+icon with an optional shape selected from a list of pre-defined shapes. Each document or folder of
+the remaining types can be given an "Importance" label with the same customisation options.
 
 These labels are there purely for your convenience, and you are not required to use them for any
 other features to work. No other part of novelWriter accesses this information. The intention is to

docs/source/project_overview.rst

@@ -43,8 +43,8 @@ project-related tools and quick access to settings at the bottom.
 
 .. versionadded:: 2.2
    A number of new formatting options were added in 2.2 to allow for some special formatting cases.
-   At the same time, a small formatting toolbar was added in the editor. It is hidden by default,
-   but can be opened by pressing the icon button in the top right corner.
+   At the same time, a small formatting toolbar was added to the editor. It is hidden by default,
+   but can be opened by pressing the button in the top right corner of the editor header.
 
 
 Project Tree and Editor View
@@ -148,6 +148,20 @@ in the document editor that acts on the open document.
 .. versionadded:: 2.4
 
 
+Switching Focus
+---------------
+
+If the project or novel view does not have focus, pressing :kbd:`Ctrl+T` switches focus to
+whichever of the two is visible. If one of them already has focus, the key press will switch
+between them instead.
+
+Likewise, pressing :kbd:`Ctrl+E` with switch focus to the document editor or viewer, or if any of
+them already have focus, it will switch focus between them,
+
+These two shortcuts makes it possible to jump between all these GUI elements without having to
+reach for the mouse or touchpad.
+
+
 .. _a_breakdown_project:
 
 Project Layout

docs/source/usage_breakdown.rst

@@ -125,8 +125,8 @@ background, depending on the selected theme.
 
 .. _a_fmt_emph:
 
-Text Emphasis
-=============
+Text Emphasis with Markdown
+===========================
 
 A minimal set of Markdown text emphasis styles are supported for text paragraphs.
 
@@ -156,7 +156,7 @@ In addition, the following rules apply:
    outside, they violate rule 2.
 4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or
    paragraphs, you must apply it to each of them in turn.
-5. Text emphasis can only be used in plain paragraphs. Comments, titles, and meta data tags don't
+5. Text emphasis can only be used in comments and paragraphs. Headings and meta data tags don't
    allow for formatting, and any formatting markup will be rendered as-is.
 
 .. tip::
@@ -168,8 +168,8 @@ In addition, the following rules apply:
 
 .. _a_fmt_shortcodes:
 
-Extended Formatting with Shortcodes
-===================================
+Formatting with Shortcodes
+==========================
 
 For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes
 that can be used to change the format of the text that follows and opening code, and last until
@@ -197,6 +197,13 @@ word if you need to. You can also freely combine them to form more complex forma
 The shortcodes are available from the **Format** menu and in the editor toolbar, which can be
 activated by clicking the left-most icon button in the editor header.
 
+.. note::
+
+   Shortcodes are not processed until you generate a preview or generate a manuscript document. So
+   there is no highlighting of the text between the formatting markers. There is also no check that
+   your markers make sense. You must ensure that you have both the opening and closing formatting
+   markers where you want them.
+
 .. versionadded:: 2.2
 
 
@@ -217,44 +224,101 @@ correctly formatted, the syntax highlighter will indicate this by altering the c
 
 The different styles of comments are as follows:
 
-``% Comment text ...``
+``% Your comment text ...``
    This is a comment. The text is not rendered by default (this can be overridden), seen in the
    document viewer, or counted towards word counts. It is intended for you to make notes in your
    text for your own sake, whatever that may be, that isn't part of the story text. This is the
    general format of a comment.
 
-``%Synopsis: Comment text ...``
+``%Synopsis: Your synopsis text ...``
    This is a synopsis comment. It is generally treated in the same way as a regular comment, except
    that it is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It
    can also be filtered separately when building the project to for instance generate an outline
    document of the whole project.
 
-``%Short: Comment text ...``
+``%Short: Your short description ...``
    This is a short description comment. It is identical to the synopsis comment (they are
    interchangeable), but is intended to be used for project notes. The text shows up in the
    Reference panel below the document viewer in the last column labelled **Short Description**.
 
-``%~ Comment text ...``
-   This can be used to exclude story text from your manuscript without having to delete it from
-   your text. Comments with the ``~`` will *never* be included in the manuscript, even if you have
-   chosen to include comments in it. That is the main difference between these two formats.
+``%Footnote.<key>: Your footnote text ...``
+   This is a special comment assigned to a footnote marker. See :ref:`a_fmt_footnote` for how to
+   use them in your text.
 
 .. note::
    Only one comment can be flagged as a synopsis or short comment for each heading. If multiple
    comments are flagged as synopsis or short comments, the last one will be used and the rest
    ignored.
 
 
+.. _a_fmt_footnote:
+
+Footnotes
+=========
+
+Footnotes are added with a shortcode, paired with a matching comment for the actual footnote text.
+The matching is done with a key that links the two. If you insert a footnote from the **Insert**
+menu, a unique key is generated for you.
+
+The insert feature will add the footnote shortcode marker at the position of your cursor in the
+text, and create the associated footnote comment right after the paragraph, and move the cursor
+there so you can immediately start typing the footnote text.
+
+The footnote comment can be anywhere in the document, so if you wish to move them to, say, the
+bottom of the text, you are free to do so.
+
+Footnote keys are only required to be unique within a document, so if you copy, move or merge text,
+you must make sure the keys are not duplicated. If you use the automatically generated keys from
+the **Insert** menu, they are unique among all indexed documents. They are not guaranteed to be
+unique against footnotes in the Archive or Trash folder though, but the chance of accidentally
+generating the same key twice in a project is relatively small in the first place (1 in 810 000).
+
+This is what a footnote inserted into a paragraph may look like when completed:
+
+.. code-block:: md
+
+   This is a text paragraph with a footnote[footnote:fn1] in the middle.
+
+   %Footnote.fn1: This is the text of the footnote.
+
+.. versionadded:: 2.5
+
+
+.. _a_fmt_ignore:
+
+Ignored Text
+============
+
+If you want to completely ignore some of the text in your documents, but are not ready to delete
+it, you can add ``%~`` before the text paragraph or line. This will cause novelWriter to skip the
+text entirely when generating previews or building manuscripts.
+
+This is a better way of removing text than converting them to regular comments, as you may want to
+include regular comments in your previews or draft manuscript.
+
+You can toggle the ignored text feature on and off for a paragraph by pressing :kbd:`Ctrl+Shift+D`
+on your keyboard with your cursor somewhere in the paragraph.
+
+Example:
+
+.. code-block:: md
+
+   %~ This text is ignored.
+
+   This text is a regular paragraph.
+
+
 .. _a_fmt_tags:
 
 Tags and References
 ===================
 
 The document editor supports a set of keywords used for setting tags, and making references between
-documents.
+documents based on those tags.
 
-Tags use the keyword ``@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.
+You must use the keyword ``@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 keyword followed by the tag value, like for instance the name of a character.
@@ -306,6 +370,40 @@ Examples:
    from the manuscript build tool as long as the format supports paragraph alignment.
 
 
+Alignment with Line Breaks
+--------------------------
+
+If you have line breaks in the paragraph, like for instance when you are writing verses, the
+alignment markers must be applied to the first line. Markers on the other lines are ignored. The
+markers for the first line are used for all the other lines.
+
+For the following text, all lines will be centred, not just the first:
+
+.. code-block:: md
+
+   >> I am the very model of a modern Major-General <<
+   I've information vegetable, animal, and mineral
+   I know the kings of England, and I quote the fights historical
+   From Marathon to Waterloo, in order categorical
+
+
+Alignment with First Line Indent
+--------------------------------
+
+If you have first line indent enabled in your Manuscript build settings, you probably want to
+disable it for text in verses. Adding any alignment tags will cause the first line indent to be
+switched off for that paragraph.
+
+The following text will always be aligned against the left margin:
+
+.. code-block:: md
+
+   I am the very model of a modern Major-General <<
+   I've information vegetable, animal, and mineral
+   I know the kings of England, and I quote the fights historical
+   From Marathon to Waterloo, in order categorical
+
+
 .. _a_fmt_break:
 
 Vertical Space and Page Breaks

docs/source/usage_format.rst

@@ -54,7 +54,8 @@ At the top of the project tree, you will find a set of buttons.
 * 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`.
+  folders and template documents. 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.
 
 Below the project tree you will find a small details panel showing the full information of the

docs/source/usage_project.rst

@@ -26,7 +26,7 @@ Main Window Shortcuts
    ":kbd:`F9`",           "Re-build the project's index"
    ":kbd:`F11`",          "Toggle full screen mode"
    ":kbd:`Ctrl+,`",       "Open the **Preferences** dialog"
-   ":kbd:`Ctrl+E`",       "Switch focus to the document editor"
+   ":kbd:`Ctrl+E`",       "Switch or toggle focus for the editor or viewer"
    ":kbd:`Ctrl+T`",       "Switch or toggle focus for the project tree or novel view"
    ":kbd:`Ctrl+Q`",       "Exit novelWriter"
    ":kbd:`Ctrl+Shift+,`", "Open the **Project Settings** dialog"