diff --git a/docs/source/images/fig_build_build.png b/docs/source/images/fig_build_build.png index 72650672..8c509d57 100644 Binary files a/docs/source/images/fig_build_build.png and b/docs/source/images/fig_build_build.png differ diff --git a/docs/source/images/fig_build_settings_headings.png b/docs/source/images/fig_build_settings_headings.png index 4eb54c5e..d5219361 100644 Binary files a/docs/source/images/fig_build_settings_headings.png and b/docs/source/images/fig_build_settings_headings.png differ diff --git a/docs/source/images/fig_build_settings_selections.png b/docs/source/images/fig_build_settings_selections.png index 9dc82d49..c9b4cb91 100644 Binary files a/docs/source/images/fig_build_settings_selections.png and b/docs/source/images/fig_build_settings_selections.png differ diff --git a/docs/source/images/fig_manuscript_build.png b/docs/source/images/fig_manuscript_build.png index 8a3e1ae8..31605cd4 100644 Binary files a/docs/source/images/fig_manuscript_build.png and b/docs/source/images/fig_manuscript_build.png differ diff --git a/docs/source/images/fig_welcome.jpg b/docs/source/images/fig_welcome.jpg new file mode 100644 index 00000000..7bcde450 Binary files /dev/null and b/docs/source/images/fig_welcome.jpg differ diff --git a/docs/source/project_manuscript.rst b/docs/source/project_manuscript.rst index 0818e864..91af6245 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 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/docs/source/project_overview.rst b/docs/source/project_overview.rst index 4429df4a..d546992f 100644 --- a/docs/source/project_overview.rst +++ b/docs/source/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/docs/source/project_references.rst b/docs/source/project_references.rst index 95f1f2d9..cdd29536 100644 --- a/docs/source/project_references.rst +++ b/docs/source/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/docs/source/project_structure.rst b/docs/source/project_structure.rst index 7787d784..0763fed7 100644 --- a/docs/source/project_structure.rst +++ b/docs/source/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. -``##! Unnumbered Chapter Title`` +.. code-block:: md -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. + ##! Unnumbered Chapter Title + + Chapter Text + +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