diff --git a/source/about/docs.rst b/source/about/docs.rst index e2b4083..9558797 100644 --- a/source/about/docs.rst +++ b/source/about/docs.rst @@ -12,6 +12,7 @@ PDF Manuals A selection of PDF manuals are available here for download, including for earlier versions of novelWriter: +| :download:`novelWriter-2.3.pdf` | :download:`novelWriter-2.2.pdf` | :download:`novelWriter-2.1.pdf` | :download:`novelWriter-2.0.pdf` diff --git a/source/about/novelWriter-2.3.pdf b/source/about/novelWriter-2.3.pdf new file mode 100644 index 0000000..2c2601c Binary files /dev/null and b/source/about/novelWriter-2.3.pdf differ diff --git a/source/docs/fileformatspec15.pdf b/source/docs/fileformatspec15.pdf index 5115b5b..58b5be9 100644 Binary files a/source/docs/fileformatspec15.pdf and b/source/docs/fileformatspec15.pdf differ diff --git a/source/docs/images/fig_build_build.png b/source/docs/images/fig_build_build.png index 7265067..8c509d5 100644 Binary files a/source/docs/images/fig_build_build.png and b/source/docs/images/fig_build_build.png differ diff --git a/source/docs/images/fig_build_settings_headings.png b/source/docs/images/fig_build_settings_headings.png index 4eb54c5..d521936 100644 Binary files a/source/docs/images/fig_build_settings_headings.png and b/source/docs/images/fig_build_settings_headings.png differ diff --git a/source/docs/images/fig_build_settings_selections.png b/source/docs/images/fig_build_settings_selections.png index 9dc82d4..c9b4cb9 100644 Binary files a/source/docs/images/fig_build_settings_selections.png and b/source/docs/images/fig_build_settings_selections.png differ diff --git a/source/docs/images/fig_manuscript_build.png b/source/docs/images/fig_manuscript_build.png index 8a3e1ae..31605cd 100644 Binary files a/source/docs/images/fig_manuscript_build.png and b/source/docs/images/fig_manuscript_build.png differ diff --git a/source/docs/images/fig_project_merge_tool.png b/source/docs/images/fig_project_merge_tool.png index a49ae22..8f01ad2 100644 Binary files a/source/docs/images/fig_project_merge_tool.png and b/source/docs/images/fig_project_merge_tool.png differ diff --git a/source/docs/images/fig_project_split_tool.png b/source/docs/images/fig_project_split_tool.png index 5d122f6..a7809f8 100644 Binary files a/source/docs/images/fig_project_split_tool.png and b/source/docs/images/fig_project_split_tool.png differ diff --git a/source/docs/images/fig_welcome.jpg b/source/docs/images/fig_welcome.jpg new file mode 100644 index 0000000..7bcde45 Binary files /dev/null and b/source/docs/images/fig_welcome.jpg differ diff --git a/source/docs/index.rst b/source/docs/index.rst index cc7b6b6..173ce87 100644 --- a/source/docs/index.rst +++ b/source/docs/index.rst @@ -4,15 +4,15 @@ Documentation ************* -| **Release Version:** 2.2.1 -| **Release Date:** Saturday, 27 January 2024 -| **Docs Updated:** Saturday, 27 January 2024 +| **Release Version:** 2.3 +| **Release Date:** Sunday, 10 March 2024 +| **Docs Updated:** Sunday, 10 March 2024 -**PDF:** :download:`novelWriter-2.2.pdf <../about/novelWriter-2.2.pdf>` [ :ref:`Older Versions ` ] +**PDF:** :download:`novelWriter-2.3.pdf <../about/novelWriter-2.3.pdf>` [ :ref:`Older Versions ` ] -novelWriter is an open source plain text editor designed for writing novels assembled from many -smaller text documents. It uses a minimal formatting syntax inspired by Markdown, and adds a meta -data syntax for comments, synopsis, and cross-referencing. It is designed to be a simple text +novelWriter is an open source plain text editor designed for writing novels assembled from +individual text documents. It uses a minimal formatting syntax inspired by Markdown, and adds a +meta data syntax for comments, synopsis, and cross-referencing. It is designed to be a simple text editor that allows for easy organisation of text and notes, using human readable text files as storage for robustness. @@ -28,13 +28,14 @@ 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 -with pip. See :ref:`a_started` for more details. +as well. novelWriter can be run directly from the Python source, or installed from packages or with +pip. See :ref:`a_started` for more details. **Useful Links** * Website: https://novelwriter.io * Documentation: https://docs.novelwriter.io +* Public Releases: https://releases.novelwriter.io * Internationalisation: https://crowdin.com/project/novelwriter * Source Code: https://github.com/vkbo/novelWriter * Source Releases: https://github.com/vkbo/novelWriter/releases @@ -71,7 +72,6 @@ with pip. See :ref:`a_started` for more details. usage_format usage_shortcuts usage_typography - usage_projectformat .. toctree:: :maxdepth: 1 @@ -85,7 +85,15 @@ with pip. See :ref:`a_started` for more details. .. toctree:: :maxdepth: 1 - :caption: Additional Topics + :caption: Additional Details + :hidden: + + more_projectformat + more_counting + +.. toctree:: + :maxdepth: 1 + :caption: Technical Topics :hidden: tech_locations diff --git a/source/docs/int_customise.rst b/source/docs/int_customise.rst index baa67ee..7b93249 100644 --- a/source/docs/int_customise.rst +++ b/source/docs/int_customise.rst @@ -36,7 +36,8 @@ and add dictionaries yourself. A small tool to assist with this can be found under :guilabel:`Tools > Add Dictionaries`. It will import spell checking dictionaries from Free Office or Libre Office extensions. The dictionaries -are then installed in the install location for the Enchant library. +are then installed in the install location for the Enchant library and should thus work for any +application that uses Enchant for spell checking. **Manual Install** @@ -139,10 +140,10 @@ In the Main section you must at least define the ``name`` and ``icontheme`` sett ``typicons_light`` or ``typicons_dark``, or to an icon theme in your custom icons directory. The setting must match the icon theme's folder name. -The Palette values correspond to the Qt enum values for QPalette::ColorRole, see the +The Palette values correspond to the Qt enum values for ``QPalette::ColorRole``, see the `Qt documentation `_ for more details. The -colour values are RGB numbers on the format ``r, g, b`` where each is an integer from to 255. -Omitted values are not loaded and will use default values. +colour values are RGB numbers on the format ``r, g, b`` where each is an integer from ``0`` to +``255``. Omitted values are not loaded and will use default values. Custom Syntax Theme @@ -174,15 +175,20 @@ A syntax theme ``.conf`` file consists of the following settings: shortcode = 0, 0, 0 keyword = 0, 0, 0 value = 0, 0, 0 + optional = 0, 0, 0 spellcheckline = 0, 0, 0 errorline = 0, 0, 0 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 of the format ``r, g, b`` where each is an integer from to 255. Omitted values default -to black, except ``background`` which defaults to white, +RGB(A) numbers of the format ``r, g, b, a`` where each is an integer ``0`` from to ``255``. The +fourth value is the alpha channel (transparency), which can be omitted. + +Omitted syntax colours default to black, except ``background`` which defaults to white. .. versionadded:: 2.2 - The `shortcode` syntax colour entry was added, so you need to update your custom themes if you - made any before version 2.2. + The `shortcode` syntax colour entry was added. + +.. versionadded:: 2.3 + The `optional` syntax colour entry was added. diff --git a/source/docs/int_glossary.rst b/source/docs/int_glossary.rst index 2cead9c..7e9bd50 100644 --- a/source/docs/int_glossary.rst +++ b/source/docs/int_glossary.rst @@ -50,7 +50,7 @@ Glossary Headings Each level of headings in :term:`Novel Documents` have a specific meaning in terms of the structure of the story. That is, they determine what novelWriter considers a partition, a - chapter, a scene or a text section. For :term:`Project Notes`, the header levels don't + chapter, a scene or a text section. For :term:`Project Notes`, the heading levels don't matter. For more details on headings in novel documents, see :ref:`a_struct_heads`. Keyword diff --git a/source/docs/int_howto.rst b/source/docs/int_howto.rst index d3633f7..43f2860 100644 --- a/source/docs/int_howto.rst +++ b/source/docs/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. See :ref:`a_ui_tree_split_merge` for more details. + can rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details. Layout Tricks @@ -42,7 +42,7 @@ Layout Tricks in columns using the tab key, and it should look the same when viewed next to the editor. This is most suitable for your notes, as the result in exported documents cannot be guaranteed - to match. + to match. Especially if you don't use the same font in your manuscript as in the editor. Organising Your Text @@ -56,7 +56,9 @@ Organising Your Text If you add separate files for chapters and scenes, the chapter file is the perfect place to add such text. Separating chapter and scene files also allows you to make scene files child - documents of the chapter (added in novelWriter 2.0). + documents of the chapter. + + .. versionadded:: 2.0 .. dropdown:: Distinguishing Soft and Hard Scene Breaks :animate: fade-in-slide-down @@ -64,12 +66,15 @@ Organising Your Text Depending on your writing style, you may need to separate between soft and hard scene breaks within chapters. Like for instance if you switch point-of-view character often. - In such cases you may want to use the scene heading for hard scene breaks and section headings + In such cases you may want to use a scene heading for hard scene breaks and a section heading for soft scene breaks. The :guilabel:`Build Manuscript` tool will let you add separate formatting for the two when you generate your manuscript. You can for instance add the common "``* * *``" for hard breaks and select to hide section breaks, which will just insert an empty paragraph in their place. See :ref:`a_manuscript_settings` for more details. + Keep in mind that this is not what the section heading is intended for, so the app will not + understand the section heading as a scene, but it will be formatted correctly in the manuscript. + Other Tools =========== diff --git a/source/docs/int_introduction.rst b/source/docs/int_introduction.rst index 9bc8914..a23810b 100644 --- a/source/docs/int_introduction.rst +++ b/source/docs/int_introduction.rst @@ -8,9 +8,18 @@ Key Features .. _Markdown: https://en.wikipedia.org/wiki/Markdown 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 available are limited to those relevant for this purpose. It is *not* suitable -for technical writing, and it is *not* a full-featured Markdown editor. +Markdown_ to apply simple formatting to the text. It also allows for some extended formatting codes +using a shortcode format. See :ref:`a_fmt_shortcodes` for more details. + +.. admonition:: Limitations + + novelWriter is designed for writing fiction, so the formatting features available are limited to + those relevant for this purpose. It is **not** suitable for technical writing, and it is **not** + a full-featured Markdown editor. + + It is also not intended as a tool to organise research for writing, and therefore lacks + formatting features you may need for this purpose. The notes feature in novelWriter is mainly + intended for character profiles and plot outlines. Your novel project is organised as a collection of separate plain text documents instead of a single, large document. The idea is to make it easier to reorganise your project structure without @@ -20,10 +29,10 @@ There are two kinds of documents in your project: :term:`Novel Documents` are do part of your story. The other kind of documents are :term:`Project Notes`. These are intended for your notes about your characters, your world building, and so on. -You can at any point split the individual documents by their headers up into multiple documents, or -merge multiple documents into single documents. This makes it easier to use variations of the +You can at any point split the individual documents by their headings up into multiple documents, +or merge multiple documents into single documents. This makes it easier to use variations of the Snowflake_ method for writing. You can start by writing larger structure-focused documents, like -one per act for instance, and later effortlessly split these up into scenes by their headers. +one per act for instance, and later effortlessly split these up into chapters or scenes. Below are some key features of novelWriter. @@ -45,15 +54,15 @@ Below are some key features of novelWriter. 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 of the project tree. You can also start out with a few documents and then - later split them into multiple documents based on their headers. + drag-and-drop feature of the project tree. You can also start out with fewer documents and then + later split them into multiple documents based on chapter and scene headings. **Multi-novel project support** - As of novelWriter 2.0, you can have multiple Novel type root folders in a project. This allows - you to keep a series of individual novels with the same characters and world building in the - same project, and create manuscripts for them individually. + You can have multiple Novel type root folders in a project. This allows you to keep a series of + individual novels with the same characters and world building in the same project, and create + manuscripts for them individually. -**Keep track of your plot elements** +**Keep track of your story 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 of it. @@ -69,10 +78,10 @@ Below are some key features of novelWriter. **Get an overview of your story elements** Under the document viewer panel you will find a series of tabs that shows the different story elements you have created tags for. The tabs are sorted into Characters, Plots, etc, depending - on which categories you are using in your story. This panel can be hidden when you don't need it - to free up space. + on which categories you are using in your story. This panel can be hidden to free up space when + you don't need it. -**Building your manuscript** +**Assembling 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, diff --git a/source/docs/int_overview.rst b/source/docs/int_overview.rst index 69202c2..e83dcd5 100644 --- a/source/docs/int_overview.rst +++ b/source/docs/int_overview.rst @@ -11,9 +11,9 @@ Overview :width: 220 novelWriter is built as a cross-platform application using `Python 3 `_ as -the programming language, and `Qt 5 `_ for the user interface. +the programming language, and `Qt 5 `_ framework for the user interface. -novelWriter is built for Linux first, and this is where it works best. However, it also runs fine +novelWriter is built for Linux first, so this is where it works best. However, it also runs fine on Windows and MacOS due to the cross-platform framework it's built on. The author of the application doesn't own a Mac, so on-going Mac support is dependent on user feedback and user contributions. @@ -22,7 +22,7 @@ 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 install spell checking languages. -For install instructions, see :ref:`a_started`. +For install instructions for novelWriter, see :ref:`a_started`. Using novelWriter @@ -58,12 +58,6 @@ read on. 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 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 - chapter. - Organising Your Projects ======================== @@ -90,3 +84,11 @@ meta data for it to extract. :ref:`a_manuscript` - Recommended Reading 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. + + +Additional Details & Technical Topics +===================================== + +The Additional Details and the Technical Topics sections contain more in-depth information about +how various bits of novelWriter works. This information is not essential to getting started using +novelWriter. diff --git a/source/docs/int_started.rst b/source/docs/int_started.rst index e83c0a4..d53b68c 100644 --- a/source/docs/int_started.rst +++ b/source/docs/int_started.rst @@ -6,7 +6,7 @@ Getting Started .. _Enchant: https://abiword.github.io/enchant/ .. _GitHub: https://github.com/vkbo/novelWriter -.. _main website: https://novelwriter.io +.. _Downloads page: https://download.novelwriter.io .. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter .. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre .. _PyPi: https://pypi.org/project/novelWriter/ @@ -15,9 +15,10 @@ Getting Started .. _AppImage: https://appimage.org/ Ready-made packages and installers for novelWriter are available for all major platforms, including -Linux, Windows and MacOS. See below for install instructions for each platform. +Linux, Windows and MacOS, from the `Downloads page`_. See below for install instructions for each +platform. -You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`. +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, or start novelWriter from the command line. @@ -32,7 +33,7 @@ Installing on Windows ===================== You can install novelWriter with both Python and library dependencies embedded using the Windows -Installer (setup.exe) file from the `main website`_, or from the Releases_ page on GitHub_. +Installer (setup.exe) file from the `Downloads page`_, or from the Releases_ page on GitHub_. Installing it should be straightforward. If you have any issues, try uninstalling the previous version and making a fresh install. If you @@ -51,8 +52,8 @@ multiple installations has been known to cause problems. Installing on Linux =================== -A Debian package can be downloaded from the `main website`_, or from the Releases_ page on GitHub_. -This package should work on both Debian, Ubuntu and Linux Mint, at least. +A Debian package can be downloaded from the `Downloads page`_, or from the Releases_ page on +GitHub_. This package should work on both Debian, Ubuntu and Linux Mint, at least. If you prefer, you can also add the novelWriter repository on Launchpad to your package manager. @@ -112,8 +113,8 @@ 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 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 + novelWriter generally doesn'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. @@ -123,14 +124,14 @@ Installing on MacOS =================== You can install novelWriter with both its Python and library dependencies embedded using the DMG -application image file from the `main website`_, or from the Releases_ page on GitHub_. Installing -it should be straightforward. +application image file from the `Downloads page`_, or from the Releases_ page on GitHub_. +Installing it should be straightforward. * Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications` folder on the right. This will install it into your :guilabel:`Applications`. * The first time you try to launch it, it will say that the bundle cannot be verified, simply press the :guilabel:`Open` button to add an exception. -* If you are not presented with an :guilabel:`Open` button in the dialog launch the application +* If you are not presented with an :guilabel:`Open` button in the dialog, launch the application again by right clicking on the application in Finder and selecting :guilabel:`Open` from the context menu. @@ -149,7 +150,7 @@ Installing from PyPi ==================== novelWriter is also available on the Python Package Index, or PyPi_. This install method works on -all supported operating systems. +all supported operating systems with a suitable Python environment. To install from PyPi you must first have the ``python`` and ``pip`` commands available on your system. You can download Python from `python.org`_. It is recommended that you install the latest diff --git a/source/docs/more_counting.rst b/source/docs/more_counting.rst new file mode 100644 index 0000000..3f0d221 --- /dev/null +++ b/source/docs/more_counting.rst @@ -0,0 +1,39 @@ +.. _a_counting: + +******************** +Word and Text Counts +******************** + +This is an overview of how words and other counts of your text are performed. The counting rules +should be relatively standard, and are compared to LibreOffice Writer rules. The counts provided in +the app on the raw text are only meant to be approximate. + + +Text Word Counts and Stats +========================== + +These are the rules for the main counts available for for each document in a project. + +For all counts, the following rules apply. + +#. Short (–) and long (—) dashes are considered word separators. +#. Any line starting with ``%`` or ``@`` is ignored. +#. Trailing white spaces are ignored, including line breaks. +#. Leading ``>`` and trailing ``<`` are ignored with any spaces next to them. +#. Valid shortcodes and other commands wrapped in brackets ``[]`` are ignored. +#. In-line Markdown syntax in text paragraphs is treated as part of the text. + +After the above preparation of the text, the following counts are available. + +**Character Count** + The character count is the sum of characters per line, including leading and in-text white space + characters, but excluding trailing white space characters. Shortcodes in the text are not + included, but Markdown codes are. Only headers and text are counted. + +**Word Count** + The words count is the sum of blocks of continuous character per line separated by any number of + white space characters or dashes. Only headers and text are counted. + +**Paragraph Count** + The paragraph count is the number of text blocks separated by one or more empty line. A line + consisting only of white spaces is considered empty. diff --git a/source/docs/usage_projectformat.rst b/source/docs/more_projectformat.rst similarity index 100% rename from source/docs/usage_projectformat.rst rename to source/docs/more_projectformat.rst diff --git a/source/docs/project_manuscript.rst b/source/docs/project_manuscript.rst index 0818e86..91af624 100644 --- a/source/docs/project_manuscript.rst +++ b/source/docs/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 the build, but otherwise has much the same + only allows you to define a single set of options for the build, but otherwise had much the same functionality. @@ -73,7 +73,7 @@ Formatting Headings The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog allows you to set 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. +numbers and scene numbers, or insert character names, like shown in the figure above. 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 @@ -152,7 +152,7 @@ novelWriter Markup Standard/Extended Markdown The Markdown format comes in both Standard and Extended flavour. The *only* difference in terms - of novelWriter functionality is the support for strikethrough text, which is not supported by + of novelWriter functionality is the support for strike through text, which is not supported by the Standard flavour. diff --git a/source/docs/project_overview.rst b/source/docs/project_overview.rst index 4429df4..d546992 100644 --- a/source/docs/project_overview.rst +++ b/source/docs/project_overview.rst @@ -4,21 +4,25 @@ Novel Projects ************** -New projects can be created from the :guilabel:`Project` menu by selecting :guilabel:`New Project`. -This will open the :guilabel:`New Project Wizard` that will assist you in creating a bare bone -project suited to your needs. +New projects can be created from the :guilabel:`Project` menu by selecting +:guilabel:`Create or Open Project`. This will open the :guilabel:`Welcome` dialog, where you can +select the :guilabel:`New` button that will assist you in creating a new project. A novelWriter project requires a dedicated folder for storing its files on the local file system. 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` +A list of recently opened projects is maintained, and displayed in the :guilabel:`Welcome` dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key or -by clicking the :guilabel:`Remove` button. +by right-clicking it and selecting the :guilabel:`Remove Project` option. + +.. figure:: images/fig_welcome.jpg + + The project list (left) and new project form (right) of the :guilabel:`Welcome` dialog. 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. Details about the project, -including word counts, and a table of contents with word and page counts, is available through the -:guilabel:`Project Details` dialog. +menu. See further details below in the :ref:`a_proj_settings` section. Details about the project's +novel text, including word counts, and a table of contents with word and page counts, is available +through the :guilabel:`Novel Details` dialog. .. _a_proj_roots: @@ -58,8 +62,9 @@ details, see the :ref:`a_references` chapter. Character notes go in this root folder type. These are especially important if you want to use the :guilabel:`Outline View` to see which character appears where, which part of the story is 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 + storyline. The character names can also be inserted into for instance chapter titles when you + create your manuscript. 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 present. :guilabel:`Locations` @@ -105,8 +110,8 @@ trash folder can then be deleted permanently, either individually, or by emptyin 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 -:kbd:`Ctrl+Shift+Del`. Root folders can only be deleted when they are empty. +A document or a folder can be moved to trash from the :guilabel:`Project` menu, or by pressing +:kbd:`Ctrl+Shift+Del`. Root folders can only be removed when they are empty. .. _a_proj_roots_out: @@ -129,9 +134,9 @@ 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. +file synchronisation tool that runs out of sync, there may be files in the project storage folder +that aren't tracked in the core project file. These files, when discovered, are recovered and added +back into the project. 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 @@ -152,10 +157,10 @@ Project Lockfile ---------------- To prevent lost documents caused by file conflicts when novelWriter projects are synchronised via -file synchronisation tools, a project lockfile is written to the project folder. If you try to open -a project which has such a file present, you will be presented with a warning, and some information -about where else novelWriter thinks the project is also open. You will be given the option to -ignore this warning, and continue opening the project at your own risk. +file synchronisation tools, a project lockfile is written to the project storage folder. If you try +to open a project which has such a file present, you will be presented with a warning, and some +information about where else novelWriter thinks the project is also open. You will be given the +option to ignore this warning, and continue opening the project at your own risk. .. note:: If, for some reason, novelWriter crashes, the lock file may remain even if there are no other @@ -208,6 +213,18 @@ converting, splitting, or merging items. See :ref:`a_ui_tree_split_merge` for mo latter two. +Document Templates +------------------ + +If you wish to create template documents to be used when creating new project documents, like for +instance a character note template, you can add a :guilabel:`Templates` root folder to your +project. Any document added to this root folder will show up in the :guilabel:`Add Item` menu in +the project tree toolbar. When selected, a new document is created with its content copied from the +chosen template. + +.. versionadded:: 2.3 + + .. _a_proj_files_counts: Word Counts @@ -227,6 +244,8 @@ the values in the project tree, which again depend on an up to date :term:`proje 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 rules for how the counts are made is covered in more detail in :ref:`a_counting`. + .. _a_proj_settings: @@ -242,25 +261,23 @@ Settings Tab The :guilabel:`Settings` tab holds the project name, title, and author settings. -The :guilabel:`Project Name` can be set to a different value than the :guilabel:`Novel Title`. The -difference between them is simply that the :guilabel:`Project Name` is used for the GUI (main -window title) and for generating backup files. The intention is that the :guilabel:`Project Name` -should remain unchanged throughout the project's lifetime, otherwise the name of exported files and -backup files may change too. +The :guilabel:`Project Name` can be edited here. It is used for the GUI (main window title) and for +generating backup files. So keep in mind that if you do change this setting, the backup file names +will change too. -The :guilabel:`Novel Title` and :guilabel:`Authors` settings are used when building the manuscript, -for some formats. +You can also change the :guilabel:`Authors` and :guilabel:`Project Language` setting. These are +only used when building the manuscript, for some formats. 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. +can override the default setting here. The project language can also be changed from the +:guilabel:`Tools` menu. You can also override the automatic backup setting if you wish. Status and Importance Tabs -------------------------- -Each document or folder of type :guilabel:`Novel` can be given a *Status* label accompanied by a -coloured icon, and each document or folder of the remaining types can be given an *Importance* +Each document or folder of type :guilabel:`Novel` can be given a "Status" label accompanied by a +coloured icon, and each document or folder of the remaining types can be given an "Importance" label. These labels are there purely for your convenience, and you are not required to use them for any diff --git a/source/docs/project_references.rst b/source/docs/project_references.rst index 95f1f2d..cdd2953 100644 --- a/source/docs/project_references.rst +++ b/source/docs/project_references.rst @@ -4,8 +4,8 @@ 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 create :term:`project notes` which you can mark as +In novelWriter there are no forms or tables to fill in to define characters, locations or other +elements of your story. Instead, you create :term:`project notes` which you can mark 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. @@ -16,9 +16,9 @@ this chapter hopes to explain in more detail how to use this tags and references .. tip:: If you find the Tags and Reference system difficult to follow just from reading this chapter, - you can create a new project in novelWriter and select to "Fill the project with example files" - in the :guilabel:`New Project Wizard`. The example project contains several examples of tags and - references. + you can create a new project in the :guilabel:`Welcome` dialog's New project form and select + "Create an example project" from the "Pre-fill project" option. The example project contains + several examples of tags and references. .. _a_references_metadata: @@ -31,14 +31,15 @@ documents, not the documents themselves. See :ref:`a_struct_heads` for more deta metadata is also associated with headings, and not the documents directly. 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. +However, there are several benefits to using documents at a larger structural scale when first +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, -you need to assign it a tag. +You can do the same with your notes. You can treat each heading as an independent element of your +notes that can be referenced somewhere else. That way you can collect all your minor or background +characters in a single note file, and still be able to reference them individually by separating +them with headings and assigning each a tag. .. _a_references_tags: @@ -51,7 +52,7 @@ by using the ``@tag`` :term:`keyword`. The basic format of a tag is ``@tag: tagName``. -The full format of a tag is ``@tag: tagName | displayName``. +An alternative format of a tag is ``@tag: tagName | displayName``. ``tagName`` (Required) This is a unique identifier of your choosing. It is the value you use later for making @@ -59,21 +60,21 @@ The full format of a tag is ``@tag: tagName | displayName``. ``displayName`` (Optional) This is an optional display name used for the tag. When you build your manuscript, you can for - instance insert the point of view character name into chapter headings. By default, the - ``tagName`` value is used in headings, but if you use a shortened format internally in your + instance insert the point of view character name directly into chapter headings. By default, the + ``tagName`` value is used in such headings, but if you use a shortened format internally in your project, you can use this to specify a more suitable format for your manuscript headings. -You can only set *one* tag per heading, and the tag has to be unique across *all* documents in the -project. +You can only set **one** tag per heading, and the tag has to be unique across **all** documents in +the project. After a tag has been defined, it can be referenced in novel documents, or cross-referenced in other -notes. Tags will also show up in the :guilabel:`Outline View` and in the back-reference panel when -a document is opened in the viewer. +notes. Tags will also show up in the :guilabel:`Outline View` and in the references panel under the +document viewer when a document is open in the viewer. 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. +to date. An invalid tag should have a green wiggly line under it, and will not receive the colour +that valid tags do. The tag is the only part of these notes that novelWriter uses. The rest of the document content is there for you to use in whatever way you wish. Of course, the content of the documents can be added diff --git a/source/docs/project_structure.rst b/source/docs/project_structure.rst index 7787d78..0763fed 100644 --- a/source/docs/project_structure.rst +++ b/source/docs/project_structure.rst @@ -7,10 +7,11 @@ Novel Structure 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. +:guilabel:`Project Notes`. Active 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, where they +become inactive. -The :guilabel:`Project Tree` can distinguish between the different header levels of the novel +The :guilabel:`Project Tree` can distinguish between the different heading levels of the novel documents using coloured icons, and optionally add emphasis on the label, set in :guilabel:`Preferences`. @@ -27,47 +28,47 @@ Four levels of headings are supported, signified by the number of hashes (``#``) 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 heading 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` for more details. -The syntax for the four basic header types, and the two special header types, is listed in section +The syntax for the four basic heading types, and the two special types, is listed in section :ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows: -**Header Level 1: Partition** - This header level signifies that the text refers to a top level partition. This is useful when +**Heading Level 1: Partition** + This heading level signifies that the text refers to a top level partition. This is useful when you want to split the manuscript up into books, parts, or acts. These headings are not required. - The novel title itself should use the special header level ``#!`` covered in :ref:`a_fmt_head`. + The novel title itself should use the special heading level ``#!`` covered in :ref:`a_fmt_head`. -**Header Level 2: Chapter** - This header level signifies a chapter level partition. Each time you want to start a new +**Heading Level 2: Chapter** + This heading level signifies a chapter level partition. Each time you want to start a new chapter, you must add such a heading. If you choose to split your manuscript up into one document per scene, you need a single chapter document with just the heading. You can of course also add a synopsis and reference keywords to the chapter document. If you want to open the chapter with a quote or other introductory text that isn't part of a scene, this is also where you'd put that text. -**Header Level 3: Scene** - This header level signifies a scene level partition. You must provide a title text, but the +**Heading Level 3: Scene** + This heading level signifies a scene level partition. You must provide a title text, but the title text can be replaced with a scene separator or just skipped entirely when you build your manuscript. -**Header Level 4: Section** - This header level signifies a sub-scene level partition, usually called a "section" in the +**Heading Level 4: Section** + This heading level signifies a sub-scene level partition, usually called a "section" in the documentation and the user interface. These can be useful if you want to change references mid-scene, like if you change the point-of-view character. You are free to use sections as you wish, and you can filter them out of the final manuscript just like with scene titles. -Page breaks are automatically added before level 1 and 2 headers when you build your project to a -format that supports page breaks, or when you print the document directly from the -:guilabel:`Manuscript Build` tool. If you want page breaks in other places, you have to specify -them manually. See :ref:`a_fmt_break`. +Page breaks are automatically added before partition and chapter headings when you build your +project to a format that supports page breaks. If you want page breaks in other places, you have to +specify them manually. See :ref:`a_fmt_break`. .. tip:: - There are multiple options of how to process novel titles when building the manuscript. For + There are multiple options of how to process novel headings when building the manuscript. For instance, chapter numbers can be applied automatically, and so can scene numbers if you want - them in a draft manuscript. See the :ref:`a_manuscript` page for more details. + them in a draft manuscript. You can also insert point-of-view character names in chapter titles. + See the :ref:`a_manuscript` page for more details. .. _a_struct_heads_title: @@ -76,17 +77,21 @@ Novel Title and Front Matter ---------------------------- It is recommended that you add a document at the very top of each Novel root folder with the novel -title as the first line. You should modify the level 1 header format code with an ``!`` in order to -render it as a document title that is excluded from any automatic Table of Content in a manuscript -build document, like so: +title as the first line. You should modify the level 1 heading format code with an ``!`` in order +to render it as a document title that is excluded from any automatic Table of Content in a +manuscript build document, like so: -``#! My Novel`` +.. code-block:: md + + #! My Novel + + >> _by Jane Doe_ << The title is by default centred on the page. You can add more text to the page as you wish, like for instance the author's name and details. If you want an additional page of text after the title page, starting on a fresh page, you can add -``[NEW PAGE]`` on a line by itself, and continue the text after it. This will insert a page break +``[new page]`` on a line by itself, and continue the text after it. This will insert a page break before the text. See also :ref:`a_fmt_break`. @@ -96,15 +101,19 @@ Unnumbered Chapter Headings --------------------------- If you use the automatic numbering feature for your chapters, but you want to keep some special -chapters separate from this, you cam add an ``!`` to the level 2 header formatting code to tell the -build tool to skip these chapters. +chapters separate from this, you can add an ``!`` to the level 2 heading formatting code to tell +the build tool to skip these chapters. + +.. code-block:: md + + ##! Unnumbered Chapter Title -``##! Unnumbered Chapter Title`` + Chapter Text -There is a separate formatting feature for such chapters in the :guilabel:`Manuscript Build` tool -as well. See the :ref:`a_manuscript` page for more details. When building a document of a format -that supports page breaks, also unnumbered chapters will have a page break added just like for -normal chapters. +There is a separate formatting feature for such chapter titles in the :guilabel:`Manuscript Build` +tool as well. See the :ref:`a_manuscript` page for more details. When building a document of a +format that supports page breaks, also unnumbered chapters will have a page break added just like +for normal chapters. .. Note:: Previously, you could also disable the automatic numbering of a chapter by adding an ``*`` as diff --git a/source/docs/tech_storage.rst b/source/docs/tech_storage.rst index 66a8b12..7fb9d39 100644 --- a/source/docs/tech_storage.rst +++ b/source/docs/tech_storage.rst @@ -33,7 +33,7 @@ itself. It is important to keep this file backed up, either through the built-in your own backup solution. The project XML file is indent-formatted, and is suitable for diff tools and version control since -most of the file will stay static, although a timesetamp is set in the meta section on line 2, and +most of the file will stay static, although a timestamp is set in the meta section on line 2, and various meta data entries incremented, on each save. .. only:: not html @@ -91,11 +91,6 @@ If successful, the old data file is then removed, and the temporary file replace that the previously saved data is only replaced when the new data has been successfully saved to the storage medium. -For the project XML file, a ``.bak`` file is in addition kept, which will always contain the -previous version of the file, although when auto-save is enabled, they may have the same content. -If the opening of a project file fails, novelWriter will automatically try to open the ``.bak`` -file instead. - Project Meta Data ================= diff --git a/source/docs/usage_breakdown.rst b/source/docs/usage_breakdown.rst index ddfd5b9..c0f1496 100644 --- a/source/docs/usage_breakdown.rst +++ b/source/docs/usage_breakdown.rst @@ -10,7 +10,7 @@ How it Works 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. +this documentation these features will be covered in more detail. .. _a_breakdown_design: @@ -23,6 +23,8 @@ 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. +Still, a small formatting toolbar can be popped out by clicking the three dots in the header of the +document editor to give quick access to standard formatting codes. 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 @@ -31,7 +33,8 @@ them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` cha .. 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. + Formatting is limited to headings, in-line basic text formats, text alignment, and a few other + simple features. 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 @@ -54,18 +57,18 @@ When in :guilabel:`Project Tree View` mode, the main work area of the main windo 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. +An optional third panel on the right side 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 if you need to check that the +formatting tags behave as you expected. 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 interface elements other than the document editor itself are hidden away. -Novel Tree and Editor View +Novel View and Editor View -------------------------- .. figure:: images/fig_novel_tree_view.png @@ -81,17 +84,17 @@ Each heading is indented according to the heading level. You can open and edit y from this view as well. All headings contained in the currently open document should be highlighted in the view to indicate which ones belong together in the same document. -If you have multiple Novel root folders, the header of the novel view becomes a dropdown box. You -can then switch between them by clicking the :guilabel:`Outline of ...` text. You can also click -the novel icon button next to it. +If you have multiple "Novel" type root folders, the header of the novel view becomes a dropdown +box. You can then switch between them by clicking the :guilabel:`Outline of ...` text. You can also +click the novel icon button next to it. Generally, the novel view should update when you make changes to the novel structure, including edits of the current document in the editor. The information is only updated when the automatic save of the document is 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. +view by pressing the refresh button in the novel view header. -It is possible to show an optional third column in the novel view, The settings are available from +It is possible to show an optional third column in the novel view. The settings are available from the menu button in the toolbar. If you click the arrow icon to the right of each item, a tooltip will pop out showing you all the @@ -123,12 +126,12 @@ neutral colours from :guilabel:`Preferences`. Other colour themes are also avail 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 -more options to choose from for the editor and viewer. +separate colour selectable from the "Document colour theme" setting in :guilabel:`Preferences`. +They are separated because there are a lot more options to choose from for the editor and viewer. .. note:: - If you switch to dark mode on the GUI, you should also switch editor theme to match, otherwise - icons may be hard to see in the editor and viewer. + If you switch between light and dark mode on the GUI, you should also switch editor theme to + match, otherwise icons may be hard to see in the editor and viewer. .. _a_breakdown_project: @@ -147,7 +150,7 @@ within those documents. .. figure:: images/fig_header_levels.png - An illustration of how header levels correspond to the novel structure. + An illustration of how heading levels correspond to the novel structure. The four heading levels (**H1** to **H4**) are treated as follows: @@ -158,8 +161,8 @@ The four heading levels (**H1** to **H4**) are treated as follows: The project tree will select an icon for the document based on the first heading in it. -This header level structure is only taken into account for :term:`novel documents`. For -:term:`project notes`, the header levels have no structural meaning, and you are free to use them +This heading level structure is only taken into account for :term:`novel documents`. For +:term:`project notes`, the heading levels have no structural meaning, and you are free to use them however you want. See :ref:`a_struct` and :ref:`a_references` for more details. .. versionadded:: 2.0 @@ -171,8 +174,8 @@ however you want. See :ref:`a_struct` and :ref:`a_references` for more details. .. _a_breakdown_export: -Building the Manuscript -======================= +Building a Manuscript +===================== The project can at any time be assembled into a range of different formats through the :guilabel:`Build Manuscript` tool. Natively, novelWriter supports `Open Document`_, HTML5, and @@ -217,8 +220,8 @@ Secondly, having multiple small files means it is very easy to synchronise them 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. +used for the files are well suited. All the JSON documents have line breaks and indents as well, +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 diff --git a/source/docs/usage_format.rst b/source/docs/usage_format.rst index a33e126..9c4bf73 100644 --- a/source/docs/usage_format.rst +++ b/source/docs/usage_format.rst @@ -6,8 +6,8 @@ Formatting Your Text The novelWriter text editor is a plain text editor that uses formatting codes for setting meta data values and allowing for some text formatting. The syntax is based on Markdown, but novelWriter is -*not* a Markdown editor. It supports basic formatting like emphasis (italic), strong importance -(bold) and strike through text, as well as four levels of headings. Form some further complex +**not** a Markdown editor. It supports basic formatting like emphasis (italic), strong importance +(bold) and strike through text, as well as four levels of headings. For some further complex formatting needs, a set of shortcodes can be used. In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a set of @@ -30,7 +30,7 @@ dialogue in your text. An example of the colour highlighting of references. "Bob" is not defined, and "@blabla" is not a valid reference type. -When you use the commands to set tags and references, these also change colour. Correct commands +When you use the keywords to set tags and references, these also change colour. Correct keywords have a distinct colour, and the references themselves will get a colour if they are valid. Invalid references will get a squiggly error line underneath. The same applies to duplicate tags. @@ -45,7 +45,7 @@ Headings .. figure:: images/fig_header_levels.png - An illustration of how header levels correspond to the novel structure. + An illustration of how heading levels correspond to the novel structure. Four levels of headings are allowed. For :term:`project notes`, they are free to be used as you see fit. That is, novelWriter doesn't assign the different headings any particular meaning. However, @@ -53,28 +53,28 @@ for :term:`novel documents` they indicate the structural level of the novel and correctly to produce the intended result. See :ref:`a_struct_heads` for more details. ``# Title Text`` - Heading level one. For novel documents, the header level indicates the start of a new partition. + Heading level one. For novel documents, the level indicates the start of a new partition. ``## Title Text`` - Heading level two. For novel documents, the header level indicates the start of a new chapter. - Chapter numbers can be inserted automatically when building the manuscript. + Heading level two. For novel documents, the level indicates the start of a new chapter. Chapter + numbers can be inserted automatically when building the manuscript. ``### Title Text`` - Heading level three. For novel documents, the header level indicates the start of a new scene. - Scene numbers or scene separators can be inserted automatically when building the manuscript, - so you can use the title field as a working title for your scenes if you wish. + Heading level three. For novel documents, the level indicates the start of a new scene. Scene + numbers or scene separators can be inserted automatically when building the manuscript, so you + can use the title field as a working title for your scenes if you wish. ``#### 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 ignored completely when building the manuscript. + Heading level four. For novel documents, the level indicates the start of a new section. 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: +For headings level one and two, adding a ``!`` modifies its meaning: ``#! Title Text`` - This tells the build tool that the level one heading is intended to be used for the novel's - main title, like for instance on the front page. When building the manuscript, this will use a - different styling and will exclude the title from, for instance, a Table of Contents in Libre - Office. + This tells the build tool that the level one heading is intended to be used for the novel's or + notes folder's main title, like for instance on the front page. When building the manuscript, + this will use a different styling and will exclude the title from, for instance, a Table of + Contents in Libre Office. ``##! Title Text`` This tells the build tool to not assign a chapter number to this chapter title if automatic @@ -99,10 +99,10 @@ In addition, the editor supports a few additional types of white spaces: * A non-breaking space can be inserted with :kbd:`Ctrl+K`, :kbd:`Space`. * Thin spaces are also supported, and can be inserted with :kbd:`Ctrl+K`, :kbd:`Shift+Space`. -* Non-breaking thin space can be inserted with :kbd:`Ctrl+K`, :kbd:`Ctrl+Space`. +* Non-breaking thin space can be inserted with :kbd:`Ctrl+K`, :kbd:`Ctrl+Space`. -These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed -in :ref:`a_kb_ins`. +These are all insert features, and the :guilabel:`Insert` menu has more. The keyboard shortcuts for +them are also listed in :ref:`a_kb_ins`. Non-breaking spaces are highlighted by the syntax highlighter with an alternate coloured background, depending on the selected theme. @@ -118,7 +118,7 @@ background, depending on the selected theme. Text Emphasis ============= -A minimal set of text emphasis styles are supported for text paragraphs. +A minimal set of Markdown text emphasis styles are supported for text paragraphs. ``_text_`` The text is rendered as emphasised text (italicised). @@ -141,7 +141,7 @@ In addition, the following rules apply: tag itself. That is, ``**text**`` is valid, ``**text **`` is not. 2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in bold** here`` is valid, ``some** text in bold** here`` is not. -3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the *inner* +3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the **inner** wrapper. This is due to the underscore also being a valid word character, so if they are on the outside, they violate rule 2. 4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or @@ -214,9 +214,10 @@ indicate this by altering the colour of the word. document of the whole project. ``%Short: text ...`` - This is a short description comment. It is identical to the synopsis comment, but is intended to - be used for project notes. The text shows up in the Reference panel below the document viewer in - the last column labelled :guilabel:`Short Description`. + This is a short description comment. It is identical to the synopsis comment (they are + interchangeable), but is intended to be used for project notes. The text shows up in the + Reference panel below the document viewer in the last column labelled + :guilabel:`Short Description`. .. note:: Only one comment can be flagged as a synopsis or short comment for each heading. If multiple @@ -232,11 +233,11 @@ Tags and References The document editor supports a set of keywords used for setting tags, and making references between documents. -Tags use the command ``@tag:`` to define a tag. The tag can be set once per section defined by a +Tags use the keyword ``@tag:`` to define a tag. The tag can be set once per section defined by a heading. Setting it multiple times under the same heading will just override the previous setting. ``@tag: value`` - A tag command followed by the tag value, like for instance the name of a character. + A tag keyword followed by the tag value, like for instance the name of a character. References can be set anywhere within a section, and are collected according to their category. References are in the form: @@ -282,7 +283,7 @@ Examples: .. note:: The text editor will not show the alignment and indentation live. But the viewer will show them when you open the document there. It will of course also be reflected in the document generated - from the build tool as long as the format supports paragraph alignment. + from the manuscript build tool as long as the format supports paragraph alignment. .. _a_fmt_break: @@ -290,37 +291,37 @@ Examples: Vertical Space and Page Breaks ============================== -Adding more than one line break between paragraphs will *not* increase the space between those +Adding more than one line break between paragraphs will **not** increase the space between those paragraphs when building the project. To add additional space between paragraphs, add the text -``[VSPACE]`` on a line of its own, and the build tool will insert a blank paragraph in its place. +``[vspace]`` on a line of its own, and the build tool will insert a blank paragraph in its place. If you need multiple blank paragraphs just add a colon and a number to the above code. For -instance, writing ``[VSPACE:3]`` will insert three blank paragraphs. +instance, writing ``[vspace:3]`` will insert three blank paragraphs. -Normally, the build tool will insert a page break before all headers of level one and for all -headers of level two for novel documents, i.e. chapters, but not for project notes. +Normally, the manuscript build tool will insert a page break before all headings of level one and +for all headings of level two for novel documents, i.e. chapters, but not for project notes. -If you need to add a page break somewhere else, put the text ``[NEW PAGE]`` on a line by itself +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. 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 - to the text when exporting to HTML or Open Document. This means that a ``[NEW PAGE]`` which has + to the text when exporting to HTML or Open Document. This means that a ``[new page]`` which has no text following it, it will not result in a page break. **Example:** -.. code-block:: markdown +.. code-block:: md This is a text paragraph. - [VSPACE:2] + [vspace:2] This is another text paragraph, but there will be two empty paragraphs in-between them. - [NEWPAGE] + [new page] This text will always start on a new page if the build format has pages. diff --git a/source/docs/usage_project.rst b/source/docs/usage_project.rst index 8e4c12d..76bccb4 100644 --- a/source/docs/usage_project.rst +++ b/source/docs/usage_project.rst @@ -86,7 +86,7 @@ Splitting Documents The :guilabel:`Split Document` dialog. -The :guilabel:`Split Document by Header` option will open a dialog that allows you to split the +The :guilabel:`Split Document by Heading` option will open a dialog that allows you to split the 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. @@ -94,7 +94,7 @@ 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. @@ -123,16 +123,16 @@ Document Importance and Status ------------------------------ Each document or folder in your project can have either a "Status" or "Importance" flag set. These -are flags that you control and define yourself. novelWriter doesn't do anything with them at all. -To modify the labels, go to their respective tabs in :guilabel:`Project Settings`. +are flags that you control and define yourself, and novelWriter doesn't use them for anything. To +modify the labels, go to their respective tabs in :guilabel:`Project Settings`. The "Status" flag is intended to tag a :term:`novel document` as for instance a draft or as completed, and the "Importance" flag is intended to tag character notes, or other :term:`project notes`, as for instance a main, major, or minor character 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 -"Importance" flag. Some folders, like :guilabel:`Trash` and :guilabel:`Archive` allow both. +lives in. If it's in a Novel type folder, it uses the "Status" flag, otherwise it uses an +"Importance" flag. .. _a_ui_tree_dnd: @@ -155,32 +155,31 @@ interface framework novelWriter is built upon. Documents and their folders can be rearranged freely within their root folders. If you move a Novel 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 -you move it back at some point. +between all root folders, but keep in mind that if you move a note into a Novel type root folder, +its "Importance" setting will be switched with a "Status" setting. See :ref:`a_ui_tree_status`. The +old value will not be overwritten though, and should be restored if you move it back at some point. Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them, you can move them up or down with respect to each other from the arrow buttons at the top of the -project tree, or by pressing :kbd:`Ctrl+Shift+Up` or :kbd:`Ctrl+Shift+Down` when they are selected. +project tree, or by pressing :kbd:`Ctrl+Up` or :kbd:`Ctrl+Down` when they are selected. .. _a_ui_tree_novel: -The Novel Tree -============== +The Novel Tree View +=================== .. figure:: images/fig_novel_tree_view.png A screenshot of the Novel Tree View. -An alternative way to view the project structure is the novel tree. You can switch to this view by -selecting the :guilabel:`Novel Tree View` button in the sidebar. This view is a simplified version -of the view in the :guilabel:`Outline View`. It is convenient when you want to browse the structure +An alternative way to view the project structure is the novel view. You can switch to this view by +selecting the :guilabel:`Novel View` button in the sidebar. This view is a simplified version of +the view in the :guilabel:`Outline View`. It is convenient when you want to browse the structure of the story itself rather than the document files. .. note:: - You cannot reorganise the entries in the novel tree, or add any new documents, as that would + You cannot reorganise the entries in the novel view, 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 when the document is saved. @@ -188,17 +187,17 @@ of the story itself rather than the document files. .. _a_ui_outline: -Project Outline View -==================== +The Novel Outline View +====================== .. figure:: images/fig_outline_view.png A screenshot of the Novel Outline View. -The project's :guilabel:`Outline View` is available as another view option from the sidebar. The -outline provides an overview of the novel structure, displaying a tree hierarchy of the elements of -the novel, that is, the level 1 to 4 headings representing partitions, chapters, scenes and -sections. +The project's :guilabel:`Novel Outline View` is available as another view option from the sidebar. +The outline provides an overview of the novel structure, displaying a tree hierarchy of the +elements of the novel, that is, the level 1 to 4 headings representing partitions, chapters, scenes +and sections. The document containing the heading can also be displayed as a separate column, as well as the line number where the heading is defined. Double-clicking an entry will open the corresponding document diff --git a/source/docs/usage_shortcuts.rst b/source/docs/usage_shortcuts.rst index 8c9fb8c..af54254 100644 --- a/source/docs/usage_shortcuts.rst +++ b/source/docs/usage_shortcuts.rst @@ -23,14 +23,14 @@ Main Window Shortcuts ":kbd:`F5`", "Open the :guilabel:`Build Manuscript` tool" ":kbd:`F6`", "Open the :guilabel:`Writing Statistics` tool" ":kbd:`F8`", "Toggle :guilabel:`Focus Mode`" - ":kbd:`F9`", "Re-build the project index" + ":kbd:`F9`", "Re-build the project's index" ":kbd:`F11`", "Toggle full screen mode" ":kbd:`Ctrl+,`", "Open the :guilabel:`Preferences` dialog" ":kbd:`Ctrl+E`", "Switch focus to the document editor" - ":kbd:`Ctrl+T`", "Switch focus to the project/novel tree" + ":kbd:`Ctrl+T`", "Switch or toggle focus for the project tree or novel view" ":kbd:`Ctrl+Q`", "Exit novelWriter" ":kbd:`Ctrl+Shift+,`", "Open the :guilabel:`Project Settings` dialog" - ":kbd:`Ctrl+Shift+O`", "Open a project" + ":kbd:`Ctrl+Shift+O`", "Open the Welcome dialog to open or create a project" ":kbd:`Ctrl+Shift+S`", "Save the current project" ":kbd:`Ctrl+Shift+T`", "Switch focus to the outline view" ":kbd:`Ctrl+Shift+W`", "Close the current project" @@ -55,12 +55,11 @@ Project Tree Shortcuts ":kbd:`Ctrl+.`", "Open the context menu on the selected item" ":kbd:`Ctrl+L`", "Open the :guilabel:`Quick Links` menu" ":kbd:`Ctrl+N`", "Open the :guilabel:`Create New Item` menu" - ":kbd:`Ctrl+O`", "Open selected document" + ":kbd:`Ctrl+O`", "Open the selected document in the editor" ":kbd:`Ctrl+R`", "Open the selected document in the viewer" ":kbd:`Ctrl+Up`", "Move selected item one step up in the tree" ":kbd:`Ctrl+Down`", "Move selected item one step down in the tree" ":kbd:`Ctrl+Shift+Del`", "Move the selected item to Trash" - ":kbd:`Ctrl+Shift+Z`", "Undo the last move of a project item, if possible" .. _a_kb_editor: @@ -92,21 +91,22 @@ Text Formatting Shortcuts ":kbd:`Ctrl+'`", "Wrap selected text, or word under cursor, in single quotes" ":kbd:`Ctrl+""`", "Wrap selected text, or word under cursor, in double quotes" - ":kbd:`Ctrl+/`", "Toggle block format as comment" - ":kbd:`Ctrl+0`", "Remove block formatting for block under cursor" - ":kbd:`Ctrl+1`", "Change block format to header level 1" - ":kbd:`Ctrl+2`", "Change block format to header level 2" - ":kbd:`Ctrl+3`", "Change block format to header level 3" - ":kbd:`Ctrl+4`", "Change block format to header level 4" + ":kbd:`Ctrl+/`", "Toggle block format as comment for block under cursor, or selected text" + ":kbd:`Ctrl+0`", "Remove block formatting for block under cursor, or selected text" + ":kbd:`Ctrl+1`", "Change block format to heading level 1" + ":kbd:`Ctrl+2`", "Change block format to heading level 2" + ":kbd:`Ctrl+3`", "Change block format to heading level 3" + ":kbd:`Ctrl+4`", "Change block format to heading level 4" ":kbd:`Ctrl+5`", "Change block alignment to left-aligned" ":kbd:`Ctrl+6`", "Change block alignment to centred" ":kbd:`Ctrl+7`", "Change block alignment to right-aligned" ":kbd:`Ctrl+8`", "Add a left margin to the block" ":kbd:`Ctrl+9`", "Add a right margin to the block" ":kbd:`Ctrl+B`", "Format selected text, or word under cursor, with strong emphasis (bold)" - ":kbd:`Ctrl+D`", "Strike through selected text, or word under cursor" + ":kbd:`Ctrl+D`", "Format selected text, or word under cursor, with strike through" ":kbd:`Ctrl+I`", "Format selected text, or word under cursor, with emphasis (italic)" - ":kbd:`Ctrl+Shift+/`", "Remove block formatting for block under cursor" + ":kbd:`Ctrl+Shift+/`", "Remove block formatting for block under cursor, or selected text" + ":kbd:`Ctrl+Shift+D`", "Toggle block format as ignored text for block under cursor, or selected text" Other Editor Shortcuts @@ -115,7 +115,7 @@ Other Editor Shortcuts .. csv-table:: :header: "Shortcut", "Description" - ":kbd:`F7`", "Re-run the spell checker" + ":kbd:`F7`", "Re-run the spell checker on the document" ":kbd:`Ctrl+.`", "Open the context menu at the current cursor location" ":kbd:`Ctrl+A`", "Select all text in the document" ":kbd:`Ctrl+C`", "Copy selected text to clipboard" @@ -132,7 +132,6 @@ Other Editor Shortcuts ":kbd:`Ctrl+F7`", "Toggle spell checking" ":kbd:`Ctrl+Return`", "Open the tag or reference under the cursor in the viewer" ":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph" - ":kbd:`Ctrl+Shift+I`", "Import text to the current document from a text file" .. _a_kb_ins: diff --git a/source/docs/usage_writing.rst b/source/docs/usage_writing.rst index 2579232..d9d6400 100644 --- a/source/docs/usage_writing.rst +++ b/source/docs/usage_writing.rst @@ -42,13 +42,12 @@ the label and pressing :kbd:`Ctrl+Return`. You can also control-click them with Editor Auto-Completer --------------------- -If you type the character ``@`` on a new line, a context menu will appear showing the different -available keywords. The list will shorten as you type. Once a keyword command has been selected or -typed, the editor may suggest further content based on your project content. See -:ref:`a_references_completer` for more details. +If you type the character ``@`` on a new line, a menu will appear showing the different available +keywords. The list will shorten as you type. Once a keyword command has been selected or typed, the +editor may suggest further content based on your project content. See :ref:`a_references_completer` +for more details. .. versionadded:: 2.2 - The auto-completer feature was added. .. _a_ui_view: diff --git a/source/settings.json b/source/settings.json index 5522fe1..0119d46 100644 --- a/source/settings.json +++ b/source/settings.json @@ -1,3 +1,3 @@ { - "docVersion": "2.2.1" + "docVersion": "2.3" } \ No newline at end of file