Update docs for 2.1 release (vkbo#1531)

tmarplatt · Oct 15, 2023 · ac36ce0 · ac36ce0
2 parents ed8d4a4 + ccffa91
commit ac36ce0
Show file tree

Hide file tree

Showing 43 changed files with 1,432 additions and 1,275 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -35,7 +35,7 @@
 time.tzset()
 
 needs_sphinx = "5.0"
-extensions = []
+extensions = ["sphinx_design"]
 templates_path = ["_templates"]
 source_suffix = ".rst"
 master_doc = "index"

diff --git a/docs/source/images/fig_build_build.png b/docs/source/images/fig_build_build.png
diff --git a/docs/source/images/fig_build_settings_headings.png b/docs/source/images/fig_build_settings_headings.png
diff --git a/docs/source/images/fig_build_settings_selections.png b/docs/source/images/fig_build_settings_selections.png
diff --git a/docs/source/images/fig_editor.png b/docs/source/images/fig_editor.png
diff --git a/docs/source/images/fig_editor_search.png b/docs/source/images/fig_editor_search.png
diff --git a/docs/source/images/fig_header_levels.png b/docs/source/images/fig_header_levels.png
diff --git a/docs/source/images/fig_manuscript_build.png b/docs/source/images/fig_manuscript_build.png
diff --git a/docs/source/images/fig_novel_tree_view.png b/docs/source/images/fig_novel_tree_view.png
diff --git a/docs/source/images/fig_outline_view.png b/docs/source/images/fig_outline_view.png
diff --git a/docs/source/images/fig_project_merge_tool.png b/docs/source/images/fig_project_merge_tool.png
diff --git a/docs/source/images/fig_project_split_tool.png b/docs/source/images/fig_project_split_tool.png
diff --git a/docs/source/images/fig_project_tree_detailed.png b/docs/source/images/fig_project_tree_detailed.png
diff --git a/docs/source/images/fig_project_tree_view.png b/docs/source/images/fig_project_tree_view.png
diff --git a/docs/source/images/fig_references.png b/docs/source/images/fig_references.png
diff --git a/docs/source/images/fig_viewer.png b/docs/source/images/fig_viewer.png
diff --git a/docs/source/images/python_win_install.png b/docs/source/images/python_win_install.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -18,18 +18,13 @@ storage for robustness.
 
 The project storage is suitable for version control software, and also well suited for file
 synchronisation tools. All text is saved as plain text files with a meta data header. The core
-project structure is stored in a single project XML file. Other meta data is primarily saved as
-JSON files. See the :ref:`a_breakdown_storage` section for more details.
+project structure is stored in a single project XML file. Other meta data is saved as 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.
+with pip. See :ref:`a_started` for more details.
 
 **Useful Links**
 
@@ -56,17 +51,18 @@ 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
    :caption: Using novelWriter
    :hidden:
 
    usage_breakdown
-   usage_interface
+   usage_project
+   usage_writing
    usage_format
    usage_shortcuts
    usage_typography
@@ -79,14 +75,15 @@ the pip tool. See :ref:`a_started` for more details.
 
    project_overview
    project_structure
-   project_notes
-   project_export
+   project_references
+   project_manuscript
 
 .. 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
@@ -17,14 +17,14 @@ Spell Check Dictionaries
 ========================
 
 novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or
-may not load installed spell check dictionaries.
+may not load all installed spell check dictionaries automatically.
 
 Linux and MacOS
 ---------------
 
 On Linux and MacOS, you generally only have to install hunspell or aspell dictionaries on your
 system like you do for other applications. See your distro or OS documentation for how to do this.
-These dictionaries should then show up as available spell check languages in novelWriter.
+These dictionaries should show up as available spell check languages in novelWriter.
 
 Windows
 -------
@@ -40,7 +40,6 @@ This assumes your user profile is stored at ``C:\Users\<USER>``. The last one or
 not exist, so you may need to create them.
 
 .. note::
-
    The Free Desktop link points to a repository, and what may look like file links inside the
    dictionary folder are actually links to web pages. If you right-click and download those, you
    get HTML files, not dictionaries!
@@ -54,8 +53,9 @@ not exist, so you may need to create them.
 Syntax and GUI Themes
 =====================
 
-Adding your own GUI and syntax themes is relatively easy. The themes are defined by simple plain
-text config files with meta data and colour settings.
+Adding your own GUI and syntax themes is relatively easy, altough it requires that you manually
+edit config files with colour values. The themes are defined by simple plain text config files with
+meta data and colour settings.
 
 In order to make your own versions, first copy one of the existing files to your local computer and
 modify it as you like.
@@ -78,16 +78,16 @@ 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.
+.. versionadded:: 2.0
+   The ``icontheme`` value was added to GUI themes. Make sure you set this value in existing custom
+   themes. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most
+   suitable one.
 
 
 Gustom GUI and Icons Theme
 --------------------------
 
-A GUI theme conf file consists of the follwing settings:
+A GUI theme ``.conf`` file consists of the follwing settings:
 
 .. code-block:: cfg
 
@@ -136,7 +136,7 @@ Omitted values are not loaded and will use default values.
 Custom Syntax Theme
 -------------------
 
-A syntax theme conf file consists of the follwing settings:
+A syntax theme ``.conf`` file consists of the follwing settings:
 
 .. code-block:: cfg
 
@@ -166,7 +166,6 @@ A syntax theme conf file consists of the follwing settings:
    replacetag     =   0,   0,   0
    modifier       =   0,   0,   0
 
-
 In the Main section, you must define at least the ``name`` setting. The Syntax colour values are
-RGB numbers on the format ``r, g, b`` where each is an integer from  to 255. Omitted values are set
+RGB numbers on the format ``r, g, b`` where each is an integer from  to 255. Omitted values default
 to black, except ``background`` which defaults to white,
diff --git a/docs/source/int_glossary.rst b/docs/source/int_glossary.rst
@@ -0,0 +1,64 @@
+.. _a_glossary:
+
+********
+Glossary
+********
+
+.. glossary::
+   :sorted:
+
+   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:`a_proj_roots`.
+
+   Novel Documents
+      These are documents that are created under a "Novel" :term:`root folder`. They behave
+      differently than :term:`Project Notes`, and have some more restrictions. For instance, they
+      can not exist in folders intended only for project notes. See the :ref:`a_struct` chapter for
+      more details.
+
+   Project Notes
+      Project Notes are unrestricted documents that can be placed anywhere in your project. You
+      should not use these documents for story elements, only for notes. Project notes are the
+      source files used by the Tags and References system. See the :ref:`a_references` chapter for
+      more details on how to use them.
+
+   Tag
+      A tag is a user defined value assigned as a tag to a section of your :term:`Project Notes`.
+      It is optional, and can be defined once per heading. It is set using the :term:`keyword`
+      syntax ``@tag: value``, where ``value`` is the user defined part. Each tag can be referenced
+      in another file using one of the :term:`reference` keywords. See :ref:`a_references` chapter
+      for more details.
+
+   Reference
+      A references is one of a set of :term:`keywords<keyword>` that can be used to link to a
+      :term:`tag` in another document. The reference keywords are specific to the different
+      :term:`root folder` types. A full overview is available in the :ref:`a_references` chapter.
+
+   Project Index
+      The project index is a record of all headings in a project, with all their meta data like
+      synopsis comments, :term:`tags<tag>` and :term:`references<reference>`. The project index is
+      kept up to date automatically, but can also be regenerated manually from the
+      :guilabel:`Tools` menu or by pressing :kbd:`F9`.
+
+   Context Menu
+      A context menu is a menu that pops up when you right click something in the user interface.
+      In novelWriter, you can often also open a context menu by pressing the keyboard shortcut
+      :kbd:`Ctrl+.`.
+
+   Headings
+      Each level of headings in :term:`Novel Documents` have a specific meaning in terms of the
+      structure of the story. That is, they determine what novelWriter considers a partition, a
+      chapter, a scene or a text section. For :term:`Project Notes`, the header levels don't
+      matter. For more details on headings in novel documents, see :ref:`a_struct_heads`.
+
+   Keyword
+      A keyword in novelWriter is a special command you put in the text of your documents. They are
+      not standard Markdown, but is used in novelWriter to add information that is interpreted by
+      the application. For instance, keywords are used for :term:`tags<tag>` and
+      :term:`references<reference>`.
+
+      Keywords must always be on their own line, and the first character of the line must always be
+      the ``@`` character. The keyword must also always be followed by a ``:`` character, and the
+      values passed to the command are added after this, separated by commas.
diff --git a/docs/source/int_howto.rst b/docs/source/int_howto.rst
@@ -9,117 +9,75 @@ Tips & Tricks
 This is a list of hopefully helpful little tips on how to get the most out of novelWriter.
 
 .. note::
-
-    This section will be expanded over time, and if you would like to have something added, feel
-    free to contribute, or start a discussion on the project's `Discussions Page`_
-
-
-Overview
-========
-
-**Managing the Project**
-
-* :ref:`a_howto_merge_documents`
-
-**Layout Tricks**
-
-* :ref:`a_howto_simple_table`
-
-**Organising Your Text**
-
-* :ref:`a_howto_chapter_intro`
-* :ref:`a_howto_soft_hard_breaks`
-
-**Other Tools**
-
-* :ref:`a_howto_convert_ywriter`
-
-
-How-Tos
-=======
+   This section will be expanded over time, and if you would like to have something added, feel
+   free to contribute, or start a discussion on the project's `Discussions Page`_.
 
 
 Managing the Project
---------------------
-
-
-.. _a_howto_merge_documents:
+====================
 
-Merge Multiple Documents Into One
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. dropdown:: Merge Multiple Documents Into One
+   :animate: fade-in-slide-down
 
-If you need to merge a set of documents in your project into a single document, you can achieve
-this by first making a new folder for just that purpose, and drag all the files you want merged
-into this folder. Then you can right click the folder, select :guilabel:`Transform` and
-:guilabel:`Merge Documents in Folder`.
+   If you need to merge a set of documents in your project into a single document, you can achieve
+   this by first making a new folder for just that purpose, and drag all the files you want merged
+   into this folder. Then you can right click the folder, select :guilabel:`Transform` and
+   :guilabel:`Merge Documents in Folder`.
 
-In the dialog that pops up, the documents will be in the same order as in the folder, but you can
-also rearrange them here of you wish.
+   In the dialog that pops up, the documents will be in the same order as in the folder, but you
+   can also rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details.
 
 
 Layout Tricks
--------------
+=============
 
+.. dropdown:: Create a Simple Table
+   :animate: fade-in-slide-down
 
-.. _a_howto_simple_table:
+   The formatting tools available in novelWriter don't allow for complex structures like tables.
+   However, the editor does render tabs in a similar way that regular word processors do. You can
+   set the width of a tab in :guilabel:`Preferences`.
 
-Create a Simple Table
-^^^^^^^^^^^^^^^^^^^^^
+   The tab key should have the same distance in the editor as in the viewer, so you can align text
+   in columns using the tab key, and it should look the same when viewed next to the editor.
 
-The formatting tools available in novelWriter don't allow for complex structures like tables.
-However, the editor does render tabs in a similar way to regular word processors. You can set the
-width of a tab in :guilabel:`Preferences`.
-
-The tab key should have the same distance in the editor as in the viewer, so you can align text in
-columns using the tab key, and it should look the same when viewed next to the editor.
-
-This is most suitable for your notes, as the result in exported documents cannot be guaranteed to
-match.
+   This is most suitable for your notes, as the result in exported documents cannot be guaranteed
+   to match.
 
 
 Organising Your Text
---------------------
-
+====================
 
-.. _a_howto_chapter_intro:
+.. dropdown:: Add Introductory Text to Chapters
+   :animate: fade-in-slide-down
 
-Add Introductory Text to Chapters
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   Sometimes chapters have a short preface, like a brief piece of text or a quote to set the stage
+   before the first scene begins.
 
-Sometimes chapters have a short preface, like a brief piece of text or a quote to set the stage
-before the first scene -- Some text that may not be a part of the actual following scene.
+   If you add separate files for chapters and scenes, the chapter file is the perfect place to add
+   such text. Separating chapter and scene files also allows you to make scene files child
+   documents of the chapter (added in novelWriter 2.0).
 
-If you add separate files for chapters and scenes, this is the perfect place to add such text.
-Separating chapter and scene files also allows you to set meta data for the whole chapter. Like
-list all characters present in the chapter, etc.
+.. dropdown:: Distinguishing Soft and Hard Scene Breaks
+   :animate: fade-in-slide-down
 
+   Depending on your writing style, you may need to separate between soft and hard scene breaks
+   within chapters. Like for instance if you switch point-of-view character often.
 
-.. _a_howto_soft_hard_breaks:
-
-Distinguishing Soft and Hard Scene Breaks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Depending on your writing style, you may need to separate between soft and hard scene breaks within
-chapters. Like for instance if you switch point-of-view character often.
-
-In such cases you may want to use the scene heading for hard scene breaks and section headings for
-soft scene breaks. the :guilabel:`Project Build Tool` will let you add separate formatting for the
-two when you generate your manuscript. You can for instance add the common "``* * *``" for hard
-breaks and select to hide section breaks, which will just insert an empty paragraph in their place.
+   In such cases you may want to use the scene heading for hard scene breaks and section headings
+   for soft scene breaks. the :guilabel:`Build Manuscript` tool will let you add separate
+   formatting for the two when you generate your manuscript. You can for instance add the common
+   "``* * *``" for hard breaks and select to hide section breaks, which will just insert an empty
+   paragraph in their place. See :ref:`a_manuscript_settings` for more details.
 
 
 Other Tools
------------
-
-
-.. _a_howto_convert_ywriter:
-
-Convert Project to/from yWriter Format
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+===========
 
-.. _yWriter: http://spacejock.com/yWriter7.html
+.. dropdown:: Convert Project to/from yWriter Format
+   :animate: fade-in-slide-down
 
-There is a tool available that lets you convert a yWriter_ project to a novelWriter project, and
-vice versa.
+   There is a tool available that lets you convert a `yWriter <http://spacejock.com/yWriter7.html>`_
+   project to a novelWriter project, and vice versa.
 
-The tool is available at `peter88213.github.io/yw2nw <https://peter88213.github.io/yw2nw/>`__
+   The tool is available at `peter88213.github.io/yw2nw <https://peter88213.github.io/yw2nw/>`__