From 21eebbb88fc9277c82bc10a257bb9fe25beb9e9c Mon Sep 17 00:00:00 2001 From: "Veronica K. B. Olsen" <1619840+vkbo@users.noreply.github.com> Date: Thu, 6 Aug 2020 22:08:36 +0200 Subject: [PATCH] Made a new pass of all the previously updated documentation files --- README.md | 2 + docs/source/conf.py | 1 + docs/source/export.rst | 2 + docs/source/images/novelwriter.png | Bin 0 -> 5489 bytes docs/source/index.rst | 59 ++++++++-- docs/source/interface.rst | 166 +++++++++++++++-------------- docs/source/introduction.rst | 52 +++++---- docs/source/notes.rst | 2 + docs/source/projects.rst | 135 +++++++++++------------ docs/source/started.rst | 25 +++-- 10 files changed, 262 insertions(+), 182 deletions(-) create mode 100644 docs/source/images/novelwriter.png diff --git a/README.md b/README.md index 4f4296fd..0c7ef8ec 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ [![Build Status](https://travis-ci.com/vkbo/novelWriter.svg?branch=master)](https://travis-ci.com/vkbo/novelWriter) [![codecov](https://codecov.io/gh/vkbo/novelWriter/branch/master/graph/badge.svg)](https://codecov.io/gh/vkbo/novelWriter) [![Documentation Status](https://readthedocs.org/projects/novelwriter/badge/?version=latest)](https://novelwriter.readthedocs.io/en/latest/?badge=latest) +[![PyPI](https://img.shields.io/pypi/v/novelwriter)](https://pypi.org/project/novelWriter/) +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/novelwriter)](https://pypi.org/project/novelWriter/) novelWriter is a markdown-like text editor designed for writing novels and larger projects of many smaller plain text documents. diff --git a/docs/source/conf.py b/docs/source/conf.py index 71cbf8db..1755d7b4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -70,6 +70,7 @@ pygments_style = None # -- Options for HTML output ------------------------------------------------- html_theme = "sphinx_rtd_theme" +html_logo = "images/novelwriter.png" html_theme_options = { # Toc options "collapse_navigation": True, diff --git a/docs/source/export.rst b/docs/source/export.rst index 8dd24631..5297deb8 100644 --- a/docs/source/export.rst +++ b/docs/source/export.rst @@ -1,3 +1,5 @@ +.. _a_export: + ################## Exporting Projects ################## diff --git a/docs/source/images/novelwriter.png b/docs/source/images/novelwriter.png new file mode 100644 index 0000000000000000000000000000000000000000..a9f2b5bcdef18f15a36f665d9f5e091395d68de2 GIT binary patch literal 5489 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 Rebuild Index` or by - pressing :kbd:`F9`. + The :guilabel:`References` panel relies on an up-to-date index of the project. If anything is + missing, or seems wrong, the index can always be rebuilt from :guilabel:`Tools` > + :guilabel:`Rebuild Index` or by pressing :kbd:`F9`. .. _a_ui_md: @@ -83,8 +84,9 @@ convenient if you want to quickly look through all documents in the list. Markdown Format =============== -The Editor uses a simplified markdown format. That is, it supports basic formatting like emphasis -(italic), strong emphasis (bold) and strikethrough text, as well as four levels of headings. +The document editor uses a simplified markdown format. That is, it supports basic formatting like +emphasis (italic), strong emphasis (bold) and strikethrough text, as well as four levels of +headings. Some non-standard markdown features have been added. For instance, novelWriter allows for comments, a synopsis tag, and a set of keyword/value sets used for tags and references. @@ -125,7 +127,7 @@ In markdown it is often recommended to differentiate between strong emphasis and ``**`` for strong emphasis and ``_`` for emphasis, although markdown generally supports also ``__`` for strong emphasis and ``*`` fdr emphasis. However, since the differentiation makes the highlighting and conversion significantly simpler and faster, in novelWriter this is a rule, not -just a recommendation. +just a recommendation. The following is therefore the only supported formatting syntax: ``_text_`` The text is rendered as emphasised text (italicised). @@ -152,8 +154,8 @@ There are also some additional rules: Comments and Synopsis --------------------- -In addition to these standard markdown features, the novelWriter also allows for comments in the -text files. The text of the comment is ignored by the word counter and not exported or, optionally, +In addition to these standard markdown features, novelWriter also allows for comments in the text +files. The text of the comment is ignored by the word counter and not exported or, optionally, hidden when viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon), the comment is treated specially, and will show up in the :ref:`a_ui_outline`. @@ -173,7 +175,9 @@ the comment is treated specially, and will show up in the :ref:`a_ui_outline`. Tags and References ------------------- -The Editor also has a minimal set of keywords used for setting tags and references between files. +The document editor supports a minimal set of keywords used for setting tags and references between +files. The tags and references can be set once per section defined by a heading. Using them multiple +times under the same heading will just override the previous setting. ``@keyword: value`` A keyword argument followed by a value, or a comma separated list of values. @@ -195,7 +199,7 @@ spaces if running with Qt 5.9 or higher. * 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`. -These are all insert features, and the :menuselection:`Insert` menu has more. They are also listed +These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed in :ref:`a_ui_shortcuts_ins`. Both hard line breaks and non-breaking spaces are highlighted by the syntax highlighter as an @@ -207,29 +211,29 @@ alternate coloured background, depending on the selected theme. Project Outline View ==================== -The Project Outline View is available as the second tab on the right hand side of the main window -labelled "Outline". The Outline View 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. +The project's Outline view is available as the second tab on the right hand side of the main window +labelled :guilabel:`Outline`. The outline provides an overview of the novel structure, displaying a +tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings. .. note:: - Since the internal structure of the novel does not depend on the file structure of the Project - Tree, these will not necessarily look the same. See the :ref:`a_struct` page for more details. + Since the internal structure of the novel does not depend on the file structure of the project + tree, these will not necessarily look the same. See the :ref:`a_struct` page for more details. -Various meta data and information extracted from tags can be displayed in columns in the Outline -View. A default set is visible, but you can turn on or off more columns by right clicking the header -and selecting the columns you want to show. The order of the columns can also be rearranged by -dragging them to a different position. +Various meta data and information extracted from tags can be displayed in columns in the outline. +A default set of such columns is visible, but you can turn on or off more columns by right clicking +the header and selecting the columns you want to show. The order of the columns can also be +rearranged by dragging them to a different position. .. note:: - The Title column cannot be disabled or moved. + The :guilabel:`Title` column cannot be disabled or moved. -The information viewed in the Outline View is based on the Project Index. While novelWriter does its -best to keep the index up to date when content changes, you can always rebuild it manually by +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 content changes, you can always rebuild it manually by pressing :kbd:`F9` if something isn't right. -The Outline View itself can be regenerated by pressing :kbd:`F10`. You can also enable automatic -updating in the :menuselection:`Tools` menu, which will trigger an update whenever the index is -updated and the Outline tab is activated. You may want to disable this feature if your project is +The outline view itself can be regenerated by pressing :kbd:`F10`. You can also enable automatic +updating in the :guilabel:`Tools` menu, which will trigger an update whenever the index is updated +and the :guilabel:`Outline` tab is active. You may want to disable this feature if your project is very large, @@ -238,15 +242,15 @@ very large, Synopsis Column --------------- -The "Synopsis" column of the Outline View takes its information from a specially formatted comment. -See :ref:`a_ui_md_comm`. In order to flag a comment as a synopsis, add the word ``Synopsis:`` as the -first word of the comment. The ``:`` is required, and the word ``synopsis`` is not case sensitive. -If it is correctly formatted, the syntax highlighter will indicate this by altering the colour of -the word. +The :guilabel:`Synopsis` column of the outline view takes its information from a specially formatted +comment. See :ref:`a_ui_md_comm`. In order to flag a comment as a synopsis, add the word +``Synopsis:`` as the first word of the comment. The ``:`` is required, and the word ``synopsis`` is +not case sensitive. If it is correctly formatted, the syntax highlighter will indicate this by +altering the colour of the word. .. note:: Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are - flagged as a synopsis, the last one will be used. + flagged as a synopsis comment, the last one will be used. .. _a_ui_shortcuts: @@ -261,11 +265,11 @@ Most features are available as keyboard shortcuts. These are as following: :widths: 30, 70 :class: "tight-table" - ":kbd:`Alt`:kbd:`1`", "Switch focus to the Project Tree." - ":kbd:`Alt`:kbd:`2`", "Switch focus to Editor." - ":kbd:`Alt`:kbd:`3`", "Switch focus to Viewer." + ":kbd:`Alt`:kbd:`1`", "Switch focus to the project tree." + ":kbd:`Alt`:kbd:`2`", "Switch focus to document editor." + ":kbd:`Alt`:kbd:`3`", "Switch focus to document viewer." ":kbd:`Ctrl`:kbd:`.`", "Open menu to correct word under cursor." - ":kbd:`Ctrl`:kbd:`,`", "Open the Preferences dialog." + ":kbd:`Ctrl`:kbd:`,`", "Open the :guilabel:`Preferences` dialog." ":kbd:`Ctrl`:kbd:`/`", "Change block format to comment." ":kbd:`Ctrl`:kbd:`-`", "Strikethrough selected text, or word under cursor." ":kbd:`Ctrl`:kbd:`0`", "Remove block formatting for block under cursor." @@ -277,7 +281,7 @@ Most features are available as keyboard shortcuts. These are as following: ":kbd:`Ctrl`:kbd:`B`", "Format selected text, or word under cursor, with strong emphasis (bold)." ":kbd:`Ctrl`:kbd:`C`", "Copy selected text to clipboard." ":kbd:`Ctrl`:kbd:`D`", "Wrap selected text, or word under cursor, in double quotes." - ":kbd:`Ctrl`:kbd:`E`", "If in the Project Tree, edit a document or folder settings. (Same as :kbd:`F2`)" + ":kbd:`Ctrl`:kbd:`E`", "If in the project tree, edit a document or folder settings. (Same as :kbd:`F2`)" ":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. (Same as :kbd:`F3`)" ":kbd:`Ctrl`:kbd:`H`", "Open the search and replace bar and search for the selected word, if any is selected. (On Mac, this is :kbd:`Cmd`:kbd:`=`)" @@ -285,18 +289,18 @@ Most features are available as keyboard shortcuts. These are as following: ":kbd:`Ctrl`:kbd:`N`", "Create new document." ":kbd:`Ctrl`:kbd:`O`", "Open selected document." ":kbd:`Ctrl`:kbd:`Q`", "Exit novelWriter." - ":kbd:`Ctrl`:kbd:`R`", "If in the Project Tree, open a document for viewing. If the Editor has focus, open current document for viewing." - ":kbd:`Ctrl`:kbd:`S`", "Save the current document in the Editor." + ":kbd:`Ctrl`:kbd:`R`", "If in the project tree, open a document for viewing. If the editor has focus, open current document for viewing." + ":kbd:`Ctrl`:kbd:`S`", "Save the current document in the document editor." ":kbd:`Ctrl`:kbd:`V`", "Paste text from clipboard to cursor position." - ":kbd:`Ctrl`:kbd:`W`", "Close the current document in the Editor." + ":kbd:`Ctrl`:kbd:`W`", "Close the current document in the document editor." ":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:`F7`", "Toggle spell checking." - ":kbd:`Ctrl`:kbd:`F10`", "Toggle automatic updating of Project Outline." - ":kbd:`Ctrl`:kbd:`Del`", "If in the Project Tree, move a document to trash, or delete a folder." + ":kbd:`Ctrl`:kbd:`F10`", "Toggle automatic updating of project outline." + ":kbd:`Ctrl`:kbd:`Del`", "If in the project tree, move a document to trash, or delete a folder." ":kbd:`Ctrl`:kbd:`Enter`", "Open the tag or reference under the cursor in the Viewer." - ":kbd:`Ctrl`:kbd:`Shift`:kbd:`,`", "Open the Project Settings dialog." + ":kbd:`Ctrl`:kbd:`Shift`:kbd:`,`", "Open the :guilabel:`Project Settings` dialog." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`/`", "Remove block formatting for block under cursor." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`1`", "Replace occurrence of search word in current document, and search for next occurrence." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`A`", "Select all text in current paragraph." @@ -305,23 +309,23 @@ Most features are available as keyboard shortcuts. These are as following: ":kbd:`Ctrl`:kbd:`Shift`:kbd:`I`", "Import text to the current document from a text file." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`N`", "Create new folder." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`O`", "Open a project." - ":kbd:`Ctrl`:kbd:`Shift`:kbd:`R`", "Close the document Viewer." + ":kbd:`Ctrl`:kbd:`Shift`:kbd:`R`", "Close the document viewer." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`S`", "Save the current project." ":kbd:`Ctrl`:kbd:`Shift`:kbd:`W`", "Close the current project." - ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Up`", "Move item one step up in the Project Tree." - ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Down`", "Move item one step down in the Project Tree." - ":kbd:`F1`", "Open the documentation. This just tries to send the documentation URL to your browser." - ":kbd:`F2`", "If in the Project Tree, edit a document or folder settings. (Same as :kbd:`Ctrl`:kbd:`E`)" + ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Up`", "Move item one step up in the project tree." + ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Down`", "Move item one step down in the project tree." + ":kbd:`F1`", "Open the documentation. This will either open the Qt Assistant, if available, or send you to the documentation website." + ":kbd:`F2`", "If in the project tree, edit a document or folder settings. (Same as :kbd:`Ctrl`:kbd:`E`)" ":kbd:`F3`", "Find next occurrence of search word in current document. (Same as :kbd:`Ctrl`:kbd:`G`)" - ":kbd:`F5`", "Open the Build Novel Project dialog." - ":kbd:`F6`", "Open the Writing Statistics dialog." + ":kbd:`F5`", "Open the :guilabel:`Build Novel Project` dialog." + ":kbd:`F6`", "Open the :guilabel:`Writing Statistics` dialog." ":kbd:`F7`", "Re-run spell checker." - ":kbd:`F8`", "Activate Focus Mode, hiding Project Tree and view panel." - ":kbd:`F9`", "Re-build Project Index." - ":kbd:`F10`", "Re-build Project Outline." + ":kbd:`F8`", "Activate :guilabel:`Focus Mode`, hiding the project tree and document viewer." + ":kbd:`F9`", "Re-build the project index." + ":kbd:`F10`", "Re-build the project outline." ":kbd:`F11`", "Activate full screen mode." ":kbd:`Shift`:kbd:`F3`", "Find previous occurrence of search word in current document. (Same as :kbd:`Ctrl`:kbd:`Shift`:kbd:`G`)" - ":kbd:`Enter`", "If in the Project Tree, open a document for editing." + ":kbd:`Enter`", "If in the project tree, open a document for editing." .. note:: On macOS, replace :kbd:`Ctrl` with :kbd:`Cmd`. diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 6613f1e2..5466bf28 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -6,17 +6,19 @@ Introduction novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply simple formatting. It is designed for writing novels, and allow for the component documents to be -ordered freely to create the desired structure of the novel project. +ordered freely to create the desired structure of the novel project. This is covered on the +:ref:`a_struct` page. In addition, the project can contain notes on the various plot elements, characters, locations, etc, that make up the story. These notes are organised in a set of category-specific folders, and each entry can be tagged and cross referenced from within the novel files and other notes. These tags make it possible to inter-link documents, and generate an overview of the entire novel project and -how the various files and plot elements are interconnected. +how the various files and plot elements are interconnected. This is covered on the :ref:`a_proj` and +:ref:`a_notes` pages. These additional features are not standard in markdown, but are available through special meta keywords. Syntax highlighting is provided to make it easier to verify that the markdown tags are -used correctly. +used correctly. This is covered on the :ref:`a_ui` page. .. _a_intro_design: @@ -32,22 +34,27 @@ at the same time provide a complete set of features needed for writing a novel. links, tables, and its formatting is limited to headers, and bold, italicised and strikethrough text. -The main window does not have a tool bar like most other applications do. This reduces clutter, and -since the documents are formatted with markdown tags, more or less redundant. However, all +The main window does not have a toolbar like most other applications do. This reduces clutter, and +since the documents are formatted with markdown tags, is more or less redundant. However, all formatting features supported are available through convenient keyboard shortcuts. They are also -available in the main menu. +available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts` +section. The colour scheme of the user interface defaults to that of the host operating system. In addition, -a dark theme is provided, and can be enabled in Preferences. A number of syntax highlighting themes -are also available in Preferences. Coloured and grayscale icon themes are also available. +a dark theme is provided, and can be enabled in :guilabel:`Preferences` from the :guilabel:`Tools` +menu. A number of syntax highlighting themes are also available in :guilabel:`Preferences`. A set of +icon themes in colour and greyscale is also offered. The icons are based on the Typicon_ icon set by +Stephen Hutchings. The main window is split in two, or optionally three, panels. The left-most contains the project tree and all the files in your project. The second panel is the document editor, and the optional third panel is a document viewer which can view any document in your project. -A second tab is also available on the main window. This is the Outline tab where the entire novel -structure can be displayed, with all the tags and references listed. Depending on how you structure -your novel project files, this outline can be quite different than your project tree. +A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the +entire novel structure can be displayed, with all the tags and references listed. Depending on how +you structure your novel project files, this outline can be quite different than your project tree. + +.. _Typicon: https://github.com/stephenhutchings/typicons.font .. _a_intro_project: @@ -56,18 +63,19 @@ Project Layout ============== You are free to structure your project files as you wish in subfolders and split between files. All -that matters to novelWriter is the linear order they appear in the project tree (top to bottom) and -the chapters, scenes and sections of the novel is determined by the headings within those files. +that matters to novelWriter is the linear order they appear in the project tree (top to bottom). The +chapters, scenes and sections of the novel are determined by the headings within those files. -The four heading levels (H1 to H4) are treated as follows: +The four heading levels (**H1** to **H4**) are treated as follows: -* H1 is used for the book title, and for partitions. -* H2 is used for chapter tiles. -* H3 is reserved for scene titles. -* H4 is for section titles within scenes, if such granularity is needed. +* **H1** is used for the book title, and for partitions. +* **H2** is used for chapter tiles. +* **H3** is reserved for scene titles. +* **H4** is for section titles within scenes, if such granularity is needed. -This structure is only considered on novel files. For the files designated as project notes, the -usage of headers imply no structural meaning, and the user is free to do whatever they want. +This header level structure is only considered on novel files. For the files designated as project +notes, the usage of headers imply no structural meaning, and the user is free to do whatever they +want. See the :ref:`a_struct` page for more details. .. _a_intro_export: @@ -84,8 +92,8 @@ HTML, which can be imported or converted by a number of other tools like Pandoc, into Libre Office and similar. It is also possible to 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. +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. See the :ref:`a_export` page for more details. .. _a_intro_screenshots: diff --git a/docs/source/notes.rst b/docs/source/notes.rst index 5947ea3f..6b3b68a4 100644 --- a/docs/source/notes.rst +++ b/docs/source/notes.rst @@ -1,3 +1,5 @@ +.. _a_notes: + ************************ Supporting Files (Notes) ************************ diff --git a/docs/source/projects.rst b/docs/source/projects.rst index 238f2ecd..fdfc3616 100644 --- a/docs/source/projects.rst +++ b/docs/source/projects.rst @@ -7,13 +7,12 @@ Novel Projects A novelWriter project requires a dedicated folder for storing its files on the local file system. See the :ref:`a_tech` page for further details. -A new project can be created from the :menuselection:`Project` menu by selecting -:menuselection:`New Project`. A list of recently opened projects is maintained, and displayed in the -Open Project dialog. A project can be removed from this list by selecting it and pressing the -:kbd:`Del` key. +A new project can be created from the :guilabel:`Project` menu by selecting :guilabel:`New Project`. +A list of recently opened projects is maintained, and displayed in the :guilabel:`Open Project` +dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key. -The project specific settings are available in :menuselection:`Project --> Project Settings`. See -further details below in the :ref:`a_proj_settings` section. +The project specific settings are available in :guilabel:`Project Settings` in the +:guilabel:`Project` menu. See further details below in the :ref:`a_proj_settings` section. .. _a_proj_roots: @@ -22,23 +21,26 @@ Project Roots ============= Projects are structured into a set of top level folders called *root folders*. They are visible in -the Project Tree. +the project tree at the left side of the main window. The core novel files go into a root folder of type "Novel". Other supporting files go into the other root folders. These other root folder types are intended for your notes on the various elements of -your story. Using these is of course entirely optional. A new project will not have all of the root -folders present, but you can add the ones you want from :menuselection:`Project --> Create Root Folder`. +your story. Using these is of course entirely optional. + +A new project will not have all of the root folders present, but you can add the ones you want from +:guilabel:`Create Root Folder` in the :guilabel:`Project` menu. The root folders are intended for the following use, but aside from the Novel folder, no restrictions are enforced by the application. You can use them however you want. .. note:: The root folders correspond to the categories of tags that can be used. - See the "Project Structure" section for further details. + See the :ref:`a_struct` page for further details. Novel - The root folder of all text that goes into the final novel. This class of files have other rules - and features than other files in the project. See the :ref:`a_struct` page for more details. + This is the root folder of all text that goes into the final novel. This class of files have + other rules and features than other files in the project. See the :ref:`a_struct` page for more + details. Plot This is the root folder where main plots can be outlined. It is optional, but adding at least @@ -76,8 +78,9 @@ Custom For more information about the tags listed, see :ref:`a_struct_tags`. .. note:: - Deleted files will be moved into a special "Trash" root folder. Files in the Trash folder can - then be deleted permanently, either individually, or by emptying the trash from the menu. + Deleted files will be moved into a special :guilabel`Trash` root folder. Files in the trash + folder can then be deleted permanently, either individually, or by emptying the trash from the + menu. .. _a_proj_roots_orph: @@ -86,14 +89,15 @@ Orphaned Documents ------------------ If novelWriter crashes or otherwise exits without saving the project state, or if you're using a -file synchronisation tool, there may be files in the project folder that isn't tracked in the core -project file. These files, when discovered, are handled by the Orphaned Documents routine. +file synchronisation tool that runs out of sync, there may be files in the project folder that isn't +tracked in the core project file. These files, when discovered, are handled by the Orphaned +Documents routine. -Files that are discovered will be re-added to the project tree in a special "Orphaned Items" root -folder next time the application is started. These orphaned files will not have most of the meta -data preserved, although novelWriter will try to restore the file label it had in the Project Tree. -Other information will have to be set again, and the files moved back to the correct location in -the project. +Files that are discovered in the project folder, but not in the project, will be re-added to the +project tree in a special :guilabel:`Orphaned Items` root folder next time the application is +started. These orphaned files will not have most of the meta data preserved, although novelWriter +will try to restore the file label it had in the project tree. Other information will have to be set +again, and the files moved back to the correct location in the project. .. _a_proj_roots_lock: @@ -108,7 +112,7 @@ where else novelWriter thinks the project is also open. You will be give the option to ignore this warning, and continue opening the project. However, if multiple instances are in fact editing the same project, you are likely to cause inconsistencies and -create diverging project files, potentially resulting in loss of data. +create diverging project files, potentially resulting in loss of data and orphaned files. .. note:: If, for some reason, novelWriter crashes, the lock file may remain even if there are no other @@ -122,47 +126,53 @@ Using Folders in the Project Tree --------------------------------- Folders, aside from root folders, have no structural significance to the project. When novelWriter -is processing the files in the novel, like for instance during export, the folders are ignored. Only -the order of the text files themselves matter. +is processing the files in the novel, like for instance during export, these folders are ignored. +Only the order of the text files themselves matter. The folders are there purely as a way for the user to organise the files in meaningful sections and to be able to close them in the Project Tree when you're not working on those files, and thus reduce clutter. +.. tip:: + You can use folders to sort your scene files into chapters. You will then need to add a chapter + file as the first file of your folder, and the scene files as the following files. + .. _a_proj_files: Project Files ============= -New document files can be created from the :menuselection:`Document` menu, or by pressing -:kbd:`Ctrl`:kbd:`N` while in the Project Tree. This will create a new, empty file, and open the Item -Settings dialog where the filename and various other settings can be changed. This dialog can also -be opened again later from either the menu, :menuselection:`Project -> Edit Item`, or by pressing -:kbd:`Ctrl`:kbd:`E` or :kbd:`F2` with the item selected. +New document files can be created from the :guilabel:`Document` menu, or by pressing +:kbd:`Ctrl`:kbd:`N` while in the Project Tree. This will create a new, empty file, and open the +:guilabel:`:Item Settings` dialog where the filename and various other settings can be changed. +This dialog can also be opened again later from either the :guilabel:`Project` menu, selecting +:guilabel:`Edit Item`, or by pressing :kbd:`Ctrl`:kbd:`E` or :kbd:`F2` with the item selected. The layout of the file is also defined here. For Novel files, the full list of layout options are available. For non-Novel files, only "Note" is available. See :ref:`a_struct_layout` for more details. You can also select whether the file is by default included when building the project. This setting -can be overridden in the Build Novel Project tool if you wish to include them anyway. +can be overridden in the :guilabel:`Build Novel Project` tool if you wish to include them anyway. +.. _a_proj_files_counts: + Word Counts ----------- A character, word and paragraph count is maintained for each file, as well as dor each section of a file defined by a header. The word count, and change of words in the current session, is displayed -in the footer of any document open in the Editor, and all stats are shown in the details panel below -the Project Tree for any file selected. +in the footer of any document open in the editor, and all stats are shown in the details panel below +the project tree for any file selected. -The word counts are not updated real time, but runs in the background every five seconds. +The word counts are not updated in real time, but runs in the background every five seconds. A total project word count is displayed in the status bar. The total count depends on the sum of the -values in the Project Tree, which again depend on an up to date index. If the counts seem wrong, a -full project word recount can be initiated by rebuilding the Project Index. Either form the -:menuselection:`Tools` menu, or by pressing :kbd:`F9`. +values in the project tree, which again depend on an up to date index. If the counts seem wrong, a +full project word recount can be initiated by rebuilding the project's index. Either form the +:guilabel:`Tools` menu, or by pressing :kbd:`F9`. .. _a_proj_settings: @@ -170,9 +180,8 @@ full project word recount can be initiated by rebuilding the Project Index. Eith Project Settings ================ -The project settings can be accessed from the :menuselection:`Project --> Project Settings` menu -entry, or by pressing :kbd:`Ctrl`:kbd:`Shift`:kbd:`,`. This will open a dialog box, with a set of -tabs. +The :guilabel:`Project Settings` can be accessed from the :guilabel:`Project` menu, or by pressing +:kbd:`Ctrl`:kbd:`Shift`:kbd:`,`. This will open a dialog box, with a set of tabs. Settings Tab @@ -198,36 +207,29 @@ project is saved, how may times it has been saved, how many folders and files it many words exist in the entire project. -Status Tab ----------- +Status and Importance Tabs +--------------------------- -Each file of type "Novel" can be given a status level, signified by a coloured icon. These are -purely there for the user's convenience, and you are not required to use them for any other feature -to work. The intention is to use this list to set what stage of writing you are on, although you can -in principle make them whatever you want. +Each file of type "Novel" can be given a status level, signified by a coloured icon and each file of +the remaining types can be given an importance level. These are colour coded icons and labels that +can be applied to each file. + +These are purely there for the user's convenience, and you are not required to use them for any +other feature to work. No other part of novelWriter accesses this information. The intention is to +use these to indicate at what stage of completeion each novel file is, or how important the content +of a note file is to the plot. You don't have to use them this way, that's just what they were +intended for, but you can make them whatever you want. .. note:: - The status levels currently in use by one or more files cannot be deleted. - - -Importance Tab --------------- - -Each file of types "Plot", "Character", "World", "Timeline", "Object", "Entity", or "Custom", can be -given an importance level, signified by a coloured icon like for status level. These are also purely -there for the user's convenience, and you are not required to use them for any other feature to -work. The intention is to use this list to set how important the character, plot element, or -otherwise, is for the story. Again, these can in principle be used for whatever you want. - -.. note:: - The importance levels currently in use by one or more files cannot be deleted. + The status or importance level currently in use by one or more files cannot be deleted, but they + can be edited. Auto-Replace Tab ---------------- A set of automatically replaced keywords can be added in this tab. The keywords in the left column -will be replaced by the text in the right column when documents are opened in the Viewer. They will +will be replaced by the text in the right column when documents are opened in the viewer. They will also be applied to exports. .. note:: @@ -246,12 +248,13 @@ backup files are to be stored must to be provided in Preferences. Backups can be run automatically when a project is closed, which also implies it is run when the application is closed. Backups are date stamped zip files of the entire project folder, and are -stored in a subfolder of the backup path with the same name as the project Working Title set in -:ref:`a_proj_settings`. +stored in a subfolder of the backup path with the same name as the project :guilabel:`Working Title` +set in :ref:`a_proj_settings`. -The backup feature, when configured, can also be run manually from the :menuselection:`Tools` menu. -It is also possible to dissable automated backup for a given project in Project Settings. +The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu. +It is also possible to dissable automated backup for a given project in :guilabel:`Project Settings`. .. note:: - For the backup to be able to run, the Working Title must be set in Project Settings. This value - is used to generate the folder name for the zip files. Without it, the backup will not run. + For the backup to be able to run, the :guilabel:`Working Title` must be set in :guilabel:`Project + Settings`. This value is used to generate the folder name for the zip files. Without it, the + backup will not run at all, but produce a warning message. diff --git a/docs/source/started.rst b/docs/source/started.rst index 6cb2f3e3..92a83d25 100644 --- a/docs/source/started.rst +++ b/docs/source/started.rst @@ -34,10 +34,10 @@ needed to communicate with the Qt GUI libraries, only one package is required fo format of the main project file. Everything else is handled with standard Python libraries. Optionally, a package can be installed to interface with the Enchant spell checking libaries, but -this isn't required. If no external spell checking library is available, novelWriter falls back to -using the internal ``difflib`` of Python to check spelling. This is a much slower approach, and it -is less sophisticated than full spell checking libaries, but if you only work with small files, the -performance loss is not noticeable. +this isn't strictly required. If no external spell checking library is available, novelWriter falls +back to using the internal ``difflib`` of Python to check spelling. This is a much slower approach, +and it is less sophisticated than full spell checking libaries, but if you only work with small +files, the performance loss is not noticeable. .. _a_started_depend_packages: @@ -53,7 +53,7 @@ the following command: pip install -r requirements.txt -On some operating systems you need to use ``python3`` instead of ``python``. +This will install all the dependencies and recommended packages. The following Python packages are required to run novelWriter: @@ -69,7 +69,7 @@ Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching u expressions requires 5.3, and for full Unicode support, 5.13. There are no known minimum for package ``lxml``, but the code was originally written with 4.2, -which is therefore set as the minimum. +which is therefore set as the minimum. It may work on lower versions. You have to test it. The spell checking extension is optional, but recommended: @@ -78,6 +78,7 @@ The spell checking extension is optional, but recommended: The optional spell check library must be at least 3.0.0 to work with Windows. On Linux, 2.0.0 also works fine. + .. _a_started_depend_docs: Building Documentation @@ -104,6 +105,16 @@ To build the help packages from the documentation source, run from the root source folder. +The setup script will copy the generated files into the ``nw/assets/help`` folder, and novelWriter +will detect the presence of the files and redirect the menu help entry to open help locally instead +of send the user to the website. + +.. note:: + In order for the local version of help to work, the Qt Assistant must be installed on the local + computer. If it isn't available, or novelWriter cannot find it, the help feature will fall back + to redirecting to the website. + + .. _a_started_running: Running novelWriter @@ -135,7 +146,7 @@ there's one script for Debian and one for Ubuntu. Building a Standalone Executable ================================ -A standalone executable can be built with pyinstaller, using the provided python script +A standalone executable can be built with ``pyinstaller``, using the provided python script ``install.py`` in the source folder. This script will automatically try to install all dependencies and build the standalone executable of novelWriter. You can run the script by typing the following into your command prompt: