From ccffa91c49fa89f74f78e572b6549edba64002a4 Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Sun, 15 Oct 2023 20:11:29 +0200 Subject: [PATCH] Make a second apss through the entire documentation to fix issues --- docs/source/index.rst | 6 +-- docs/source/int_customise.rst | 19 +++---- docs/source/int_howto.rst | 4 +- docs/source/int_introduction.rst | 32 +++++------ docs/source/int_overview.rst | 43 +++++++-------- docs/source/int_started.rst | 12 ++--- docs/source/project_manuscript.rst | 42 +++++++-------- docs/source/project_overview.rst | 75 +++++++++++++------------- docs/source/project_references.rst | 51 +++++++++--------- docs/source/project_structure.rst | 9 ++-- docs/source/tech_locations.rst | 16 +++--- docs/source/tech_source.rst | 26 ++++----- docs/source/tech_storage.rst | 18 +++---- docs/source/tech_tests.rst | 13 +++-- docs/source/usage_breakdown.rst | 82 ++++++++++++++++------------- docs/source/usage_format.rst | 19 ++++--- docs/source/usage_project.rst | 29 +++++----- docs/source/usage_projectformat.rst | 9 ++-- docs/source/usage_shortcuts.rst | 4 +- docs/source/usage_typography.rst | 6 +-- docs/source/usage_writing.rst | 32 +++++------ 21 files changed, 278 insertions(+), 269 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 3420ce57..1495d713 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,13 +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 as well. novelWriter can also be run directly from the Python source, or installed from packages or -from pip. See :ref:`a_started` for more details. +with pip. See :ref:`a_started` for more details. **Useful Links** diff --git a/docs/source/int_customise.rst b/docs/source/int_customise.rst index c151322c..9098db7d 100644 --- a/docs/source/int_customise.rst +++ b/docs/source/int_customise.rst @@ -17,7 +17,7 @@ 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 automatically. +may not load all installed spell check dictionaries automatically. Linux and MacOS --------------- @@ -40,7 +40,6 @@ This assumes your user profile is stored at ``C:\Users\``. 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,9 +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 altough 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. +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. @@ -81,15 +80,14 @@ set as ``name`` inside the file. .. 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 + 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 @@ -138,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 @@ -168,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_howto.rst b/docs/source/int_howto.rst index b0be358d..95a83876 100644 --- a/docs/source/int_howto.rst +++ b/docs/source/int_howto.rst @@ -25,7 +25,7 @@ Managing the Project :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. + can also rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details. Layout Tricks @@ -68,7 +68,7 @@ Organising Your Text 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. + paragraph in their place. See :ref:`a_manuscript_settings` for more details. Other Tools diff --git a/docs/source/int_introduction.rst b/docs/source/int_introduction.rst index b595d296..d4c99188 100644 --- a/docs/source/int_introduction.rst +++ b/docs/source/int_introduction.rst @@ -7,10 +7,10 @@ Key Features .. _Snowflake: https://www.advancedfictionwriting.com/articles/snowflake-method/ .. _Markdown: https://en.wikipedia.org/wiki/Markdown -At the core, novelWriter is a multi-document plain text editor. It uses a markup syntax inspired by +At its core, novelWriter is a multi-document plain text editor. It uses a markup syntax inspired by Markdown_ to apply simple formatting to the text. It is designed for writing fiction, so the -formatting features are limited to those relevant for this purpose. It is not suitable for -technical writing, and it is *not* a full feature Markdown editor. +formatting features available are limited to those relevant for this purpose. It is *not* suitable +for technical writing, and it is *not* a full-feature Markdown editor. Your novel project is organised as a collection of separate plain text documents instead of a single, large document. The idea here is to make it easier to reorganise your project structure @@ -22,8 +22,8 @@ your notes about your characters, your world building, and so on. You can at any point split the individual documents by their headers up into multiple documents, or merge multiple documents into single documents. This makes it easier to use variations of the -popular Snowflake_ method for writing. You can focus on writing larger structure-focused documents, -like one per act for instance, and later effortlessly split these up into scenes by their headers. +Snowflake_ method for writing. You can focus on writing larger structure-focused documents, like +one per act for instance, and later effortlessly split these up into scenes by their headers. Below are some key features of novelWriter. @@ -42,11 +42,11 @@ Below are some key features of novelWriter. **Organise your documents how you like** You can split your novel project up into as many individual documents as you want to. When you - build the project, they are all glued together in the top-to-bottom order in which they appear - in the project tree. You can use as few text documents as you like, but splitting the project up - into chapters and scenes means you can easily reorder them using the drag and drop feature. You - can start out with a few documents and then later split them into multiple documents based on - their headers. + build the project into a manuscript, they are all glued together in the top-to-bottom order in + which they appear in the project tree. You can use as few text documents as you like, but + splitting the project up into chapters and scenes means you can easily reorder them using the + drag-and-drop feature. You can also start out with a few documents and then later split them + into multiple documents based on their headers. **Multi-novel project support** As of novelWriter 2.0, you can have multiple Novel type root folders in a project. This allows @@ -56,22 +56,22 @@ Below are some key features of novelWriter. **Keep track of your plot elements** All notes in your project can be assigned a :term:`tag` that you can :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. + to be able to reference specific sections of ot. **Get an overview of your plot elements** In the :guilabel:`Outline View` on the main window you can see an outline of all the chapters, scenes, and sections of your project. If they have any references in them, these are listed in - additional columns. You can also add a synopsis to each document, 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 information is also available in the :guilabel:`Novel View` as an alternative view - to the project tree. + 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 information is also available in the :guilabel:`Novel View` as an + alternative view to the project tree. **Building your manuscript** Whether you want to assemble a manuscript, or export all your notes, or generate an outline of your chapters and scenes with a synopsis, you can use the :guilabel:`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 + 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. diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst index b2d3a587..09d8358f 100644 --- a/docs/source/int_overview.rst +++ b/docs/source/int_overview.rst @@ -14,12 +14,13 @@ novelWriter is built as a cross-platform application using `Python 3 `_ for the user interface. novelWriter is built for Linux first, and this is where it works best. However, it also runs fine -on Windows and MacOS due to being built with cross-platform tools. The author of the application -doesn't own a Mac, so on-going Mac support is dependant on user feedback and user contributions. +on Windows and MacOS due to the cross-platform framework it's build on. The author of the +application doesn't own a Mac, so on-going Mac support is dependant on user feedback and user +contributions. Spell checking in novelWriter is provided by a third party library called `Enchant `_. Please see the section on :ref:`a_custom_dict` for -how to handle spell checking in different languages. +how to install spell checking languages. For install instructions, see :ref:`a_started`. @@ -28,40 +29,40 @@ Using novelWriter ================= In order to use novelWriter effectively, you need to know the basics of how it works. The following -sections will explain the main principles. It starts with the basics, and gets more detailed as you +chapters will explain the main principles. It starts with the basics, and gets more detailed as you read on. :ref:`a_breakdown` – Essential Information - This section explains the basics of how the application works and what it can and cannot do. + This chapter explains the basics of how the application works and what it can and cannot do. :ref:`a_ui_project` – Recommended Reading - This section will give you a more detailed explanation of how you the user interface components + This chapter 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. + This chapter 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 + This chapter covers how you should format your text. The editor is plain text, so text formatting requires some basic markup. The structure of your novel is also inferred by how you use headings. Tags and references are implemented by special keywords. :ref:`a_kb` – Optional / Lookup - This section lists all the keyboard shortcuts in novelWriter and what they do. Most of the - shortcuts are also listed next to the menu items inside the app, or in tool tips, so this - section is mostly for reference. + This chapter lists all the keyboard shortcuts in novelWriter and what they do. Most of the + shortcuts are also listed next to their menu entries inside the app, or in tool tips. This + chapter is mostly for reference. :ref:`a_typ` – Optional - This section gives you an overview of the special typographical symbols available in + This chapter gives you an overview of the special typographical symbols available in novelWriter. The auto-replace feature can handle the insertion of standard quote symbols for your language, and other special characters. If you use any symbols aside from these. their intended use is explained here. :ref:`a_prjfmt` – Optional - This section is more technical and has an overview of changes made to the way your project data + This chapter is more technical and has an overview of changes made to the way your project data is stored. The format has changed a bit from time to time, and sometimes the changes require that you make small modifications to your project. Everything you need to know is listed in this - section. + chapter. Organising Your Projects @@ -73,19 +74,19 @@ to take advantage of these features, you must structure your text in a specific meta data for it to extract. :ref:`a_proj` – Essential Information - This section explains how you organise the content of your project, and how to set up automated + This chapter explains how you organise the content of your project, and how to set up automated backups of your work. :ref:`a_struct` – Essential Information - This section covers the way your novel's structure is encoded into the text documents. It - explains how the different levels of headings are used, and how you can include information - about characters, plot elements, and other meta data in your text. + This chapter covers the way your novel's structure is encoded into the text documents. It + explains how the different levels of headings are used, and some special formatting for + different kinds of headings. :ref:`a_references` - Recommended Reading - This section explains how you organise your notes, and how the Tags and References system works. + This chapter explains how you organise your notes, and how the Tags and References system works. This system lets you cross-link your documents in your project, and display these references in the application interface. :ref:`a_manuscript` - Recommended Reading - This section explains in more detail how the Manuscript Build tool works, how you can control - the way chapter titles are formatted, and how scene and section breaks are handled. + This chapter explains how the :guilabel:`Manuscript Build` tool works, how you can control the + way chapter titles are formatted, and how scene and section breaks are handled. diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index 1d00aab7..402ec687 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -14,8 +14,8 @@ Getting Started .. _Releases: https://github.com/vkbo/novelWriter/releases .. _AppImage: https://appimage.org/ -Package installers are available for all major platforms, including Linux, Windows and MacOS. See -below for install instructions for each platform. +Package installers for novelWriter are available for all major platforms, including Linux, Windows +and MacOS. See below for install instructions for each platform. You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`. Installing from PyPi does not set up icon launchers, so you will either have to do this yourself, @@ -37,7 +37,7 @@ Installing it should be straightforward. If you have any issues, try uninstalling the previous version and making a fresh install. If you already had a version installed via a different method, you should uninstall that first as having -multiple installations has been known to cause issues. +multiple installations has been known to cause problems. .. note:: The novelWriter installer is not signed because Microsoft doesn't currently provide a way for @@ -112,9 +112,9 @@ completely standalone images for the app that include the necessary environment They can of course be run on any Linux distro, if you prefer this to native packages. .. note:: - - novelWriter generally stops supporting Python versions that have reached end of life. If your - Linux distro still uses older Python versions, you may want to try the AppImage instead. + novelWriter generally don't support Python versions that have reached end of life. If your Linux + distro still uses older Python versions and novelWriter won't run, you may want to try the + AppImage instead. .. _a_started_macos: diff --git a/docs/source/project_manuscript.rst b/docs/source/project_manuscript.rst index e01e5d01..0818e864 100644 --- a/docs/source/project_manuscript.rst +++ b/docs/source/project_manuscript.rst @@ -10,7 +10,7 @@ You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing .. versionadded:: 2.1 This tool is new for version 2.1. A simpler tool was used for earlier versions. The simpler tool - only allows you to define a single set of options for one build, but otherwise has much the same + only allows you to define a single set of options for the build, but otherwise has much the same functionality. @@ -52,7 +52,7 @@ Document Selection The :guilabel:`Selections` page of the :guilabel:`Manuscript Build Settings` dialog allows you to fine tune which documents are included in the build. They are indicated by a green arrow icon in -the last column. On the right, you have some filter options for selecting content of a specific +the last column. On the right you have some filter options for selecting content of a specific type, and a set of switches for which root folders to include. You can override the result of these filters by marking one or more documents and selecting to @@ -71,14 +71,14 @@ Formatting Headings The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog. The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog allows you to set -how the headings in your :term:`Novel Documents` as formatted. By default, the title is just copied -as-is, indicated by the ``{Title}`` format. You can change this to for instance add chapter +how the headings in your :term:`Novel Documents` are formatted. By default, the title is just +copied as-is, indicated by the ``{Title}`` format. You can change this to for instance add chapter numbers and scene numbers like shown int he figure above. -Clicking the edit button will copy the formatting string into the edit box, where a syntax -highlighter will help indicate which parts are automatically generated by the build tool. The -:guilabel:`Insert` button is a dropdown list of these formats, and selecting one will insert it at -the position of the cursor. +Clicking the edit button next to a format will copy the formatting string into the edit box where +it can be modified, and where a syntax highlighter will help indicate which parts are automatically +generated by the build tool. The :guilabel:`Insert` button is a dropdown list of these formats, and +selecting one will insert it at the position of the cursor. Any text you add that isn't highlighted in colours will remain in your formatted titles. ``{Title}`` will always be replaced by the text in the heading from your documents. @@ -92,11 +92,11 @@ Scene Separators If you don't want any titles for your scenes (or for your sections if you have them), you can leave the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or sections instead, resulting in a gap in the text. You can also switch on the :guilabel:`Hide` -setting, which will ignore them completely. That is, there won't even be an extra gap insetred. +setting, which will ignore them completely. That is, there won't even be an extra gap inserted. Alternatively, if you want a separator text between them, like the common ``* * *``, you can enter -the desired separator text in the formatting box. In fact, if the format is any piece of static -text, it will always be treated as a separator. +the desired separator text as the format. If the format is any piece of static text, it will always +be treated as a separator. Output Settings @@ -115,15 +115,15 @@ Building Manuscript Documents .. figure:: images/fig_build_build.png - The :guilabel:`Manuscript Build` dialog sued for writing the actual manuscript documents. + The :guilabel:`Manuscript Build` dialog used for writing the actual manuscript documents. When you press the :guilabel:`Build` button on the :guilabel:`Build Manuscript` tool main window, a special file dialog opens up. This is where you pick your desired output format and where to write the file. -On the left is a list of all the available file formats, and on the right, a list of what documents -are included based on the build definition you selected. You can choose an output path, and set a -base file name as well. The file extension will be added automatically. +On the left side of the dialog is a list of all the available file formats, and on the right, a +list of the documents which are included based on the build definition you selected. You can choose +an output path, and set a base file name as well. The file extension will be added automatically. To generate the manuscript document, press the :guilabel:`Build` button. A small progress bar will show the build progress, but for small projects it may pass very fast. @@ -137,7 +137,7 @@ Currently, four document formats are supported. Open Document Format The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a flat version of the document format as a single XML file. Most rich text editors support the - former, and a few the latter. + former, and only a few the latter. novelWriter HTML The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document @@ -145,10 +145,10 @@ novelWriter HTML word processors, or for printing from browser. novelWriter Markup - This is simply a concatenation of the project documents selected by the filters. The documents - are stacked together in the order they appear in the project tree, with comments, tags, etc. - included if they are selected. This is a useful format for exporting the project for later - import back into novelWriter. + This is simply a concatenation of the project documents selected by the filters into a ``.txt`` + file. The documents are stacked together in the order they appear in the project tree, with + comments, tags, etc. included if they are selected. This is a useful format for exporting the + project for later import back into novelWriter. Standard/Extended Markdown The Markdown format comes in both Standard and Extended flavour. The *only* difference in terms @@ -161,7 +161,7 @@ Additional Formats In addition to the above document formats, the novelWriter HTML and Markup formats can also be wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also -the accompanying css styles are included. +the accompanying CSS styles used by the preview are included. The text body is saved in a two-level list. The outer list contains one entry per document, in the order they appear in the project tree. Each document is then split up into a list as well, with one diff --git a/docs/source/project_overview.rst b/docs/source/project_overview.rst index e18f2b93..54467990 100644 --- a/docs/source/project_overview.rst +++ b/docs/source/project_overview.rst @@ -9,7 +9,7 @@ This will open the :guilabel:`New Project Wizard` that will assist you in creati project suited to your needs. A novelWriter project requires a dedicated folder for storing its files on the local file system. -See :ref:`a_storage` for further details on how files are organised. +If you're interested in the details, you can have a look at the chapter :ref:`a_storage`. 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 or @@ -36,17 +36,14 @@ various elements of your story. Using them is of course entirely optional. A new project may not have all of the root folders present, but you can add the ones you want from the project tree tool bar. -Each root folder has one or more reference keyword associated with it that is used to reference -them from other documents and notes. The intended usage of each type of root folder is listed -below. However, aside from the :guilabel:`Novel` folder, no restrictions are applied by the +Each root folder has one or more :term:`reference` :term:`keyword` associated with it that is used +to reference them from other documents and notes. The intended usage of each type of root folder is +listed below. However, aside from the :guilabel:`Novel` folder, no restrictions are applied by the application on what you put in them. You can use them however you want. The root folder system is closesly connected to how the Tags and References system works. For more details, see the :ref:`a_references` chapter. -.. tip:: - You can make multiple root folders of each kind if you wish to split up your notes. - :guilabel:`Novel` This is the root folder type for text that goes into the final novel or novels. This class of documents have other rules and features than the project notes. See :ref:`a_struct` for more @@ -54,8 +51,8 @@ details, see the :ref:`a_references` chapter. :guilabel:`Plot` This is the root folder type where main plots can be outlined. It is optional, but adding at - least brief notes can be useful in order to tag plot elements for the Outline View. Tags in this - folder can be references using the ``@plot`` keyword. + least brief notes can be useful in order to tag plot elements for the :guilabel:`Outline View`. + Tags in this folder can be references using the ``@plot`` keyword. :guilabel:`Characters` Character notes go in this root folder type. These are especially important if you want to use @@ -63,7 +60,7 @@ details, see the :ref:`a_references` chapter. told from a specific character's point-of-view, or focusing on a particular character's storyline. Tags in this type of folder can be referenced using the ``@pov`` keyword for point-of-view characters, ``@focus`` for a focus character, or the ``@char`` keyword for any - other character. + other character present. :guilabel:`Locations` The locations folder type is for various scene locations that you want to track. Tags in this @@ -94,6 +91,9 @@ information about the tags listed, see :ref:`a_references_references`. You can rename root folders to whatever you want. However, this doesn't change the reference keyword or what they do. +.. versionadded:: 2.0 + As of version 2.0, you can make multiple root folders of each kind to split up your project. + .. _a_proj_roots_del: @@ -102,7 +102,7 @@ Deleted Documents Deleted documents will be moved into a special :guilabel:`Trash` root folder. Documents in the trash folder can then be deleted permanently, either individually, or by emptying the trash from -the menu. Documents in the trash folder are removed from the project index and cannot be +the menu. Documents in the trash folder are removed from the :term:`project index` and cannot be referenced. A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing @@ -115,12 +115,12 @@ Archived Documents ------------------ If you don't want to delete a document, or put it in the :guilabel:`Trash` folder where it may be -deleted, but still want it out of your main project tree, you can create an :guilabel:`Archive` -root folder and move it there. +deleted accidentally, but still want it out of your main project tree, you can create an +:guilabel:`Archive` root folder and move it there. You can drag any document to this folder and preserve its settings. The document will always be -excluded from the :guilabel:`Build Manuscript` tool. It is also removed from the project index, so -the tags and references defined in it will not show up anywhere else. +excluded from the :guilabel:`Build Manuscript` tool. It is also removed from the +:term:`project index`, so the tags and references defined in it will not show up anywhere else. .. _a_proj_roots_orphaned: @@ -131,19 +131,19 @@ Recovered Documents If novelWriter crashes or otherwise exits without saving the project state, or if you're using a file synchronisation tool that runs out of sync, there may be files in the project folder that aren't tracked in the core project file. These files, when discovered, are recovered and added back -into the project, if possible. +into the project. -The discovered files are scanned for meta information that give clues as to where the document may -previously have been located in the project. The project loading routines will try to put them back +The discovered files are scanned for metadata that give clues as to where the document may +previously have been located in the project. The project loading routine will try to put them back as close as possible to this location, if it still exists. Generally, it will be appended to the end of the folder where it previously was located. If that folder doesn't exist, it will try to add -it to the correct root folder. If it cannot figure out which root folder is correct, the document -will be added to the :guilabel:`Novel` root folder. Finally, if the :guilabel:`Novel` folder is -missing, one will be created. +it to the correct root folder type. If it cannot figure out which root folder is correct, the +document will be added to the :guilabel:`Novel` root folder. Finally, if the :guilabel:`Novel` +folder is missing, one will be created. -If the title of the document can be recovered, the word "Recovered:" will be added as a prefix. If -the title cannot be determined, the document will be named after its internal key, which is a -string of characters and numbers. +If the title of the document can be recovered, the word "Recovered:" will be added as a prefix to +indicate that it may need further attention. If the title cannot be determined, the document will +be named after its internal key, which is a string of characters and numbers. .. _a_proj_roots_lock: @@ -176,7 +176,7 @@ Using Folders in the Project Tree --------------------------------- Folders, aside from root folders, have no structural significance to the project. When novelWriter -is processing the documents in the novel, like for instance when you create a manuscript from it, +is processing the documents in a project, like for instance when you create a manuscript from it, these folders are ignored. Only the order of the documents themselves matter. The folders are there purely as a way for you to organise the documents in meaningful sections and @@ -197,14 +197,15 @@ Project Documents New documents can be created from the toolbar in the :guilabel:`Project Tree`, or by pressing :kbd:`Ctrl+N`. This will open the create new item menu and let you choose between a number of -pre-defined documents and folders. You will be prompted for a label for the new item. You can -always rename an item by selecting :guilabel:`Rename Item` from the :guilabel:`Project` menu, or by -pressing :kbd:`F2`. +pre-defined documents and folders. You will be prompted for a label for the new item. + +You can always rename an item by selecting :guilabel:`Rename Item` from the :guilabel:`Project` +menu, or by pressing :kbd:`F2`. Other settings for project items are available from the context menu that you can activate by -right-clicking on an item in the :guilabel:`Project Tree`. The :guilabel:`Transform` submenu -includes options for converting, splitting, or merging items. See :ref:`a_ui_tree_split_merge` for -more details on the latter two. +right-clicking on an item in the tree. The :guilabel:`Transform` submenu includes options for +converting, splitting, or merging items. See :ref:`a_ui_tree_split_merge` for more details on the +latter two. .. _a_proj_files_counts: @@ -222,9 +223,9 @@ The word counts are not updated in real time, but run in the background every fe long as the document is being actively edited. 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's index. Either from -the :guilabel:`Tools` menu, or by pressing :kbd:`F9`. +the values in the project tree, which again depend on an up to date :term:`project index`. If the +counts seem wrong, a full project word recount can be initiated by rebuilding the project's index. +Either from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`. .. _a_proj_settings: @@ -250,9 +251,9 @@ backup files may change too. The :guilabel:`Novel Title` and :guilabel:`Authors` settings are used when building the manuscript, for some formats. -If your project is in a different language than your main spell checking is set to, you can -override the default spell checking language here. You can also override the automatic backup -setting. The project language can also be changed from the :guilabel:`Tools` menu. +If your project is in a different language than your main spell checking language is set to, you +can override the default setting here. You can also override the automatic backup setting. The +project language can also be changed from the :guilabel:`Tools` menu. Status and Importance Tabs diff --git a/docs/source/project_references.rst b/docs/source/project_references.rst index b1898d20..5a5ef85e 100644 --- a/docs/source/project_references.rst +++ b/docs/source/project_references.rst @@ -5,14 +5,14 @@ Tags and References ******************* In novelWriter there are no forms or tables to fill in to define the characters, locations and -other elements of your story. Instead, you can mark your :term:`Project Notes` as representing -these story elements by creating a :term:`tag`. Whenever you want to link a piece of yur story to +other elements of your story. Instead, you can mark your :term:`project notes` as representing +these story elements by creating a :term:`tag`. Whenever you want to link a piece of your story to a note defining a story element, like a character, you create a :term:`reference` back to that tag. -You can also cross-link your Project Notes in the same way. +You can also cross-link your project notes in the same way. -This is perhaps one of the features that makes novelWriter quite different than other, similar +This is perhaps one of the features that makes novelWriter different from other, similar applications. It is therefore not always obvious to new users how this is supposed to work, so -this chapter hopes to explains in more detail how these tags and references system works. +this chapter hopes to explains in more detail how to use the tags and references system. .. tip:: If you find the Tags and Reference system difficult to follow just from reading this chapter, @@ -30,11 +30,11 @@ The structure of your novelWriter project is inferred from the :term:`headings` documents, not the documents themselves. See :ref:`a_struct_heads` for more details. Therefore, metadata is also associated with headings, and not documents. -If you split your project into separate documents for each scene, this may not matter. However, -there are several benefits to using documents at a larger structural scale when starting your -project. For instance, it may make more sense to define all your scenes, and even chapters, in a -single document at first, or perhaps a document per act. You can later split these documents up -using the split feature. See :ref:`a_ui_tree_split_merge` for more details on this feature. +If you split your project into separate documents for each scene, this distinction may not matter. +However, there are several benefits to using documents at a larger structural scale when starting +your project. For instance, it may make more sense to define all your scenes, and even chapters, in +a single document at first, or perhaps a document per act. You can later split these documents up +using the document split feature. See :ref:`a_ui_tree_split_merge` for more details. The implication here is that you can treat each heading as an independent element of your notes that can be referenced somewhere else. In order to make it possible to reference a header section, @@ -53,23 +53,23 @@ has to be unique across all documents in the project. .. note:: In version 2.2, tags will be made case insensitive, but as of novelWriter 2.1 they are not. You - should avoid using tags that are only distinquished by case. + should however avoid using tags that are only distinguished by case. -Tags can then be referenced in the novel documents, or cross-referenced in other notes, and will -show up in the :guilabel:`Outline View` and in the back-reference panel when a document is opened -in the viewer. +After the tags have been defined, they can then be referenced in the novel documents, or +cross-referenced in other notes. they will also show up in the :guilabel:`Outline View` and in the +back-reference panel when a document is opened in the viewer. -The syntax highlighter will alert you that the keyword is correctly used and that the tag is +The syntax highlighter will indicate to you that the keyword is correctly used and that the tag is allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up to date. An invalid tag should have a green wiggly line under it, and will not receive the syntax colour that valid tags do. -The tag is the only part of these notes that the application uses. The rest of the document content +The tag is the only part of these notes that the novelWriter uses. The rest of the document content is there for the writer to use in whatever way they wish. Of course, the content of the documents can be added to the manuscript, or an outline document. If you want to compile a single document of all your notes, you can do this from the :guilabel:`Manuscript Build` tool. -Example: +Example of a heading with a tag for a character of the story: .. code-block:: none @@ -81,10 +81,11 @@ Example: When this is done in a document in a :term:`Root Folder` of type "Characters", the tag is automatically treated as an available character in your project, and you will be able to reference -it in any of your other documents. +it in any of your other documents using the reference keywords for characters. It is the root folder type that defines what category of story elements the tag is indexed under. -See the :ref:`a_proj_roots` section for an overview of availabe root folder types. +See the :ref:`a_proj_roots` section for an overview of availabe root folder types. They are also +covered in the next section. .. _a_references_references: @@ -98,7 +99,7 @@ other things. References are set as a :term:`keyword` and a list of corresponding tags. The valid keywords are listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All -keywords allow multiple values. +reference keywords allow multiple values. ``@pov`` The point-of-view character for the current section. The target must be a note tag in a @@ -141,9 +142,11 @@ keywords allow multiple values. The syntax highlighter will alert the user that the tags and references are used correctly, and that the tags referenced exist. -The highlighter may be mistaken if the index of defined tags is out of date. If so, press :kbd:`F9` -to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general, -the index for a document is regenerated when it is saved, so this shouldn't normally be necessary. +.. note:: + The highlighter may be mistaken if the index of defined tags is out of date. If so, press + :kbd:`F9` to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. + In general, the index for a document is regenerated when it is saved, so this shouldn't normally + be necessary. One note can also reference another note in the same way novel documents do. When the note is opened in the document viewer, the references become clickable links, making it easier to follow @@ -157,7 +160,7 @@ highlight that two notes are related. .. tip:: If you cross-reference between notes and export your project as an HTML document using the :guilabel:`Manuscript Build` tool, the cross-references become clickable links in the exported - HTML document. + HTML document as well. Example of a novel document with references to characters and plots: diff --git a/docs/source/project_structure.rst b/docs/source/project_structure.rst index 117cfdfb..7787d784 100644 --- a/docs/source/project_structure.rst +++ b/docs/source/project_structure.rst @@ -8,8 +8,7 @@ This chapter covers the structure of a novel project. There are two different types of documents in a project, :guilabel:`Novel Documents` and :guilabel:`Project Notes`. Novel documents can only live in a :guilabel:`Novel` type root folder. -You can also move them to :guilabel:`Archive` and :guilabel:`Trash` of course. This chapter covers -the former type. +You can also move them to :guilabel:`Archive` and :guilabel:`Trash` of course. The :guilabel:`Project Tree` can distinguish between the different header levels of the novel documents using coloured icons, and optionally add emphasis on the label, set in @@ -22,16 +21,16 @@ Importance of Headings ====================== Subfolders under root folders have no impact on the structure of the novel itself. The structure is -instead dictated by the heading level of the headers within the documents. +instead dictated by the heading level of the headings within the documents. Four levels of headings are supported, signified by the number of hashes (``#``) preceding the -title. See also the :ref:`a_fmt` section for more details about the markdown syntax. +title. See also the :ref:`a_fmt` section for more details about the markup syntax. .. note:: The header levels are not only important when generating the manuscript, they are also used by the indexer when building the outline tree in the :guilabel:`Outline View` as well as in the :guilabel:`Novel Tree`. Each heading also starts a new region where new Tags and References - can be defined. See :ref:`a_references`. + can be defined. See :ref:`a_references` for more details. The syntax for the four basic header types, and the two special header types, is listed in section :ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows: diff --git a/docs/source/tech_locations.rst b/docs/source/tech_locations.rst index ad0aa5df..da199292 100644 --- a/docs/source/tech_locations.rst +++ b/docs/source/tech_locations.rst @@ -7,7 +7,7 @@ File Locations .. _QStandardPaths: https://doc.qt.io/qt-5/qstandardpaths.html novelWriter will create a few files on your system outside of the application folder itself. These -file locations are described in this document. +file locations are described in this chapter. .. _a_locations_conf: @@ -17,15 +17,16 @@ Configuration The general configuration of novelWriter, including everything that is in :guilabel:`Preferences`, is saved in one central configuration file. The location of this file depends on your operating -system. The system paths are provided by the Qt QStandardPaths_ class and its ConfigLocation value. +system. The system paths are provided by the Qt QStandardPaths_ class and its ``ConfigLocation`` +value. The standard paths are: * Linux: ``~/.config/novelwriter/novelwriter.conf`` -* macOS: ``~/Library/Preferences/novelwriter/novelwriter.conf`` +* MacOS: ``~/Library/Preferences/novelwriter/novelwriter.conf`` * Windows: ``C:\Users\\AppData\Local\novelwriter\novelwriter.conf`` -Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ```` is the +Here, ``~`` corresponds to the user's home directory on Linux and MacOS, and ```` is the user's username on Windows. .. note:: @@ -40,15 +41,16 @@ Application Data novelWriter also stores a bit of data that is generated by the user's actions. This includes the list of recent projects form the :guilabel:`Open Project` dialog. Custom themes should also be -saved here. The system paths are provided by the Qt QStandardPaths_ class and its AppDataLocation. +saved here. The system paths are provided by the Qt QStandardPaths_ class and its +``AppDataLocation`` value. The standard paths are: * Linux: ``~/.local/share/novelwriter/`` -* macOS: ``~/Library/Application Support/novelwriter/`` +* MacOS: ``~/Library/Application Support/novelwriter/`` * Windows: ``C:\Users\\AppData\Roaming\novelwriter\`` -Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ```` is the +Here, ``~`` corresponds to the user's home directory on Linux and MacOS, and ```` is the user's username on Windows. .. note:: diff --git a/docs/source/tech_source.rst b/docs/source/tech_source.rst index 29fc2907..8c23463e 100644 --- a/docs/source/tech_source.rst +++ b/docs/source/tech_source.rst @@ -8,7 +8,7 @@ Running from Source .. _PyPi: https://pypi.org/project/novelWriter/ .. _Sphinx Docs: https://www.sphinx-doc.org/ -This section describes various ways of running novelWriter directly from the source code, and how +This chapter describes various ways of running novelWriter directly from the source code, and how to build the various components like the translation files and documentation. .. note:: @@ -30,11 +30,11 @@ by running: Dependencies ============ -novelWriter has been designed to rely on as few dependencies as possible. Aside from the packages -needed to communicate with the Qt GUI libraries, only one package is required for handling the XML -format of the main project file. Everything else is handled with standard Python libraries. +novelWriter has been designed to rely on as few dependencies as possible. Only the Python wrapper +for the Qt GUI libraries is required. The package for spell checking is optional, but recommended. +Everything else is handled with standard Python libraries. -The following Python packages are needed to run novelWriter: +The following Python packages are needed to run all features of novelWriter: * ``PyQt5`` – needed for connecting with the Qt5 libraries. * ``PyEnchant`` – needed for spell checking (optional). @@ -53,7 +53,6 @@ source, dependencies can still be installed from PyPi with: pip install -r requirements.txt .. note:: - On Linux distros, the Qt library is usually split up into multiple packages. In some cases, secondary dependencies may not be installed automatically. For novelWriter, the library files for renderring the SVG icons may be left out and needs to be installed manually. This is the @@ -70,7 +69,7 @@ build the package using the Python Packaging Authority's build tool. It can be i .. code-block:: bash - pip install --upgrade build + pip install build On Debian-based systems the tool can also be installed with: @@ -82,11 +81,11 @@ With the tool installed, run the following command from the root of the novelWri .. code-block:: bash - python -m build + python -m build --wheel -This should generate two files in the ``dist/`` folder at your current location. One with file -extension ``.tar.gz`` and one with extension ``.whl``. The latter is the package you want to -install, here with example version number 2.0.7, but yours may be different: +This should generate a ``.whl`` file in the ``dist/`` folder at your current location. The wheel +file can then be installed on your system. Here with example version number 2.0.7, but yours may be +different: .. code-block:: bash @@ -124,7 +123,8 @@ Building the Example Project ============================ In order to be able to create new projects from example files, you need a ``sample.zip`` file in -the ``assets`` folder of the source. This file can be built from setup script by running: +the ``assets`` folder of the source. This file can be built from the ``pkgutils.py`` script by +running: .. code-block:: bash @@ -152,7 +152,7 @@ The documentation can then be built from the root folder in the source code by r If successful, the documentation should be available in the ``docs/build/html`` folder and you can open the ``index.html`` file in your browser. -You can also build a PDF manual from the documentation using the setup script: +You can also build a PDF manual from the documentation using the ``pkgutils.py`` script: .. code-block:: bash diff --git a/docs/source/tech_storage.rst b/docs/source/tech_storage.rst index 776eef6a..66a8b12d 100644 --- a/docs/source/tech_storage.rst +++ b/docs/source/tech_storage.rst @@ -6,27 +6,27 @@ How Data is Stored .. _documentation: https://docs.novelwriter.io/ -This section contains details of how novelWriter stores and handles the project data. +This chapter contains details of how novelWriter stores and handles the project data. Project Structure ================= All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix -line endings to Windows line endings on Windows systems, and vice versa, novelWriter does not make -any adaptations to the formatting on Windows systems. This is handled entirely by the Python -standard library. Python also handles this when working on the same files on both Windows and -Unix-based operating systems. +line endings to Windows line endings on Windows systems, novelWriter does not make any adaptations +to the formatting on Windows systems. This is handled entirely by the Python standard library. +Python also handles this when working on the same files on both Windows and Unix-based operating +systems. Main Project File ----------------- The project itself requires a dedicated folder for storing its files, where novelWriter will create -its own "file system" where the folder and file hierarchy is described in a project XML file. This -is the main project file in the project's root folder with the name ``nwProject.nwx``. This file -also contains all the meta data required for the project (except the index data), and a number of -related project settings. +its own "file system" where the project's folder and file hierarchy is described in a project XML +file. This is the main project file in the project's root folder with the name ``nwProject.nwx``. +This file also contains all the meta data required for the project (except the index data), and a +number of related project settings. If this file is lost or corrupted, the structure of the project is lost, although not the text itself. It is important to keep this file backed up, either through the built-in backup tool, or diff --git a/docs/source/tech_tests.rst b/docs/source/tech_tests.rst index ae40e4d4..f4502594 100644 --- a/docs/source/tech_tests.rst +++ b/docs/source/tech_tests.rst @@ -34,12 +34,11 @@ Since several of the tests involve opening up the novelWriter GUI, you may want for the duration of the test run. Moving your mouse while the tests are running may otherwise interfere with the execution of some tests. -You can disable the renderring of the GUI by setting the flag ``export QT_QPA_PLATFORM=offscreen``, -or alternatively run the tests with the ``xvfb`` package, like so: +You can disable the renderring of the GUI by setting the flag ``QT_QPA_PLATFORM=offscreen``: .. code-block:: bash - xvfb-run pytest + export QT_QPA_PLATFORM=offscreen pytest Advanced Options @@ -51,7 +50,7 @@ You can also add coverage report generation. For instance to HTML: .. code-block:: bash - xvfb-run pytest -v --cov=novelwriter --cov-report=html + export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html Other useful report formats are ``xml``, and ``term`` for terminal output. @@ -60,7 +59,7 @@ subpackage groups are ``base``, ``core``, and ``gui``. Consider for instance: .. code-block:: bash - xvfb-run pytest -v --cov=novelwriter --cov-report=html -m core + export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html -m core This will only run the tests of the "core" package, that is, all the classes that deal with the project data of a novelWriter project. The "gui" tests, likewise, will run the tests for the GUI @@ -71,7 +70,7 @@ You can also filter the tests with the ``-k`` switch. The following will do the .. code-block:: bash - xvfb-run pytest -v --cov=novelwriter --cov-report=html -k testCore + export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html -k testCore All tests are named in such a way that you can filter them by adding more bits of the test names. They all start with the word "test". Then comes the group: "Core", "Base", "Dlg", "Tool", or "Gui". @@ -80,6 +79,6 @@ file. For instance, running the following will run all tests for the document ed .. code-block:: bash - xvfb-run pytest -v --cov=novelwriter --cov-report=html -k testGuiEditor + export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html -k testGuiEditor To run a single test, simply add the full test name to the ``-k`` switch. diff --git a/docs/source/usage_breakdown.rst b/docs/source/usage_breakdown.rst index c5c1eaca..b6899f44 100644 --- a/docs/source/usage_breakdown.rst +++ b/docs/source/usage_breakdown.rst @@ -8,9 +8,9 @@ How it Works .. _Pandoc: https://pandoc.org/ .. _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 more detail. +The main features of novelWriter are listed in the :ref:`a_intro` chapter. In this chapter, 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 more detail. .. _a_breakdown_design: @@ -19,20 +19,20 @@ GUI Layout and Design ===================== The user interface of novelWriter is intended to be as minimalistic as practically possible, while -at the same time provide a complete set of features needed for writing a novel. +at the same time provide useful 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, 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. +them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` chapter. .. note:: novelWriter is not intended to be a full office type word processor. It doesn't support images, links, tables, and other complex structures and objects often needed for such documents. 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 +On the left side 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 Manuscript` tool, and a set of project-related tools and quick access to settings at the bottom. @@ -46,11 +46,13 @@ 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 -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. +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's header, or by pressing :kbd:`F8`. When :guilabel:`Focus Mode` is enabled, all the user @@ -79,15 +81,15 @@ 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 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 +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. +the menu button in the toolbar. -If you click the arrow icon to the right of each item, a tooltip will pop up showing you all the -meta data collected for that heading entry. +If you click the arrow icon to the right of each item, a tooltip will pop out showing you all the +meta data collected for that heading. Novel Outline View @@ -111,8 +113,8 @@ Colour Themes 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. +neutral colours from :guilabel:`Preferences`. Other colour themes are also available. More themes +can be contributed to novelWriter on GitHub. 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 @@ -143,9 +145,9 @@ within those documents. The four heading levels (**H1** to **H4**) are treated as follows: -* **H1** is used for the book title, and for partitions. +* **H1** is used for the novel title, and for partitions. * **H2** is used for chapter tiles. -* **H3** is used for scene titles – optionally replaced by separators. +* **H3** is used for scene titles -- optionally replaced by separators. * **H4** is for section titles within scenes, if such granularity is needed. The project tree will select an icon for the document based on the first heading in it. @@ -157,7 +159,8 @@ whatever they want. See :ref:`a_struct` and :ref:`a_references` for more details .. 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. + individual scene documents so that you can rearrange scene documents freely without affecting + chapter placement. .. _a_breakdown_export: @@ -177,7 +180,8 @@ In addition, you can export the content of the project to a JSON file. This is u 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_manuscript_build` for more details. + +See :ref:`a_manuscript` for more details. .. versionadded:: 2.1 You can now define multiple build definitions in the :guilabel:`Build Manuscript` tool. This @@ -192,31 +196,35 @@ Project Storage The files of a novelWriter project are stored in a dedicated project folder. The project structure is kept in a file at the root of this folder called ``nwProject.nwx``. All the document files and -associated meta data is stored in the other folders below the project folder. For more technical +associated meta data is stored in other folders below the project folder. For more technical details about what all the files mean and how they're organised, see the :ref:`a_storage` section. -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 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. +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, which means there is a smaller risk of losing data if the application or your computer +crashes. + +Secondly, having multiple 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:: - Since novelWriter has to keep track of a bunch of files and folders when a project is open, it may not run well on some virtual file systems. A file or folder must be accessible with exactly the path it was saved or created with. An example where this is not the case is the way Google Drive is mapped on Linux Gnome desktops using gvfs/gio. .. caution:: + You should not add additional files to the project folder yourself. Nor should you,a s a rule, + manually edit files within it. If you really must manually edit the text files, e.g. with some + automated task you want to perform, you need to rebuild the :term:`Project Index` when you open + the project again. - 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 :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 + Editing text files in the ``content`` folder is less risky as these 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 04d4ccdf..4b159491 100644 --- a/docs/source/usage_format.rst +++ b/docs/source/usage_format.rst @@ -11,7 +11,7 @@ values and allowing for some text formatting. The syntax is based on Markdown, b In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a set of 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. +some codes that apply to whole paragraphs. See :ref:`a_fmt_text` for more details. .. _a_fmt_hlight: @@ -65,7 +65,7 @@ correctly to produce the intended result. See :ref:`a_struct_heads` for more det ``#### Title Text`` Heading level four. For novel documents, the header level indicates the start of a new section. - Section titles can be replaced by separators or removed completely when building the manuscript. + Section titles can be replaced by separators or ignored completely when building the manuscript. For headers level one and two, adding a ``!`` modifies the behaviour of the heading: @@ -165,9 +165,9 @@ The text of a comment is ignored by the word counter. The text can also be filte building the manuscript or viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon included), the comment is treated -specially and will show up in the :ref:`a_ui_outline` in a dedicated column. 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. +in a special manner and will show up in the :ref:`a_ui_outline` in a dedicated column. 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. ``% text...`` This is a comment. The text is not renderred by default (this can be overridden), seen in the @@ -204,8 +204,8 @@ References are on the form: ``@keyword: value`` A reference keyword followed by a value, or a comma separated list of values. -The available reference keywords are listed in the :ref:`a_references_references` section. They can -also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu. +Tags andreferences are covered in detail in the :ref:`a_references` chapter. The keywords can be +inserted at the cursor position in the editor via the :guilabel:`Insert` menu. .. _a_fmt_align: @@ -214,7 +214,7 @@ Paragraph Alignment and Indentation =================================== All documents have the text by default aligned to the left or justified, depending on your -Preferences. +settings in :guilabel:`Preferences`. You can override the default text alignment on individual paragraphs by specifying alignment tags. These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after @@ -262,8 +262,7 @@ headers of level two for novel documents, i.e. chapters, but not for project not If you need to add a page break somewhere else, put the text ``[NEW PAGE]`` on a line by itself before the text you wish to start on a new page. -Page breaks are automatically added to partition, chapter and unnumbered chapter headers of novel -documents. If you want such breaks for scenes and sections, you must add them manually. +If you want page breaks for scenes and sections, you must add them manually. .. note:: The page break code is applied to the text that follows it. It adds a "page break before" mark diff --git a/docs/source/usage_project.rst b/docs/source/usage_project.rst index 3482534d..4229b6eb 100644 --- a/docs/source/usage_project.rst +++ b/docs/source/usage_project.rst @@ -4,7 +4,7 @@ Project Views ************* -This sections covers in more detail the different project views available in novelWriter. +This chapter covers in more detail the different project views available in novelWriter. .. figure:: images/fig_project_tree_detailed.png @@ -81,14 +81,14 @@ Splitting Documents The :guilabel:`Split Document` dialog. The :guilabel:`Split Document by Header` option will open a dialog that allows you to split the -selected document into multiple new documents based on the headers it contains. You can select at -which header level the split is to be performed from the dropdown box. The list box will preview -which headers will be split into new documents. +selected document into multiple new documents based on the headings it contains. You can select at +which heading level the split is to be performed from the dropdown box. The list box will preview +which headings will be split into new documents. You are given the option to create a folder for these new documents, and whether or not to create a hierarchy of documents. That is, put sections under scenes, and scenes under chapters. -The source document **is not** deleted in the process, but you have the option to let the tool move +The source document *is not* deleted in the process, but you have the option to let the tool move the source document to the :guilabel:`Trash` folder. Merging Documents @@ -119,9 +119,9 @@ Each document or folder in your project can have either a "Status" or "Importanc 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 +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. +:term:`project notes`, as for instance a main, major, or minor character or story element. 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 @@ -139,10 +139,11 @@ 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`. +the last move action can be undone by pressing :kbd:`Ctrl+Shift+Z` or from the menu icon in the +project tree's toolbar. 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 +document 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 @@ -171,7 +172,7 @@ of the story itself rather than the document files. 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. + references, which will be updated in this view when the document is saved. .. _a_ui_outline: @@ -189,16 +190,16 @@ the novel, that is, the level 1 to 4 headings representing partitions, chapters, 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. +number where the heading is defined. Double-clicking an entry will open the corresponding document +in the editor and switch to :guilabel:`Project Tree View` mode. 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. + structure of the project tree, this view 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 diff --git a/docs/source/usage_projectformat.rst b/docs/source/usage_projectformat.rst index 3a0265f5..58f8525e 100644 --- a/docs/source/usage_projectformat.rst +++ b/docs/source/usage_projectformat.rst @@ -11,15 +11,14 @@ Most of the changes to the file formats over the history of novelWriter have no 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 -applicable. +The key changes in the formats are listed in this chapter, as well as the user actions required, +where applicable. .. only:: not html A full project file format specification is available in the online documentation_. .. caution:: - When you update a project from one format version to the next, the project can no longer be opened by a version of novelWriter prior to the version where the new file format was introduced. You will get a notification about any updates to your project file format and will @@ -71,7 +70,7 @@ Format 1.3 Changes This project format was introduced in novelWriter version 1.5. -With this format, the number of document layouts was reduced from 8 to 2. The conversion of +With this format, the number of document layouts was reduced from eight to two. The conversion of document layouts is performed automatically when the project is opened. Due to the reduction of layouts, some features that were previously controlled by these layouts @@ -85,7 +84,7 @@ should be used only a few places in any given project. These are as follows: * The formatting of the level one title on the title page must be changed from ``# Title Text`` to ``#! Title Text`` in order to retain the previous functionality. See :ref:`a_fmt_head`. -* Any text that was previously centred on the page must be manually centred using the new text +* Any text that was previously centred on the page must be manually centred using the text alignment feature. See :ref:`a_fmt_align`. **Unnumbered Chapters** diff --git a/docs/source/usage_shortcuts.rst b/docs/source/usage_shortcuts.rst index 09e0b485..764b5240 100644 --- a/docs/source/usage_shortcuts.rst +++ b/docs/source/usage_shortcuts.rst @@ -5,10 +5,10 @@ Keyboard Shortcuts ****************** Most features in novelWriter are available as keyboard shortcuts. This is a reference list if these -shortcuts. Most of them are also listed in the application. +shortcuts. Most of them are also listed in the application's user interface. .. note:: - On macOS, replace :kbd:`Ctrl` with :kbd:`Cmd`. + On MacOS, replace :kbd:`Ctrl` with :kbd:`Cmd`. .. _a_kb_main: diff --git a/docs/source/usage_typography.rst b/docs/source/usage_typography.rst index 8604f724..95585195 100644 --- a/docs/source/usage_typography.rst +++ b/docs/source/usage_typography.rst @@ -59,8 +59,8 @@ Single and Double Prime ------------------------ Both single and double prime symbols are available in the :guilabel:`Insert` menu. These symbols -are the correct symbols to use for unit symbols for feet, inches, minutes and seconds. The usage of -these is described in more detail on the Wikipedia Prime_ page. They look very similar to single +are the correct symbols to use for unit symbols for feet, inches, minutes, and seconds. The usage +of these is described in more detail on the Wikipedia Prime_ page. They look very similar to single and double straight quotes, and may be renderred similarly by the font, but they have different codes. Using these correctly will also prevent the auto-replace and dialogue highlighting features misunderstanding their meaning in the text. @@ -81,7 +81,7 @@ right single quotation marks, depending on the font. There is a Wikipedia articl .. note:: 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. + Therefore it doesn't really matter if you only use them to correct syntax highlighting. Special Space Symbols diff --git a/docs/source/usage_writing.rst b/docs/source/usage_writing.rst index 3373af18..56c2ff78 100644 --- a/docs/source/usage_writing.rst +++ b/docs/source/usage_writing.rst @@ -6,7 +6,7 @@ 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. +This chapter covers in more detail how the document editor and viewer panels work. .. _a_ui_edit: @@ -21,7 +21,7 @@ Editing a Document 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. +format is described in the :ref:`a_fmt` chapter. 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 @@ -33,8 +33,8 @@ header at the top of the edit or view panel. Optionally, the full project path t 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. + Clicking on the document title bar will select the document in the project tree and thus reveal + its location there, making it easier to find 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. @@ -54,10 +54,10 @@ viewer. To view a document, press :kbd:`Ctrl+R`, or select :guilabel:`View Docum 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. +The document viewed does not have to be the same document as the one 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 viewer 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. @@ -75,10 +75,10 @@ This is convenient if you want to quickly look through all documents in the list :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`. + The :guilabel:`References` panel relies on an up-to-date :term:`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: @@ -124,8 +124,8 @@ 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 :guilabel:`Insert` menu, and via :ref:`a_kb_ins`. You may also be using a `Compose Key`_ + setup, which means you may not need the auto-replace feature at all. 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 @@ -135,5 +135,5 @@ 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. + :kbd:`Ctrl+Z` once after the auto-replacement will undo it without undoing the character + you typed before it.