From acfef7b4cb805c7d359e714a68b2474044e57d25 Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Sun, 25 May 2025 18:56:11 +0200 Subject: [PATCH] Clean up the "Getting Started" section --- docs/source/more/project_format.rst | 4 +- docs/source/technical/source.rst | 10 +-- docs/source/usage/advanced_formatting.rst | 41 ++++++----- docs/source/usage/alignment_and_indent.rst | 4 +- docs/source/usage/basic_formatting.rst | 10 +-- docs/source/usage/chapters_and_scenes.rst | 35 ++++----- docs/source/usage/comments.rst | 19 ++--- docs/source/usage/front_back_matter.rst | 4 +- docs/source/usage/introduction.rst | 20 +++--- docs/source/usage/organising_project.rst | 84 +++++++++++----------- docs/source/usage/tags_and_references.rst | 40 ++++++----- docs/source/user_interface/main_window.rst | 4 ++ docs/source/user_interface/manuscript.rst | 4 +- 13 files changed, 144 insertions(+), 135 deletions(-) diff --git a/docs/source/more/project_format.rst b/docs/source/more/project_format.rst index b002eba9..5f8be823 100644 --- a/docs/source/more/project_format.rst +++ b/docs/source/more/project_format.rst @@ -72,7 +72,7 @@ should be used only a few places in any given project. These are as follows: * The formatting of the level one title on the title page must be changed from ``# Title Text`` to ``#! Title Text`` in order to retain the previous functionality. - See :ref:`docs_usage_headers_levels`. + See :ref:`docs_usage_headings_levels`. * Any text that was previously centred on the page must be manually centred using the text alignment feature. See :ref:`docs_usage_align_indent`. @@ -81,7 +81,7 @@ should be used only a few places in any given project. These are as follows: * Since the specific layout for unnumbered chapters has been dropped, such chapters must all use the ``##! Chapter Name`` formatting code instead of ``## Chapter Name``. This also includes chapters marked by an asterisk: ``## *Chapter Name``, as this feature has also been dropped. - See :ref:`docs_usage_headers_levels`. + See :ref:`docs_usage_headings_levels`. **Plain Pages** diff --git a/docs/source/technical/source.rst b/docs/source/technical/source.rst index 2e9f0bbd..c4903e7c 100644 --- a/docs/source/technical/source.rst +++ b/docs/source/technical/source.rst @@ -25,7 +25,7 @@ by running: python pkgutils.py help -.. _a_source_depend: +.. _docs_technical_source_depend: Dependencies ============ @@ -56,7 +56,7 @@ source, dependencies can still be installed from PyPi with: case on for instance Arch Linux. -.. _a_source_install: +.. _docs_technical_source_install: Build and Install from Source ============================= @@ -89,7 +89,7 @@ different: pip install --user dist/novelWriter-2.0.7-py3-none-any.whl -.. _a_source_i18n: +.. _docs_technical_source_i18n: Building the Translation Files ============================== @@ -114,7 +114,7 @@ needed package is called ``qttools5-dev-tools``. in the ``i18n`` folder of the source code. -.. _a_source_sample: +.. _docs_technical_source_sample: Building the Example Project ============================ @@ -128,7 +128,7 @@ running: python pkgutils.py sample -.. _a_source_docs: +.. _docs_technical_source_docs: Building the Documentation ========================== diff --git a/docs/source/usage/advanced_formatting.rst b/docs/source/usage/advanced_formatting.rst index 807a175c..557db1a7 100644 --- a/docs/source/usage/advanced_formatting.rst +++ b/docs/source/usage/advanced_formatting.rst @@ -4,9 +4,9 @@ Advanced Formatting ******************* -Markdown formatting is somewhat limited by default, so novelWriter has some additional formatting -codes for common use cases. These codes are all based on brackets, and some allow an additional -value after a colon. +Standard Markdown formatting is somewhat limited, so novelWriter has some additional formatting +codes for special use cases. These codes are all based on brackets, and some allow an additional +value to be set after a colon. This section covers all these formatting codes. @@ -17,10 +17,11 @@ Formatting with Shortcodes ========================== For basic formatting, like emphasis, you should use the standard Markdown style formatting tags -descried in :ref:`docs_usage_basics_emphasis`. +descried in :ref:`docs_usage_basics_emphasis` whenever possible. For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes -that wrap the section of text to be formatted. Shortcodes can overlap and intersect. +that wrap the section of text to be formatted. Shortcodes can be nested to apply multiple formats +to the same piece of text. These shortcodes are intended for special formatting cases, or more complex cases that cannot be solved with simple Markdown-like formatting codes. Available shortcodes are listed below. @@ -30,13 +31,13 @@ solved with simple Markdown-like formatting codes. Available shortcodes are list :widths: 40, 60 :class: "tight-table" - "``[b]text[/b]``", "Text is rendered as bold text." - "``[i]text[/i]``", "Text is rendered as italicised text." - "``[s]text[/s]``", "Text is rendered as strike through text." - "``[u]text[/u]``", "Text is rendered as underlined text." - "``[m]text[/m]``", "Text is rendered as highlighted text." - "``[sup]text[/sup]``", "Text is rendered as superscript text." - "``[sub]text[/sub]``", "Text is rendered as subscript text." + "``[b]text[/b]``", "Text is displayed as bold text." + "``[i]text[/i]``", "Text is displayed as italicised text." + "``[s]text[/s]``", "Text is displayed as strike through text." + "``[u]text[/u]``", "Text is displayed as underlined text." + "``[m]text[/m]``", "Text is displayed as highlighted text." + "``[sup]text[/sup]``", "Text is displayed as superscript text." + "``[sub]text[/sub]``", "Text is displayed as subscript text." "``[footnote:key]``", "A reference to a :ref:`footnote comment `." Unlike Markdown style codes, these can be used anywhere within a paragraph. Even in the middle of a @@ -65,9 +66,9 @@ You can apply page breaks to partition, chapter and scene headings for novel doc places, there are special codes available for this purpose. 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 **Manuscript** tool will insert a blank paragraph in its -place. +paragraphs when generating a manuscript document. To add additional space between paragraphs, add +the text ``[vspace]`` on a line of its own, and the **Manuscript 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. @@ -78,8 +79,8 @@ the text you wish to start on a new page. .. 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 - no text following it, it will not result in a page break. + to the text when exporting to HTML or Open Document. This means that a ``[new page]`` code which + has no text following it will not result in a page break. :bdg-info:`Example` @@ -94,7 +95,7 @@ the text you wish to start on a new page. [new page] - This text will start on a new page if the build format has pages. + This text will start on a new page if the build format supports pages. .. _docs_usage_formatting_counts: @@ -114,7 +115,6 @@ The available codes are: .. csv-table:: Stats Shortcodes :header: "Code", "Description" - :widths: 40, 60 :class: "tight-table" "``[field:allChars]``", "Characters" @@ -132,8 +132,7 @@ The available codes are: :bdg-info:`Example` This is an example cover page. A similar page is automatically generated when you create a new -project. The Word Count uses a "field" shortcode to insert a count of all words in text paragraphs -on the cover page. +project. .. code-block:: md diff --git a/docs/source/usage/alignment_and_indent.rst b/docs/source/usage/alignment_and_indent.rst index 8d94ae5a..2494ea32 100644 --- a/docs/source/usage/alignment_and_indent.rst +++ b/docs/source/usage/alignment_and_indent.rst @@ -40,7 +40,7 @@ from the edge. 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 manuscript build tool as long as the format supports paragraph alignment. + from the **Manuscript Build** tool as long as the format supports paragraph alignment. Alignment with Line Breaks @@ -62,7 +62,7 @@ the entire paragraph. For the following text, all lines will be centred: Alignment with First Line Indent ================================ -If you have first line indent enabled in your Manuscript build settings, you probably want to +If you have first line indent enabled in your manuscript build settings, you probably want to disable it for text in verses. Adding any alignment tags will cause the first line indent to be switched off for that paragraph. diff --git a/docs/source/usage/basic_formatting.rst b/docs/source/usage/basic_formatting.rst index 15b8435f..8a5d59c6 100644 --- a/docs/source/usage/basic_formatting.rst +++ b/docs/source/usage/basic_formatting.rst @@ -9,9 +9,9 @@ Basic Formatting The basic text formatting syntax of novelWriter is based on Markdown_. It is only a subset of the Markdown syntax though. Lists, images, and links are not supported. -URLs in the text should automatically be highlighted and become clickable. However, only URLs -starting with "http" or "https" are recognised. In the editor, you must hold down the :kbd:`Ctrl` -key when clicking a URL to follow it. +That said, URLs in the text should automatically be highlighted and become clickable. However, only +URLs starting with "http" or "https" are recognised. In the editor, you must hold down the +:kbd:`Ctrl` key when clicking a URL to follow it. .. _docs_usage_basics_paragraphs: @@ -25,7 +25,7 @@ paragraph. It is important that you actually follow this rule. You should not, for instance, mimic indented paragraphs manually in the editor. This, and a lot of other formatting options that can be -applied to text paragraphs in the :ref:`Manuscript Tool ` depends on paragraphs +applied to text paragraphs in the :ref:`Manuscript Tool ` depend on paragraphs being separated by blank lines. :bdg-success:`Correct` @@ -85,7 +85,7 @@ In addition, the following rules apply: 4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or paragraphs, you must apply it to each of them in turn. 5. Text emphasis can only be used in comments and paragraphs. Headings and meta data tags don't - allow for formatting, and any formatting markup will be rendered as-is. + allow for formatting, and any formatting markup will be displayed as-is. .. tip:: diff --git a/docs/source/usage/chapters_and_scenes.rst b/docs/source/usage/chapters_and_scenes.rst index e9f9471c..106e2364 100644 --- a/docs/source/usage/chapters_and_scenes.rst +++ b/docs/source/usage/chapters_and_scenes.rst @@ -1,4 +1,4 @@ -.. _docs_usage_headers: +.. _docs_usage_headings: ******************* Chapters and Scenes @@ -8,20 +8,20 @@ Chapters and Scenes Since novelWriter uses a plain text format, the structure of your novel must follow a certain set of simple rules. For documents in a **Novel** type root folder, it is the heading that determines -if it is a Chapter or a Scene document. +if the document is a chapter or a scene. -The formatting of headings is based on Markdown_, and a heading is indicated by a line starting -with the ``#`` character. It accepts from one two four of these. You can use multiple headings in -the same document, but it is the first heading that determines which icon and information is -displayed in the project tree. +The formatting of headings is based on Markdown_. A heading is indicated by a line starting with +one or more ``#`` characters. It accepts up to four of these. You can use multiple headings in the +same document, but it is the first heading that determines which icon and information is displayed +in the project tree. .. note:: - You can use the same headings for your notes in the other root folders, but they aren't - treated as chapters or scenes, so you are free to use them as you want. + You can use the same heading levels for your notes in the other root folders, but they aren't + treated as chapters or scenes, so there you are free to use them as you want. -.. _docs_usage_headers_levels: +.. _docs_usage_headings_levels: Heading Levels ============== @@ -33,12 +33,14 @@ Heading Levels Four levels of headings are understood for novel documents. You can pick and choose from these as you want, but if your story has chapters, you should use these headings to indicate them. If you also add scene headings, you have better control of how your scene separators are formatted in your -manuscript. +manuscript. The chapter and scenes headings are also displayed in the +:ref:`Novel View ` and :ref:`Outline View `. ``# Title Text`` This is a heading level one. This heading indicates the start of a new partition. Partitions are for when you want to split your story into "Part 1", "Part 2", etc. You can also choose to use - them for splitting the text up into acts, and then hide these headings in your manuscript. + them for splitting the text up into acts, and then hide these headings in your manuscript so + that they are not included in the output. ``## Chapter Title`` This is a heading level two. This heading indicates the start of a new chapter. Chapter numbers @@ -58,19 +60,20 @@ manuscript. chunks, or into separate documents. For headings level one through three, adding a ``!`` modifies the meaning of the heading. The -alternative meaning of the heading is only relevant to when you generate your manuscript, but you -may want to keep the use cases in mind while writing. +alternative meaning of the heading is only relevant when you generate your manuscript, but you may +want to keep the use cases in mind while writing. ``#! Title Text`` This tells the **Manuscript Build** tool that the level one heading is intended to be used for the novel or notes folder's main title, like for instance the novel title on the cover page. When building the manuscript, this will use a different styling of the title, which you can modify independently from how partition titles are styled. + See :ref:`docs_usage_front_back_matter_title` for more details. ``##! Chapter Title`` This tells the **Manuscript Build** tool to not assign a chapter number to this chapter title if automatic chapter numbers are enabled. Such titles are useful for prologues and epilogues for - instance. + instance. See :ref:`docs_usage_front_back_matter_unnumbered` for more details. ``###! Scene Title`` This is an alternative scene heading that can be formatted differently in the **Manuscript @@ -84,8 +87,8 @@ documentation. .. note:: - The space after the ``#`` or ``!`` character is mandatory. The syntax highlighter will change - colour and font size when the heading is correctly formatted. + The space after the ``#`` or ``!`` character is mandatory. The editor will change colour and + font size when the heading is correctly formatted. Page breaks can be automatically added before titles, partition, chapter and scene headings from the **Manuscript Build** tool when you build your project to a format that supports page breaks. diff --git a/docs/source/usage/comments.rst b/docs/source/usage/comments.rst index 11bb1e69..426f32b1 100644 --- a/docs/source/usage/comments.rst +++ b/docs/source/usage/comments.rst @@ -8,7 +8,7 @@ You can add comments to your text that are not a part of the story. Regular comm for you to add notes to yourself inside the text, which may be useful when you revise your drafts. However, there are several types of comments you can use. -This section covers the basic comment types. There are a couple of advanced features that sue +This section covers the basic comment types. There are a couple of advanced features that use comment syntax too, but they are covered later. @@ -18,11 +18,12 @@ Plain Comments ============== A plain comment is a line or paragraph that starts with the character ``%`` as its first character. -You can put them wherever you like in your documents, and you can chose to include or exclude them +You can put them wherever you like in your documents, and you can choose to include or exclude them from your manuscript. For the most part, novelWriter completely ignores these comments. They are not included in your -word or character count, and are only displayed in the document viewer panel if you enable them. +word or character counts either, and are only displayed in the document viewer panel if you enable +them. :bdg-info:`Example` @@ -49,9 +50,9 @@ in your manuscript, but they are formatted differently than plain comments. .. note:: - A summary or description comment can only be used once for each heading as they are considered a - description of the content of the text under that heading. If you add two such comments under - the same heading, the last one will be used. + A summary or description comment can be used once, and only once, for each heading as they are + considered a description of the content of the text under that heading. If you add two such + comments under the same heading, the last one will be used. Synopsis @@ -111,9 +112,9 @@ The matching is done with a key that links the two. If you insert a footnote fro menu, a unique key is generated for you. Shortcodes in general are covered in more detail in :ref:`docs_usage_formatting_shortcodes`. -The insert feature will add the footnote shortcode marker at the position of your cursor in the -editor panel, and create the associated footnote comment right after the paragraph. It will then -move the cursor there so you can immediately start typing the footnote text. +The insert footnote feature will add the footnote shortcode marker at the position of your cursor +in the editor panel, and create the associated footnote comment right after the paragraph. It will +then move the cursor there so you can immediately start typing the footnote text. The footnote comment can be anywhere in the document, so if you wish to move them to, say, the bottom of the text, you are free to do so. diff --git a/docs/source/usage/front_back_matter.rst b/docs/source/usage/front_back_matter.rst index a52cd35a..27a0fcbb 100644 --- a/docs/source/usage/front_back_matter.rst +++ b/docs/source/usage/front_back_matter.rst @@ -43,6 +43,9 @@ This is the title page novelWriter generates automatically for a new project as 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. +The default title page inserts the word count for text only, but you can add other counts too. +See :ref:`docs_usage_formatting_counts` for more details. + .. _docs_usage_front_back_matter_pages: @@ -67,7 +70,6 @@ Unnumbered chapters are useful for prologue and epilogue chapters, and also for if you use those in your text. There is a separate formatting feature for such chapter titles in the **Manuscript Build** tool. See the :ref:`docs_ui_manuscript` page for more details. - :bdg-info:`Example` .. code-block:: md diff --git a/docs/source/usage/introduction.rst b/docs/source/usage/introduction.rst index b4f1c9f0..47dceb98 100644 --- a/docs/source/usage/introduction.rst +++ b/docs/source/usage/introduction.rst @@ -25,8 +25,8 @@ It also uses Markdown formatting for defining document headings, which is how yo between chapters and scenes. For those special cases where you need more complex formatting, a set of shortcodes are available. -To make them easier to use, a dropdown button bar is available in the editor panel with standard -format buttons. So don't worry. You don't have to learn any codes. +To make these codes easier to use, a dropdown button bar is available in the editor panel with +standard format buttons. So don't worry. You don't have to learn any of these codes. Adding Meta Data @@ -37,12 +37,12 @@ data into your text documents to indicate things like which characters are prese scene, whose point of view we're seeing, what location the events take place in, and so on. Since the editor is plain text, this is done on special lines of text starting with an ``@`` -character. The editor will show an auto-complete menu when to help you write these lines. We will -talk more about this later. +character. The editor will show an auto-complete menu to help you write these lines. We will talk +more about this later. You can also add your own author's comments in your text, without these comments becoming a part of the story itself. A comment line starts with a ``%`` character. There are different types of -comments too, and an auto-complete menu has suggestions here too. More about this later as well. +comments, and an auto-complete menu can help you here too. More about this later as well. .. admonition:: Limitations @@ -50,8 +50,8 @@ comments too, and an auto-complete menu has suggestions here too. More about thi available are limited to those relevant for this purpose. It is *not* suitable for technical writing. It is also *not* a full-featured Markdown editor. - It is also not intended as a tool for organising 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. It is recommended to use a proper note taking - tool for research. This is anyway more practical as you may use the same research for multiple - projects. + In addition, novelWriter is not intended as a tool for organising research for writing, and + therefore lacks formatting features you may need for this purpose. The notes feature in is + mainly intended for character profiles and plot outlines. It is recommended to use a proper + note-taking tool for research. This is anyway more practical as you may use the same research + for multiple projects. diff --git a/docs/source/usage/organising_project.rst b/docs/source/usage/organising_project.rst index 1475aec3..4c8f1cf4 100644 --- a/docs/source/usage/organising_project.rst +++ b/docs/source/usage/organising_project.rst @@ -13,12 +13,12 @@ side of the main window. The **Project Content** tree populated with example documents. -Each line in the project tree shows the label of each item, its word count (or alternatively -character count), an active/inactive icon (see :ref:`docs_usage_project_active`), and a custom -status icon (see :ref:`docs_usage_project_status`). +Each line in the project tree shows the name of each item, its word count (or alternatively +character count), an icon for :ref:`docs_usage_project_active`, and a custom icon for +:ref:`docs_usage_project_status` of each item. These latter two are covered alter in this section. -You can add, view and edit the documents in the project tree by right-clicking on them. Some -features are also located in the buttons along the top next to the **Project Content** label. +You can add, view and edit documents in the project tree by right-clicking on them. Some features +are also located in the buttons along the top, next to the **Project Content** label. .. _docs_usage_project_roots: @@ -27,7 +27,7 @@ How Root Folders Work ===================== Projects are structured into a set of top level folders called "Root Folders". They are visible in -the project tree at the left side of the main window. +the project tree at the left side of the main window. Each type of root folder has a distinct icon. The documents that make up your story go into a root folder of type **Novel**. Your notes go into the other root folders. These other root folder types are separated into types depending on what @@ -38,7 +38,7 @@ A new project may not have all of the root folders present, but you can add the the project tree tool bar. The intended usage of each type of root folder is listed below. However, aside from the **Novel** -folder, no restrictions are applied by the application on what you put in them. You can use them +folder, no restrictions are applied by novelWriter on what you put in them. You can use them however you want. @@ -51,7 +51,7 @@ Root Folder Types one novel. The Novel folder is somewhat special in that it can contain documents for chapters, scenes and - story partitions. How this is indicated is covered in the section :ref:`docs_usage_headers`. + story partitions. How this is indicated is covered in the section :ref:`docs_usage_headings`. **Plot** (Notes) This is where you can keep notes and outlines of your story plots. Such notes can be @@ -61,13 +61,13 @@ Root Folder Types **Characters** (Notes) Character notes go in this root folder type. For your main characters, you may want to make one document for each character. For smaller characters you can put multiple into the same document. - In your chapters and scenes you can reference these character notes as Point of View or Focus + In your chapters and scenes you can reference these character notes as point-of-view or focus characters. **Locations** (Notes) The locations where your story takes place can be documented here. This, together with Plot and - Characters are the particularly useful story elements to track, and to reference from your - chapter and scene documents. + Characters are the key story elements to track, and to reference from your chapter and scene + documents. **Timeline** (Notes) If the story has multiple plot timelines or jumps in time within the same plot, this folder type @@ -99,9 +99,9 @@ Root Folder Types This folder behaves like you expect. Anything dropped in here can be deleted permanently from the project, and the content doesn't show up anywhere else in novelWriter. -The root folders are closely tied to the tags and reference system. Each folder type except -**Archive** and **Trash** corresponds to one or more categories of tags that can be used to -reference the content in them. See :ref:`docs_usage_tags_refs` for more details. +The root folder types are closely tied to the tags and reference system. Each folder type for novel +and notes corresponds to one or more categories of tags that can be used to reference the content +in them. See :ref:`docs_usage_tags_refs` for more details. .. tip:: @@ -113,14 +113,13 @@ reference the content in them. See :ref:`docs_usage_tags_refs` for more details. Regular Folders =============== -Regular folders, those that are not root folders, have no structural significance to the project. +You can add regular folders anywhere you want in the project. The folders are there purely as a way +for you to organise the documents in meaningful sections and to be able to collapse and hide them +in the project tree when you're not working on those documents. + When novelWriter is processing the documents in a project, like for instance when you create a manuscript from it, these folders are ignored. Only the order of the documents themselves matter. -The folders are there purely as a way for you to organise the documents in meaningful sections and -to be able to collapse and hide them in the project tree when you're not working on those -documents. - .. _docs_usage_project_documents: @@ -128,34 +127,33 @@ Documents ========= You can add documents anywhere you want in your project structure. You can even add documents as -child items of other documents, just like if they were folders. This makes it easy to associate a -set of scenes with their chapter. You can also do this in your notes, where you for instance may -have a hierarchy of your locations. +child items of other documents, just as if they were folders. This makes it easy to associate a set +of scenes with their chapter. You can also do this in your notes, where you for instance may have a +hierarchy of your locations. The name on a document in the project tree is not linked to any headings in the document text. Think of the document name as a file name. You can rename a document, or any other item in the project, at any time. - Documents come in two types: **Novel Documents** These are the documents that make up your story or novel. They can only be added under a root folder of type **Novel**. You can technically also add them under **Archive**. See - :ref:`docs_usage_headers` for more details about how these documents are handled by novelWriter. + :ref:`docs_usage_headings` for more details on how these documents are handled by novelWriter. **Project Notes** These are the documents where you keep your notes. You can add them anywhere in your project, including under **Novel** type folders. If you do add them there, they are not treated as a part of the story by default. -You can convert between the two types of documents where the types are allowed. You can also -convert folders into documents, which may sometimes be convenient. +You can convert between the two types of documents where both types are allowed. You can also +convert folders into documents, which may sometimes be convenient too. -Another convenient feature is that documents can be split into sub-documents by its containing -headings, or multiple documents merged into one. This is particularly convenient if you start out -with larger structural documents, like one containing all chapters and scenes in an act, and then -split those. See :ref:`docs_ui_split_merge` for more details. +Another convenient feature is that documents can be split into sub-documents by its headings, or +multiple documents merged into one. This is particularly useful if you start out with larger +structural documents, like one containing all chapters and scenes in an act, and then split those +when you start writing. See :ref:`docs_ui_split_merge` for more details. .. _docs_usage_project_documents_templates: @@ -163,10 +161,10 @@ split those. See :ref:`docs_ui_split_merge` for more details. 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 **Templates** root folder to your project. Any -document added to this root folder will show up in the **Add Item** menu in the project tree -toolbar. When selected, a new document is created with its content copied from the chosen template. +If you wish to create template documents to be used when creating new documents, like for instance +a character note template, you can add a **Templates** root folder to your project. Any document +added to this root folder will show up in the **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 @@ -176,13 +174,13 @@ toolbar. When selected, a new document is created with its content copied from t Active and Inactive Documents ============================= -A document can be set as "Active" or "Inactive", which alters the icon in the third column. These -are mostly intended for your convenience as they will indicate whether the document is meant to be -included in the manuscript or not. You can think of it as a whole document out-take. It is a less -radical option than to move it to **Archive**. +A document can be set as "Active" or "Inactive", which alters the icon in the third column of the +project tree. These are mostly intended for your convenience as they will indicate whether the +document is meant to be included in the manuscript or not. You can think of an inactive status as a +whole-document out-take. It allows you to take it out without moving it to **Archive**. -Inactive documents are by default excluded from your manuscript, but you can override this. -See :ref:`docs_ui_manuscript_selection` for more details. +Inactive documents are by default excluded from your manuscript, but you can override this if you +wish. See :ref:`docs_ui_manuscript_selection` for more details. .. _docs_usage_project_status: @@ -190,9 +188,9 @@ See :ref:`docs_ui_manuscript_selection` for more details. Importance and Status ===================== -Each document or folder in your project can have either a "Status" or "Importance" labels set. -These are labels and icons that you control and define yourself, and novelWriter doesn't use them -for anything. You can modify these labels in **Project Settings**. +Each document or folder in your project can have either a "Status" or "Importance" label set. These +are labels and icons that you control and define yourself, and novelWriter doesn't use them for +anything. You can modify these labels in **Project Settings**. See :ref:`docs_ui_projects_settings_status` for more details. The "Status" labels are intended to tag a novel document as for instance a draft or as completed, diff --git a/docs/source/usage/tags_and_references.rst b/docs/source/usage/tags_and_references.rst index 1ee1ee4f..87c7331c 100644 --- a/docs/source/usage/tags_and_references.rst +++ b/docs/source/usage/tags_and_references.rst @@ -4,9 +4,9 @@ Tags and References ******************* -One of the core features of novelWriter is its Tags and References system. This is perhaps one of -the features that makes novelWriter different from other, similar applications. It is therefore not -always obvious to new users how this is supposed to work. +One of the core features of novelWriter is its **Tags and References** system. This is perhaps one +of the features that makes novelWriter different from other similar applications. It is therefore +not always obvious to new users how this is supposed to work. In novelWriter there are no forms or tables to fill in to define characters, locations or other elements of your story. Instead, you create documents in one of the root folders for notes. Within @@ -17,7 +17,7 @@ tag. .. tip:: If you find the Tags and Reference system difficult to follow just from reading this chapter, - you can create a new project in the **Welcome** dialog's New project form and select "Create an + you can create a new project in the **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. @@ -28,8 +28,8 @@ How to Use Tags =============== The structure of your novelWriter project is inferred from the headings within the documents, not -the documents themselves. See :ref:`docs_usage_headers` for more details. Therefore, metadata is -also associated with headings, and not the documents directly. +the documents themselves. See :ref:`docs_usage_headings` for more details. Therefore, metadata is +also associated with headings, and not the documents themselves. A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set by using the ``@tag`` keyword. @@ -40,27 +40,29 @@ An alternative format of a tag is ``@tag: TagName | Display Name``. ``tagName`` (Required) This is a unique identifier of your choosing. It is the value you use later for making - references back to the heading in the document. + references back to the heading in the document. The tag must be unique. ``Display Name`` (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 directly into chapter headings. By default, the + instance insert the point-of-view character name directly into chapter titles. 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 chapter headings. + project, you can use the display name to specify a more suitable format for your chapter title. -You can only set **one** tag per heading, and the tag has to be unique across **all** documents in -the project. +.. note:: + + 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 **Outline View** and in the references panel under the +notes. Tags will also show up in the **Outline View** and in the **References** panel under the document viewer when a document is open in the viewer. The editor will indicate to you that the keyword is correctly used and that the tag is allowed, that is, the tag is unique, by adding a colour highlighting to it. An invalid tag should have a 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. +The tag is the only part of notes that novelWriter uses. The rest of the document content is there +for you to use in whatever way you wish. .. versionadded:: 2.2 @@ -79,7 +81,7 @@ there for you to use in whatever way you wish. :bdg-info:`Example` -Example of a heading with a tag for a character of the story: +Example of a note document for a character with a tag set: .. code-block:: md @@ -176,8 +178,8 @@ editor. .. tip:: If you add a reference in the editor to a tag that doesn't yet exist, you can right-click it and - select **Create Note for Tag**. This will generate a new note automatically with the new tag - defined. + select **Create Note for Tag**. This will generate a new note automatically in the correct type + of root folder, with the new tag defined. One note can also reference another note in the same way novel documents do. When the note is opened in the document viewer, the references become clickable links, making it easier to follow @@ -222,7 +224,7 @@ character ``@`` on a new line. It will first suggest tag or reference keywords f after the ``:`` has been added, suggest references from the list of tags you have already defined. You can use the auto-completer to add multiple references with a ``,`` between them, and even type -new ones. New references can be created by right-clicking on them and selecting **Create Note for -Tag** from the menu. +new ones. Notes for new references can be created by right-clicking on them and selecting **Create +Note for Tag** from the menu. .. versionadded:: 2.2 diff --git a/docs/source/user_interface/main_window.rst b/docs/source/user_interface/main_window.rst index 435d3529..88fe1b27 100644 --- a/docs/source/user_interface/main_window.rst +++ b/docs/source/user_interface/main_window.rst @@ -84,6 +84,8 @@ project tree, or by pressing :kbd:`Ctrl+Up` or :kbd:`Ctrl+Down` when they are se .. versionadded:: 2.2 +.. _docs_ui_main_novel: + Novel View and Editor View ========================== @@ -125,6 +127,8 @@ meta data collected for that heading. references, which will be updated in this view when the document is saved. +.. _docs_ui_main_outline: + Novel Outline View ================== diff --git a/docs/source/user_interface/manuscript.rst b/docs/source/user_interface/manuscript.rst index 1ac42706..9cb995ec 100644 --- a/docs/source/user_interface/manuscript.rst +++ b/docs/source/user_interface/manuscript.rst @@ -141,7 +141,7 @@ Automatic Numbering The headings formatter also allows you to automatically insert chapter and scene numbers into your heading formats. The automatic chapter number counter will skip all chapter headings marked as -unnumbered using the heading format described in :ref:`docs_usage_headers_levels`. +unnumbered using the heading format described in :ref:`docs_usage_headings_levels`. Scene numbers are mostly intended for use in a draft manuscript. You can either insert absolute scene numbers that counts every scene in the novel, or you can insert per-chapter scene numbers @@ -184,7 +184,7 @@ If you wish to distinguish between so-called soft and hard scene breaks, you can alternative scene heading format in your text. You can then give these headings a different formatting in the **Headings** settings. -See :ref:`docs_usage_headers_levels` for more info on how to format headings in your text. +See :ref:`docs_usage_headings_levels` for more info on how to format headings in your text. Output Settings