diff --git a/docs/source/images/fig_build_build.png b/docs/source/images/fig_build_build.png new file mode 100644 index 00000000..72650672 Binary files /dev/null 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 new file mode 100644 index 00000000..4eb54c5e Binary files /dev/null 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 new file mode 100644 index 00000000..9dc82d49 Binary files /dev/null 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 new file mode 100644 index 00000000..8a3e1ae8 Binary files /dev/null and b/docs/source/images/fig_manuscript_build.png differ diff --git a/docs/source/images/fig_project_merge_tool.png b/docs/source/images/fig_project_merge_tool.png new file mode 100644 index 00000000..a49ae226 Binary files /dev/null and b/docs/source/images/fig_project_merge_tool.png differ diff --git a/docs/source/images/fig_project_split_tool.png b/docs/source/images/fig_project_split_tool.png new file mode 100644 index 00000000..5d122f66 Binary files /dev/null and b/docs/source/images/fig_project_split_tool.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 825c1b50..3420ce57 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -75,8 +75,8 @@ from pip. See :ref:`a_started` for more details. project_overview project_structure - project_notes - project_export + project_references + project_manuscript .. toctree:: :maxdepth: 1 diff --git a/docs/source/int_glossary.rst b/docs/source/int_glossary.rst index 7d6fc105..077c80aa 100644 --- a/docs/source/int_glossary.rst +++ b/docs/source/int_glossary.rst @@ -9,13 +9,19 @@ Glossary Root Folder A "Root Folder" is a top level folder of the project tree in novelWriter. Each type of root folder has a specific icon to identify it. For an overview of available root folder types, - see :ref:`` + see :ref:`a_proj_roots`. Novel Documents - These are documents that are created under a "Novel" :term:`root folder`. + These are documents that are created under a "Novel" :term:`root folder`. They behave + differently than :term:`Project Notes`, and have some more restrictions. For instance, they + can not exist in folders intended only for project notes. See the :ref:`a_struct` chapter for + more details. Project Notes - ... + Project Notes are unrestricted documents that can be placed anywhere in your project. You + should not use these documents for story elements, only for notes. Project notes are the + source files used by the Tags and References system. See the :ref:`a_references` chapter for + more details on how to use them. Tag ... @@ -28,3 +34,12 @@ Glossary Context Menu ... + + 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 + matter. For more details on headings in novel documents, see :ref:`a_struct_heads`. + + Keyword + ... diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst index c877777a..b2d3a587 100644 --- a/docs/source/int_overview.rst +++ b/docs/source/int_overview.rst @@ -81,11 +81,11 @@ meta data for it to extract. explains how the different levels of headings are used, and how you can include information about characters, plot elements, and other meta data in your text. -:ref:`a_notes` - Recommended Reading - This section briefly describes what novelWriter does with the note files you add to your - project. Generally, the application doesn't do much with them at all aside from looking through - them for tags you've set so that it knows which file to open when you click on a reference. +:ref:`a_references` - Recommended Reading + This section explains how you organise your notes, and how the Tags and References system works. + This system lets you cross-link your documents in your project, and display these references in + the application interface. -:ref:`a_export` - Recommended Reading - This section explains in more detail how the build tool works. In particular how you can - control the way chapter titles are formatted, and how scene and section breaks are handled. +:ref:`a_manuscript` - Recommended Reading + This section explains in more detail how the Manuscript Build tool works, how you can control + the way chapter titles are formatted, and how scene and section breaks are handled. diff --git a/docs/source/project_export.rst b/docs/source/project_export.rst deleted file mode 100644 index ea29fa15..00000000 --- a/docs/source/project_export.rst +++ /dev/null @@ -1,159 +0,0 @@ -.. _a_export: - -*********************** -Building the Manuscript -*********************** - -You can at any time build a manuscript, an outline of your notes, or any other type of document -from the text in your project. All of this is handled by the :guilabel:`Build Novel Project` tool. -You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing :kbd:`F5`. - -.. note:: - This tool is scheduled to receive a full update in novelWriter 2.1, adding many new features - requested by users. See the `2.1 Milestone `_ - for an overview. - - -.. _a_export_headers: - -Header Formatting -================= - -The titles for the five types of headings (the chapter headings come in a numbered and unnumbered -version) of story structure can be formatted collectively in the build tool. This is done through -a series of keyword–replace steps. They are all on the format ``%keyword%``. - -``%title%`` - This keyword will always be replaced with the title text you put after the ``#`` characters in - your document. - -``%ch%`` - This will be replaced by a chapter number. The number is incremented by one each time the build - tool sees a new heading of level two in a document, unless the heading formatting code has the - added ``!``. In the latter case, the counter is *not* incremented. This is useful for for - instance Prologue and Epilogue chapters. - -``%chw%`` - Behaves like ``%ch%``, but the number is represented as a number word. You can select between a - number of different languages. - -``%chi%`` - Begaves like ``%ch%``, but represented as a lower case Roman number from 1 to 4999. - -``%chI%`` - Behaves like ``%ch%``, but represented as an upper case Roman number from 1 to 4999. - -``%sc%`` - This is the number counter equivalent for scenes. These are incremented each time a heading of - level three is encountered, but reset to 1 each time a chapter is encountered. They can thus be - used for counting scenes within a chapter. - -``%sca%`` - Behaves like ``%sc%``, but the number is *not* reset to 1 for each chapter. Instead it runs from - 1 from the beginning of the novel to produce an absolute scene count. - -``\\`` - This inserts a line break within the title. - -.. note:: - Header formatting only applies to novel documents. Headings in notes will be left as-is. - -**Example** - -* The format ``%title%`` just reproduces the title you set in the document. -* The format ``Chapter %ch%: %title%`` produces something like "Chapter 1: My Chapter Title". -* The format ``Scene %ch%.%sc%`` produces something like "Scene 1.2" for scene 2 in chapter 1. - - -.. _a_export_scenes: - -Scene Separators -================ - -If you don't want any titles for your scenes (or for your sections if you have them), you can leave -the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or -sections instead, resulting in a gap in the text. - -Alternatively, if you want a separator between them, like the common ``* * *``, you can enter the -desired separator text in the formatting box. In fact, if the format is a piece of static text, it -will always be treated as a separator. - - -.. _a_export_files: - -File Selection -============== - -Which documents and notes are selected for the build can be controlled from the options on the left -side of the dialog window. In addition, you can select to include the synopsis comments, regular -comments, keywords, and even exclude the body text itself if you just want an outline. - -.. tip:: - If you for instance want to export a document with an outline of the novel, you can enable - keywords and synopsis export and disable body text, thus getting a document with each heading - followed by the tags and references and the synopsis. - -If you need to exclude specific documents from your exports, like draft documents or documents you -want to take out of your manuscript, but don't want to delete, you can set the documents as -"inactive" in the project tree. :guilabel:`Build Novel Project` tool has a switch to collectively -exclude inactive documents. - - -.. _a_export_print: - -Printing -======== - -The print button allows you to print the content in the preview window. You can either print to one -of your system's printers, or print directly to a file as PDF. You can also print to file from the -regular print dialog. The direct to file option is just a shortcut. - -.. note:: - The paper format should in all cases default to whatever your system default is. Of you want to - change it, you have to select it from the :guilabel:`Print Preview`` dialog. - - -.. _a_export_formats: - -Export Formats -============== - -Currently, six formats are supported. - -Open Document Format - The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a - flat version of the document format as a single XML file. Most rich text editors support the - former, and a few the latter. - -novelWriter HTML - The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document - is suitable for further processing by document conversion tools like Pandoc, for importing in - word processors, or for printing from browser. - -novelWriter Markdown - This is simply a concatenation of the project documents selected by the filters. The documents - are stacked together in the order they appear in the project tree, with comments, tags, etc. - included if they are selected. This is a useful format for exporting the project for later - import back into novelWriter. - -Standard/GitHub Markdown - The Markdown format comes in both Standard and GitHub flavour. The *only* difference in terms of - novelWriter functionality is the support for strikethrough text, which is not supported by the - Standard flavour, but *is* supported by the GitHub flavour. - - -.. _a_export_options: - -Additional Formats -================== - -In addition to the above document formats, the novelWriter HTML and Markdown formats can also be -wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also -the accompanying css styles are included. - -The text body is saved in a two-level list. The outer list contains one entry per document, in the -order they appear in the project tree. Each document is then split up into a list as well, with one -entry per paragraph it contains. - -These files are mainly intended for scripted post-processing for those who want that option. A JSON -file can be imported directly into a Python dict object or a PHP array, to mentions a few options. diff --git a/docs/source/project_manuscript.rst b/docs/source/project_manuscript.rst new file mode 100644 index 00000000..e01e5d01 --- /dev/null +++ b/docs/source/project_manuscript.rst @@ -0,0 +1,185 @@ +.. _a_manuscript: + +*********************** +Building the Manuscript +*********************** + +You can at any time build a manuscript, an outline of your notes, or any other type of document +from the text in your project. All of this is handled by the :guilabel:`Manuscript Build` tool. +You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing :kbd:`F5`. + +.. versionadded:: 2.1 + This tool is new for version 2.1. A simpler tool was used for earlier versions. The simpler tool + only allows you to define a single set of options for one build, but otherwise has much the same + functionality. + + +.. _a_manuscript_main: + +The Manuscript Build Tool +========================= + +.. figure:: images/fig_manuscript_build.png + + The :guilabel:`Manuscript Build` tool main window. + +The main window of the :guilabel:`Manuscript Build` tool contains a list of all the builds you have +defined, a selection of settings, and a few buttons to generate preview, open the print dialog, or +run the build to create a manuscript document. + + +.. _a_manuscript_settings: + +Build Settings +============== + +Each build definition can be edited by opening it in the :guilabel:`Manuscript Build Settings` +dialog, either by double-clicking or by selecting it and pressing the edit button in the toolbar. + +.. tip:: + You can keep the :guilabel:`Manuscript Build Settings` dialog open while testing the different + options, and just hit the :guilabel:`Apply` button. You can test the result of your settings + by pressing the :guilabel:`Preview` button in the main :guilabel:`Manuscript Build` window. + When you're happy with the result, you can close the settings. + + +Document Selection +------------------ + +.. figure:: images/fig_build_settings_selections.png + + The :guilabel:`Selections` page of the :guilabel:`Manuscript Build Settings` dialog. + +The :guilabel:`Selections` page of the :guilabel:`Manuscript Build Settings` dialog allows you to +fine tune which documents are included in the build. They are indicated by a green arrow icon in +the last column. On the right, you have some filter options for selecting content of a specific +type, and a set of switches for which root folders to include. + +You can override the result of these filters by marking one or more documents and selecting to +explicitly include or exclude them by using the buttons below the tree view. The last button can be +used to reset the override and return control to the filter settings. + +In the figure, the green arrow icon and the blue pin icon indicates which documents are included, +and the red forbidden icon indicates that a document is explicitly excluded. + + +Formatting Headings +------------------- + +.. figure:: images/fig_build_settings_headings.png + + The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog. + +The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog allows you to set +how the headings in your :term:`Novel Documents` as formatted. By default, the title is just copied +as-is, indicated by the ``{Title}`` format. You can change this to for instance add chapter +numbers and scene numbers like shown int he figure above. + +Clicking the edit button will copy the formatting string into the edit box, where a syntax +highlighter will help indicate which parts are automatically generated by the build tool. The +:guilabel:`Insert` button is a dropdown list of these formats, and selecting one will insert it at +the position of the cursor. + +Any text you add that isn't highlighted in colours will remain in your formatted titles. +``{Title}`` will always be replaced by the text in the heading from your documents. + +You can preview the result of these format strings by clicking :guilabel:`Apply`, and then clicking +:guilabel:`Preview` in the :guilabel:`Manuscript Build` tool main window. + +Scene Separators +^^^^^^^^^^^^^^^^ + +If you don't want any titles for your scenes (or for your sections if you have them), you can leave +the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or +sections instead, resulting in a gap in the text. You can also switch on the :guilabel:`Hide` +setting, which will ignore them completely. That is, there won't even be an extra gap insetred. + +Alternatively, if you want a separator text between them, like the common ``* * *``, you can enter +the desired separator text in the formatting box. In fact, if the format is any piece of static +text, it will always be treated as a separator. + + +Output Settings +--------------- + +The :guilabel:`Content`, :guilabel:`Format` and :guilabel:`Output` pages of the +:guilabel:`Manuscript Build Settings` dialog control a number of other settings for the output. +Some of these only apply to specific output formats, which is indicated by the section headings on +the settings pages. + + +.. _a_manuscript_build: + +Building Manuscript Documents +============================= + +.. figure:: images/fig_build_build.png + + The :guilabel:`Manuscript Build` dialog sued for writing the actual manuscript documents. + +When you press the :guilabel:`Build` button on the :guilabel:`Build Manuscript` tool main window, a +special file dialog opens up. This is where you pick your desired output format and where to write +the file. + +On the left is a list of all the available file formats, and on the right, a list of what documents +are included based on the build definition you selected. You can choose an output path, and set a +base file name as well. The file extension will be added automatically. + +To generate the manuscript document, press the :guilabel:`Build` button. A small progress bar will +show the build progress, but for small projects it may pass very fast. + + +File Formats +------------ + +Currently, four document formats are supported. + +Open Document Format + The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a + flat version of the document format as a single XML file. Most rich text editors support the + former, and a few the latter. + +novelWriter HTML + The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document + is suitable for further processing by document conversion tools like Pandoc, for importing in + word processors, or for printing from browser. + +novelWriter Markup + This is simply a concatenation of the project documents selected by the filters. The documents + are stacked together in the order they appear in the project tree, with comments, tags, etc. + included if they are selected. This is a useful format for exporting the project for later + import back into novelWriter. + +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 + the Standard flavour. + + +Additional Formats +------------------ + +In addition to the above document formats, the novelWriter HTML and Markup formats can also be +wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also +the accompanying css styles are included. + +The text body is saved in a two-level list. The outer list contains one entry per document, in the +order they appear in the project tree. Each document is then split up into a list as well, with one +entry per paragraph it contains. + +These files are mainly intended for scripted post-processing for those who want that option. A JSON +file can be imported directly into a Python dict object or a PHP array, to mentions a few options. + + +.. _a_manuscript_print: + +Print and PDF +============= + +The :guilabel:`Print` button allows you to print the content in the preview window. You can either +print to one of your system's printers, or select PDF as your output format from the printer icon +on the print dialog. + +.. note:: + The paper format should in all cases default to whatever your system default is. If you want to + change it, you have to select it from the :guilabel:`Print Preview` dialog. diff --git a/docs/source/project_notes.rst b/docs/source/project_notes.rst deleted file mode 100644 index 2536225e..00000000 --- a/docs/source/project_notes.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _a_notes: - -************* -Project Notes -************* - -novelWriter doesn't have a database and complicated forms for filling in details about plot -elements, characters, and all sorts of additional information that isn't a part of the novel text -itself. Instead, all such information is saved in notes that are written and maintained just like -all other text in your project. - -The relation between all these additional elements is extracted from the documents and notes by the -project indexer, based on the tags and references you set within them. - -Using notes is not required, but making at least minimal notes for each plot element, and adding a -tag to them, makes it possible to use the Outline View to see how each element intersects with each -section of the novel itself, and adds clickable cross-references between documents in the editor -and viewer. - - -.. _a_notes_tags: - -Tags in Notes -============= - -Each new heading in a note can have a tag associated with it. The format of a tag is -``@tag: tagname``, where tagname is a unique identifier of your choosing. Tags can then be -referenced in the novel documents, or cross-referenced in other notes, and will show up in the -Outline View and in the back-reference panel when a document is opened in the viewer. See -:ref:`a_struct_tags` for how to reference notes. - -The syntax highlighter will alert the user that the keyword is correctly used and that the tag is -allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up -to date. An invalid tag should have a green wiggly line under it, and will not receive the syntax -colour that valid tags do. - -The tag is the only part of these notes that the application uses. The rest of the document content -is there for the writer to use in whatever way they wish. Of course, the content of the documents -can be added to the manuscript, or an outline document. If you want to compile a single document of -all your notes, you can do this from the :guilabel:`Build Novel Project` tool. - -One note can also reference another note in the same way novel documents do. When the note is -opened in the view panel, the references become clickable links, making it easier to follow -connections in the plot. Notes don't show up in the Outline View though, so referencing between -notes is only meaningful if you want to be able to click-navigate between them, or of course if you -just want to highlight that two notes are related. - -.. tip:: - If you cross-reference between notes and export your project as an HTML document using the - :guilabel:`Build Novel Project` tool, the cross-references become clickable links in the - exported HTML document. - -Example of a project note with two headers, with separate tags, and with references to other notes: - -.. code-block:: none - :linenos: - - # Main Characters - - ## Jane Doe - - @tag: Jane - @location: Earth - - Something about Jane ... - - ## John Doh - - @tag: John - @location: Mars - - Something about John ... diff --git a/docs/source/project_overview.rst b/docs/source/project_overview.rst index b272f3f4..e18f2b93 100644 --- a/docs/source/project_overview.rst +++ b/docs/source/project_overview.rst @@ -29,9 +29,9 @@ Project Roots 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 novel documents go into a root folder of type :guilabel:`Novel`. Project notes go into the -other root folders. These other root folder types are intended for your notes on the various -elements of your story. Using them is of course entirely optional. +The :term:`novel documents` go into a root folder of type :guilabel:`Novel`. :term:`Project notes` +go into the other root folders. These other root folder types are intended for your notes on the +various elements of your story. Using them is of course entirely optional. A new project may not have all of the root folders present, but you can add the ones you want from the project tree tool bar. @@ -41,80 +41,58 @@ them from other documents and notes. The intended usage of each type of root fol below. However, aside from the :guilabel:`Novel` folder, no restrictions are applied by the application on what you put in them. You can use them however you want. +The root folder system is closesly connected to how the Tags and References system works. For more +details, see the :ref:`a_references` chapter. + .. tip:: You can make multiple root folders of each kind if you wish to split up your notes. -.. note:: - It is not the notes themselves that are referenced by the listed reference keywords, but tags - set within the notes. See the examples below and in :ref:`a_struct_tags`. - :guilabel:`Novel` - This is the root folder of all text that goes into the final novel or novels. This class of + This is the root folder type for text that goes into the final novel or novels. This class of documents have other rules and features than the project notes. See :ref:`a_struct` for more details. :guilabel:`Plot` - This is the root folder where main plots can be outlined. It is optional, but adding at least - brief notes can be useful in order to tag plot elements for the Outline View. Tags in this + This is the root folder type where main plots can be outlined. It is optional, but adding at + least brief notes can be useful in order to tag plot elements for the Outline View. Tags in this folder can be references using the ``@plot`` keyword. :guilabel:`Characters` - Character notes go in this root folder. These are especially important if you want to use the - Outline View to see which character appears where, and 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 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 characters. + 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 + other character. :guilabel:`Locations` - The locations folder is for various scene locations that you want to track. Tags in this folder - can be references using the ``@location`` keyword. + The locations folder type is for various scene locations that you want to track. Tags in this + folder can be references using the ``@location`` keyword. :guilabel:`Timeline` - If the story has multiple plot timelines or jumps in time within the same plot, this class of - notes can be used to track this. Tags in this folder can be references using the ``@time`` + If the story has multiple plot timelines or jumps in time within the same plot, this folder type + can be used to track this. Tags in this type of folder can be references using the ``@time`` keyword. :guilabel:`Objects` - Important objects in the story, for instance important objects that change hands often, can be - tracked here. Tags in this folder can be references using the ``@object`` keyword. + Important objects in the story, for instance objects that change hands often, can be tracked + here. Tags in this type of folder can be references using the ``@object`` keyword. :guilabel:`Entities` Does your plot have many powerful organisations or companies? Or other entities that are part of - the plot? They can be organised here. Tags in this folder can be references using the + the plot? They can be organised here. Tags in this type of folder can be references using the ``@entity`` keyword. :guilabel:`Custom` - The custom root folder can be used for tracking anything else not covered by the above options. - Tags in this folder can be references using the ``@custom`` keyword. + The custom root folder type can be used for tracking anything else not covered by the above + options. Tags in this folder type can be references using the ``@custom`` keyword. The root folders correspond to the categories of tags that can be used to reference them. For more -information about the tags listed, see :ref:`a_struct_tags`. +information about the tags listed, see :ref:`a_references_references`. .. note:: You can rename root folders to whatever you want. However, this doesn't change the reference - keyword. - -Example of a character note: - -.. code-block:: none - :linenos: - - # Jane Doe - - @tag: Jane - - Some information about the character Jane Doe. - -Example of a novel scene referencing the above character: - -.. code-block:: none - :linenos: - - ### Chapter 1, Scene 1 - - @pov: Jane - - When Jane woke up that morning ... + keyword or what they do. .. _a_proj_roots_del: @@ -128,7 +106,7 @@ the menu. Documents in the trash folder are removed from the project index and c referenced. A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing -:kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`. Root folders can only be deleted when they are empty. +:kbd:`Ctrl+Shift+Del`. Root folders can only be deleted when they are empty. .. _a_proj_roots_out: @@ -138,14 +116,14 @@ Archived Documents If you don't want to delete a document, or put it in the :guilabel:`Trash` folder where it may be deleted, but still want it out of your main project tree, you can create an :guilabel:`Archive` -root folder. +root folder and move it there. You can drag any document to this folder and preserve its settings. The document will always be -excluded from the :guilabel:`Build Novel Project` builds. It is also removed from the project -index, so the tags and references defined in it will not show up anywhere else. +excluded from the :guilabel:`Build Manuscript` tool. It is also removed from the project index, so +the tags and references defined in it will not show up anywhere else. -.. _a_proj_roots_orph: +.. _a_proj_roots_orphaned: Recovered Documents ------------------- @@ -153,19 +131,19 @@ Recovered Documents If novelWriter crashes or otherwise exits without saving the project state, or if you're using a file synchronisation tool that runs out of sync, there may be files in the project folder that aren't tracked in the core project file. These files, when discovered, are recovered and added back -into the project if possible. +into the project, if possible. The discovered files are scanned for meta information that give clues as to where the document may previously have been located in the project. The project loading routines will try to put them back as close as possible to this location, if it still exists. Generally, it will be appended to the end of the folder where it previously was located. If that folder doesn't exist, it will try to add it to the correct root folder. If it cannot figure out which root folder is correct, the document -will be added to the :guilabel:`Novel` root folder. Only if the :guilabel:`Novel` folder is -missing will it give up. +will be added to the :guilabel:`Novel` root folder. Finally, if the :guilabel:`Novel` folder is +missing, one will be created. If the title of the document can be recovered, the word "Recovered:" will be added as a prefix. If -the title cannot be determined, the document will be named "Recovered File N" where N is a -sequential number. +the title cannot be determined, the document will be named after its internal key, which is a +string of characters and numbers. .. _a_proj_roots_lock: @@ -173,11 +151,11 @@ sequential number. Project Lockfile ---------------- -To prevent lost documents caused by file conflicts when novelWriter projects are synced with 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 give the option to ignore -this warning, and continue opening the project at your own risk. +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. .. note:: If, for some reason, novelWriter crashes, the lock file may remain even if there are no other @@ -198,18 +176,18 @@ Using Folders in the Project Tree --------------------------------- Folders, aside from root folders, have no structural significance to the project. When novelWriter -is processing the documents in the novel, like for instance during export, these folders are -ignored. Only the order of the documents themselves matter. +is processing the documents in the novel, 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 the user 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 +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. -.. tip:: - You can add child documents to other documents. This is particularly useful when you create - chapters and scenes. If you add separate scene documents, you should also add separate chapter - documents, even if they only contain a chapter heading. You can then add scene documents as - child items to the chapters. +.. versionadded:: 2.0 + As of version 2.0 it is possible to add child documents to other documents. This is particularly + useful when you create chapters and scenes. If you add separate scene documents, you should also + add separate chapter documents, even if they only contain a chapter heading. You can then add + scene documents as child items to the chapters. .. _a_proj_files: @@ -217,15 +195,16 @@ documents. Project Documents ================= -New documents can be created from the tool bar in the Project Tree, or by pressing -:kbd:`Ctrl`:kbd:`N`. This will open the create new item menu and let you choose between a number of +New documents can be created from the toolbar in the :guilabel:`Project Tree`, or by pressing +:kbd:`Ctrl+N`. This will open the create new item menu and let you choose between a number of pre-defined documents and folders. You will be prompted for a label for the new item. You can always rename an item by selecting :guilabel:`Rename Item` from the :guilabel:`Project` menu, or by pressing :kbd:`F2`. Other settings for project items are available from the context menu that you can activate by -right-clicking on an item in the Project Tree. The :guilabel:`Transform` submenu includes options -for converting, splitting, or merging items. +right-clicking on an item in the :guilabel:`Project Tree`. The :guilabel:`Transform` submenu +includes options for converting, splitting, or merging items. See :ref:`a_ui_tree_split_merge` for +more details on the latter two. .. _a_proj_files_counts: @@ -234,16 +213,17 @@ Word Counts ----------- A character, word and paragraph count is maintained for each document, as well as for each section -of a document following a header. The word count and change of words in the current session is -displayed in the footer of any document open in the editor, and all stats are shown in the details -panel below the project tree for any document selected in the project or novel tree. +of a document following a :term:`heading`. The word count and change of words in the +current session is displayed in the footer of any document open in the editor, and all stats are +shown in the details panel below the :guilabel:`Project Tree` for any document selected in the +project or novel trees. The word counts are not updated in real time, but run in the background every few seconds for as long as the document is being actively edited. A total project word count is displayed in the status bar. The total count depends on the sum of the values in the project tree, which again depend on an up to date index. If the counts seem -wrong, a full project word recount can be initiated by rebuilding the project's index. Either form +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`. @@ -253,7 +233,7 @@ Project Settings ================ The :guilabel:`Project Settings` can be accessed from the :guilabel:`Project` menu, or by pressing -:kbd:`Ctrl`:kbd:`Shift`:kbd:`,`. This will open a dialog box, with a set of tabs. +:kbd:`Ctrl+Shift+,`. This will open a dialog box, with a set of tabs. Settings Tab @@ -263,26 +243,26 @@ 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 the 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. +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:`Novel Title` and :guilabel:`Authors` settings are used when building the manuscript, for some formats. If your project is in a different language than your main spell checking is set to, you can override the default spell checking language here. You can also override the automatic backup -setting. +setting. The project language can also be changed from the :guilabel:`Tools` menu. Status and Importance Tabs -------------------------- -Each document or folder of type :guilabel:`Novel` can be given a *Status*_* label accompanied by a +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 are purely there for the user's convenience, and you are not required to use them for any +These labels are there purely for your convenience, and you are not required to use them for any other features to work. No other part of novelWriter accesses this information. The intention is to use these to indicate at what stage of completion each novel document is, or how important the content of a note is to the story. You don't have to use them this way, that's just what they were @@ -302,7 +282,7 @@ A set of automatically replaced keywords can be added in this tab. The keywords will be replaced by the text in the right column when documents are opened in the viewer. They will also be applied to manuscript builds. -The auto-replace feature will replace text in angle brackets that are in this list. The syntax +The auto-replace feature will replace text in angle brackets that is in this list. The syntax highlighter will add an alternate colour to text matching the syntax, but it doesn't check if the text is in this list. @@ -332,7 +312,7 @@ It is also possible to disable automated backups for a given project in .. note:: For the backup to be able to run, the :guilabel:`Project Name` must be set in - :guilabel:`Project Settings`. This value is used to generate the folder name for the zip files. + :guilabel:`Project Settings`. This value is used to generate the name and path of the backups. Without it, the backup will not run at all, but it will produce a warning message. @@ -343,19 +323,19 @@ Writing Statistics When you work on a project, a log file records when you opened it, when you closed it, and the total word counts of your novel documents and notes at the end of the session, provided that the -session lasted either more than 5 minutes, or that the total word count changed. You can view this -file in the ``meta`` folder in the directory where you saved your project. The file is named -``sessionStats.log``. +session lasted either more than 5 minutes, or that the total word count changed. For more details +about the log file, see :ref:`a_storage`. -A tool to view the content of this file is available in the :guilabel:`Tools` menu under +A tool to view the content of the log file is available in the :guilabel:`Tools` menu under :guilabel:`Writing Statistics`. You can also launch it by pressing :kbd:`F6`, or find it on the -Sidebar. +sidebar. The tool will show a list of all your sessions, and a set of filters to apply to the data. You can also export the filtered data to a JSON file or to a CSV file that can be opened by a spreadsheet -application like for instance Libre Office Calc. +application like for instance Libre Office Calc or Excel. -As of version 1.2, the log file also stores how much of the session time was spent idle. The -definition of idle here is that the novelWriter main window loses focus, or the user hasn't made -any changes to the currently open document in five minutes. The number of minutes can be altered in -:guilabel:`Preferences`. +.. versionadded:: 1.2 + As of version 1.2, the log file also stores how much of the session time was spent idle. The + definition of idle here is that the novelWriter main window loses focus, or the user hasn't made + any changes to the currently open document in five minutes. The number of minutes can be altered + in :guilabel:`Preferences`. diff --git a/docs/source/project_references.rst b/docs/source/project_references.rst new file mode 100644 index 00000000..b1898d20 --- /dev/null +++ b/docs/source/project_references.rst @@ -0,0 +1,175 @@ +.. _a_references: + +******************* +Tags and References +******************* + +In novelWriter there are no forms or tables to fill in to define the characters, locations and +other elements of your story. Instead, you can mark your :term:`Project Notes` as representing +these story elements by creating a :term:`tag`. Whenever you want to link a piece of yur story to +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. + +This is perhaps one of the features that makes novelWriter quite different than other, similar +applications. It is therefore not always obvious to new users how this is supposed to work, so +this chapter hopes to explains in more detail how these tags and references system works. + +.. 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. + + +.. _a_references_metadata: + +Metadata in novelWriter +======================= + +The structure of your novelWriter project is inferred from the :term:`headings` within the +documents, not the documents themselves. See :ref:`a_struct_heads` for more details. Therefore, +metadata is also associated with headings, and not documents. + +If you split your project into separate documents for each scene, this may not matter. However, +there are several benefits to using documents at a larger structural scale when starting your +project. For instance, it may make more sense to define all your scenes, and even chapters, in a +single document at first, or perhaps a document per act. You can later split these documents up +using the split feature. See :ref:`a_ui_tree_split_merge` for more details on this feature. + +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. + + +.. _a_references_tags: + +How to Use Tags +=============== + +A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set +by using the ``@tags`` :term:`keyword`. The full format of a tag is ``@tag: tagname``, where +``tagname`` is an identifier of your choosing. You can only set *one* tag per heading, and the tag +has to be unique across all documents in the project. + +.. note:: + In version 2.2, tags will be made case insensitive, but as of novelWriter 2.1 they are not. You + should avoid using tags that are only distinquished by case. + +Tags can then be referenced in the novel documents, or cross-referenced in other notes, and will +show up in the :guilabel:`Outline View` and in the back-reference panel when a document is opened +in the viewer. + +The syntax highlighter will alert you that the keyword is correctly used and that the tag is +allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up +to date. An invalid tag should have a green wiggly line under it, and will not receive the syntax +colour that valid tags do. + +The tag is the only part of these notes that the application uses. The rest of the document content +is there for the writer to use in whatever way they wish. Of course, the content of the documents +can be added to the manuscript, or an outline document. If you want to compile a single document of +all your notes, you can do this from the :guilabel:`Manuscript Build` tool. + +Example: + +.. code-block:: none + + # Jane Doe + + @tag: Jane + + Some information about the character Jane Doe. + +When this is done in a document in a :term:`Root Folder` of type "Characters", the tag is +automatically treated as an available character in your project, and you will be able to reference +it in any of your other documents. + +It is the root folder type that defines what category of story elements the tag is indexed under. +See the :ref:`a_proj_roots` section for an overview of availabe root folder types. + + +.. _a_references_references: + +How to Use References +===================== + +Each heading of any level in your project can contain references to tags set in project notes. The +references are gathered by the indexer and used to generate the :guilabel:`Outline View`, among +other things. + +References are set as a :term:`keyword` and a list of corresponding tags. The valid keywords are +listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All +keywords allow multiple values. + +``@pov`` + The point-of-view character for the current section. The target must be a note tag in a + :guilabel:`Character` type root folder. + +``@focus`` + The character that has the focus for the current section. This can be used in cases where the + focus is not a point-of-view character. The target must be a note tag in a :guilabel:`Character` + type root folder. + +``@char`` + Other characters in the current section. The target must be a note tag in a + :guilabel:`Character` type root folder. This should not include the point-of-view or focus + character if those references are used. + +``@plot`` + The plot or subplot advanced in the current section. The target must be a note tag in a + :guilabel:`Plot` type root folder. + +``@time`` + The timelines touched by the current section. The target must be a note tag in a + :guilabel:`Timeline` type root folder. + +``@location`` + The location the current section takes place in. The target must be a note tag in a + :guilabel:`Locations` type root folder. + +``@object`` + Objects present in the current section. The target must be a note tag in a :guilabel:`Object` + type root folder. + +``@entity`` + Entities present in the current section. The target must be a note tag in a + :guilabel:`Entities` type root folder. + +``@custom`` + Custom references in the current section. The target must be a note tag in a :guilabel:`Custom` + type root folder. The custom folder are for any other category of notes you may want to use. + +The syntax highlighter will alert the user that the tags and references are used correctly, and +that the tags referenced exist. + +The highlighter may be mistaken if the index of defined tags is out of date. If so, press :kbd:`F9` +to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general, +the index for a document is regenerated when it is saved, so this shouldn't normally be necessary. + +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 +connections in the plot. You can follow links in the document editor by clicking them with the +mouse while holding down the :kbd:`Ctrl` key. Clicked links are always opened in the view panel. + +Project notes don't show up in the :guilabel:`Outline View`, so referencing between notes is only +meaningful if you want to be able to click-navigate between them, or of course if you just want to +highlight that two notes are related. + +.. tip:: + If you cross-reference between notes and export your project as an HTML document using the + :guilabel:`Manuscript Build` tool, the cross-references become clickable links in the exported + HTML document. + +Example of a novel document with references to characters and plots: + +.. code-block:: none + + ## Chapter 1 + + @pov: Jane + + ### Scene 1 + + @char: John, Sam + @plot: Main + + Once upon a time ... diff --git a/docs/source/project_structure.rst b/docs/source/project_structure.rst index 35cc861e..117cfdfb 100644 --- a/docs/source/project_structure.rst +++ b/docs/source/project_structure.rst @@ -4,10 +4,16 @@ Novel Structure *************** -This section covers the structure of a novel project. +This chapter covers the structure of a novel project. -It concerns documents under the :guilabel:`Novel` type root folder only. There are some -restrictions and features that only apply to these types of documents. +There are two different types of documents in a project, :guilabel:`Novel Documents` and +:guilabel:`Project Notes`. Novel documents can only live in a :guilabel:`Novel` type root folder. +You can also move them to :guilabel:`Archive` and :guilabel:`Trash` of course. This chapter covers +the former type. + +The :guilabel:`Project Tree` can distinguish between the different header levels of the novel +documents using coloured icons, and optionally add emphasis on the label, set in +:guilabel:`Preferences`. .. _a_struct_heads: @@ -23,8 +29,9 @@ title. See also the :ref:`a_fmt` section for more details about the markdown syn .. note:: The header levels are not only important when generating the manuscript, they are also used by - the indexer when building the outline tree in the Outline as well as the Novel Tree. Each - heading also starts a new region where new references and tags can be defined. + 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`. The syntax for the four basic header types, and the two special header types, is listed in section :ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows: @@ -32,7 +39,7 @@ The syntax for the four basic header types, and the two special header types, is **Header Level 1: Partition** This header 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 explained in :ref:`a_fmt_head`. + The novel title itself should use the special header 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 @@ -49,18 +56,19 @@ The syntax for the four basic header types, and the two special header types, is **Header Level 4: Section** This header 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 tag references + 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 build tool. If -you want page breaks in other places, you have to specify them manually. See :ref:`a_fmt_break`. +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`. .. tip:: There are multiple options of how to process novel titles 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_export` page for more details. + them in a draft manuscript. See the :ref:`a_manuscript` page for more details. .. _a_struct_heads_title: @@ -89,13 +97,13 @@ 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 a ``!`` to the level 2 header formatting code to tell the +chapters separate from this, you cam add an ``!`` to the level 2 header formatting code to tell the build tool to skip these chapters. ``##! Unnumbered Chapter Title`` -There is a separate formatting feature for such chapters in the :guilabel:`Build Novel Project` -tool as well. See the :ref:`a_export` page for more details. When building a document of a format +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. @@ -104,105 +112,3 @@ normal chapters. the first character of the chapter title itself. This feature has been dropped in favour of the current format in order to keep level 1 and 2 headers consistent. Please update your chapter headings if you've used this syntax. - - -.. _a_struct_tags: - -Note References -=============== - -Each text partition, indicated by a heading of any level, can contain references to tags set in the -project notes of the project. The references are gathered by the indexer and used to generate the -Outline View. This section covers how to make references to tags. See :ref:`a_notes_tags` for how -to define tags the references can point to. - -References and tags are also clickable in the document editor and viewer, making it easy to -navigate between reference notes while writing. Clicked links are always opened in the view panel. - -References are set as a keyword and a list of corresponding tags. The valid keywords are listed -below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All keywords -allow multiple values. - -``@pov`` - The point-of-view character for the current section. The target must be a note tag in a - :guilabel:`Character` type root folder. - -``@focus`` - The character that has the focus for the current section. This can be used in cases where the - focus is not a point-of-view character. The target must be a note tag in a :guilabel:`Character` - type root folder. - -``@char`` - Other characters in the current section. The target must be a note tag in a - :guilabel:`Character` type root folder. This should not include the point-of-view or focus - character if those references are used. - -``@plot`` - The plot or subplot advanced in the current section. The target must be a note tag in a - :guilabel:`Plot` type root folder. - -``@time`` - The timelines touched by the current section. The target must be a note tag in a - :guilabel:`Timeline` type root folder. - -``@location`` - The location the current section takes place in. The target must be a note tag in a - :guilabel:`Locations` type root folder. - -``@object`` - Objects present in the current section. The target must be a note tag in a :guilabel:`Object` - type root folder. - -``@entity`` - Entities present in the current section. The target must be a note tag in a - :guilabel:`Entities` type root folder. - -``@custom`` - Custom references in the current section. The target must be a note tag in a :guilabel:`Custom` - type root folder. The custom folder are for any other category of notes you may want to use. - -The syntax highlighter will alert the user that the tags and references are used correctly, and -that the tags referenced exist. - -The highlighter may be mistaken if the index of defined tags is out of date. If so, press :kbd:`F9` -to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general, -the index for a document is regenerated when it is saved, so this shouldn't normally be necessary. - -Example of a novel document with references to characters and plots: - -.. code-block:: none - :linenos: - - ## Chapter 1 - - @pov: Jane - - ### Scene 1 - - @char: John, Sam - @plot: Main - - Once upon a time ... - - -.. _a_struct_layout: - -Document Layout -=============== - -All documents in the project can have a layout format set. Previously, there were multiple layouts -available to change how the documents where formatted on export. These have now been reduced to -just two layouts: :guilabel:`Novel Document` and :guilabel:`Project Note`. - -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. Project notes can be added anywhere in the -project. - -The project tree can distinguish between the different layouts and header levels of the documents -using coloured icons, and optionally add emphasis on the label (See the :guilabel:`Preferences`.) -For novel documents, the heading level of the first heading is recorded, and indicated by the icon. - -.. tip:: - You can always start writing with a coarse setup with one or a few documents, and then later use - the split tool to split the documents into separate chapter and scene documents. You can split a - document on any of the four header levels. diff --git a/docs/source/usage_breakdown.rst b/docs/source/usage_breakdown.rst index c1f3b6a6..c5c1eaca 100644 --- a/docs/source/usage_breakdown.rst +++ b/docs/source/usage_breakdown.rst @@ -152,7 +152,7 @@ The project tree will select an icon for the document based on the first heading 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 the user is free to do -whatever they want. See :ref:`a_struct` and :ref:`a_notes` for more details. +whatever they want. See :ref:`a_struct` and :ref:`a_references` for more details. .. versionadded:: 2.0 You can add documents as child items of other documents. This is often more useful than adding @@ -177,12 +177,12 @@ In addition, you can export the content of the project to a JSON file. This is u to write your own custom processing script in for instance Python, as the entire novel can be read into a Python dictionary with a couple of lines of code. The JSON file can be populated with either HTML formatted text, or with the raw text as typed into the novel documents. -See :ref:`a_export_options` for more details. +See :ref:`a_manuscript_build` for more details. .. versionadded:: 2.1 You can now define multiple build definitions in the :guilabel:`Build Manuscript` tool. This allows you to define specific settings for various types of draft documents, outline documents, - and manuscript formats. See :ref:`a_export` for more details. + and manuscript formats. See :ref:`a_manuscript` for more details. .. _a_breakdown_storage: diff --git a/docs/source/usage_format.rst b/docs/source/usage_format.rst index 98000f83..04d4ccdf 100644 --- a/docs/source/usage_format.rst +++ b/docs/source/usage_format.rst @@ -204,8 +204,8 @@ References are on the form: ``@keyword: value`` A reference keyword followed by a value, or a comma separated list of values. -The available reference keywords are listed in the :ref:`a_struct_tags` section. They can also be -inserted at the cursor position in the editor via the :guilabel:`Insert` menu. +The available reference keywords are listed in the :ref:`a_references_references` section. They can +also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu. .. _a_fmt_align: diff --git a/docs/source/usage_project.rst b/docs/source/usage_project.rst index a86ecd4f..3482534d 100644 --- a/docs/source/usage_project.rst +++ b/docs/source/usage_project.rst @@ -58,16 +58,58 @@ At the top of the tree, you will find a set of buttons. folders. You can also activate this dropdown menu by pressing :kbd:`Ctrl+N`. * The last button is a menu of further actions you can apply to the project tree. -.. tip:: - Under the :guilabel:`Transform` submenu in the context menu of an item, you will find several - options on how to change a document or folder. This includes changing between document and note, - splitting them into multiple documents, or merging child items into a single document. - Below the project tree you will find a small details panel showing the full information of the currently selected item. This panel also includes the latest paragraph and character counts in addition to the word count. +.. _a_ui_tree_split_merge: + +Splitting and Merging Documents +------------------------------- + +Under the :guilabel:`Transform` submenu in the context menu of an item in the project tree, you +will find several options on how to change a document or folder. This includes changing between +document and note, but also splitting them into multiple documents, or merging child items into a +single document. + +Splitting Documents +^^^^^^^^^^^^^^^^^^^ + +.. figure:: images/fig_project_split_tool.png + + The :guilabel:`Split Document` dialog. + +The :guilabel:`Split Document by Header` option will open a dialog that allows you to split the +selected document into multiple new documents based on the headers it contains. You can select at +which header level the split is to be performed from the dropdown box. The list box will preview +which headers will be split into new documents. + +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 to the :guilabel:`Trash` folder. + +Merging Documents +^^^^^^^^^^^^^^^^^ + +.. figure:: images/fig_project_merge_tool.png + + The :guilabel:`Merge Documents` dialog. + +You have two options for merging documents that are child elements of another document. You can +either :guilabel:`Merge Child Items into Self` and :guilabel:`Merge Child Items into New`. The +first option will pull all content of child items and merge them into the parent document, while +the second option will create a new document in the process. + +When merging documents in a folder, you only have the latter process is possible, so only the +choice :guilabel:`Merge Documents in Folder` is available. + +In either case, the :guilabel:`Merge Documents` dialog will let you exclude documents you don't +want to include, and it also lets you reorder them if you wish. + + .. _a_ui_tree_status: Document Importance and Status