novelWriter/docs/source/user_interface/manuscript.rst

.. _docs_ui_manuscript:

***********************
Building the Manuscript
***********************

.. _Pandoc: https://pandoc.org/

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 **Manuscript Build** tool. You can
activate it from the sidebar, the **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 the build, but otherwise had much the same
   functionality.


.. _docs_ui_manuscript_main:

The Manuscript Build Tool
=========================

.. figure:: images/fig_manuscript_build.png
   :width: 80%

   The **Manuscript Build** tool main window.

The main window of the **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.


Outline and Word Counts
-----------------------

.. figure:: images/fig_manuscript_build_outline.png
   :width: 80%

   The **Manuscript Build** tool main window with the **Outline** visible.

The **Outline** tab on the left lets you navigate the headings in the preview document. It will
show up to scene level headings for novel documents, and level 2 headings for notes.

A collapsible panel of word and character counts are also available below the preview document.
These are calculated from the text you have included in the document, and are more accurate counts
than what's available in the project tree since they are counted *after formatting*.

For a detailed description on how they are counted, see :ref:`docs_more_counting`.


.. _docs_ui_manuscript_settings:

Build Settings
==============

Each build definition can be edited by opening it in the **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 **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 **Manuscript Build** window. When you're happy with
   the result, you can close the settings.


.. _docs_ui_manuscript_selection:

Document Selection
------------------

.. figure:: images/fig_build_settings_selections.png
   :width: 80%

   The **Selections** page of the **Manuscript Build Settings** dialog.

The **Selections** page of the **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.

By default, inactive documents are excluded, but you can override this in the filter settings.
See :ref:`docs_usage_project_active` for more details.


.. _docs_ui_manuscript_head:

Formatting Headings
-------------------

.. figure:: images/fig_build_settings_headings.png
   :width: 80%

   The **Headings** page of the **Manuscript Build Settings** dialog.

The **Headings** page of the **Manuscript Build Settings** dialog allows you to set how the
headings in your Novel Documents are formatted. By default, the title is just copied as-is,
indicated by the ``{Title}`` format. You can change this to for instance add chapter numbers and
scene numbers, or insert character names, like shown in the figure above.

Clicking the edit button next to a format will copy the formatting string into the edit box where
it can be modified, and where a syntax highlighter will help indicate which parts are automatically
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.

.. csv-table:: Heading Formats
   :header: "Code", "Description"
   :class: "tight-table"

   "``{BR}``",             "Insert a line break."
   "``{Title}``",          "Insert the original title text."
   "``{Chapter}``",        "Insert a chapter number."
   "``{Chapter:Word}``",   "Insert a chapter number as a word."
   "``{Chapter:URoman}``", "Insert a chapter number as an upper case Roman numeral."
   "``{Chapter:LRoman}``", "Insert a chapter number as an lower case Roman numeral."
   "``{Scene}``",          "Insert a scene number within the current chapter."
   "``{Scene:Abs}``",      "Insert a scene number unique to the whole manuscript."
   "``{Char:POV}``",       "Insert the point-of-view character's :ref:`display name <docs_usage_tags_refs_tags>`."
   "``{Char:Focus}``",     "Insert the focus character's :ref:`display name <docs_usage_tags_refs_tags>`."

You can preview the result of these format strings by clicking :guilabel:`Apply`, and then clicking
:guilabel:`Preview` in the **Manuscript Build** tool main window.


.. _docs_ui_manuscript_head_numbers:

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_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
that reset to 1 for each chapter.

:bdg-info:`Example`

This will create a chapter title on the format "Chapter 1: Title Text":

.. code-block:: md

   Chapter {Chapter}: {Title}

This will create a scene title on the format "Scene 1.1: Title Text":

.. code-block:: md

   Scene {Chapter}.{Scene}: {Title}


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 inserted.

Alternatively, if you want a separator text between them, like the common ``* * *``, you can enter
the desired separator text as the format. If the format is any piece of static text, it will always
be treated as a separator.


.. _docs_ui_manuscript_head_hard_soft:

Hard and Soft Scenes
^^^^^^^^^^^^^^^^^^^^

If you wish to distinguish between so-called soft and hard scene breaks, you can use the
alternative scene heading format in your text. You can then give these headings a different
formatting in the **Headings** settings.

See :ref:`docs_usage_headings_levels` for more info on how to format headings in your text.


Output Settings
---------------

The **Content**, **Format** and **Output** pages of the **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.


.. _docs_ui_manuscript_build:

Building Manuscript Documents
=============================

.. figure:: images/fig_build_build.png
   :width: 80%

   The **Manuscript Build** dialog used for writing the actual manuscript documents.

When you press the :guilabel:`Build` button on the **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 side of the dialog is a list of all the available file formats, and on the right, a
list of the documents which are included based on the build definition you selected. You can choose
an output path, and set a base file name as well. The file extension will be added automatically.

To generate the manuscript document, press the :guilabel:`Build` button. A small progress bar will
show the build progress, but for small projects it may pass very fast.


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 only a few the latter.

Microsoft Word Document Format
   The Microsoft Word Document format writes a single ``.docx`` file. It uses a fairly basic format
   that should be compatible with most rich text editors.

Portable Document Format (PDF)
   The PDF is generated from a copy of the preview document, and should have the same formatting
   capabilities as the preview. It's identical to what is produced if you select the print option
   and print to PDF.

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.

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 strike through text, which is not supported by
   the Standard flavour.

novelWriter Markup
   This is simply a concatenation of the project documents selected by the filters into a ``.txt``
   file. The documents are stacked together in the order they appear in the project tree, with
   comments, tags, etc. included if they are selected. This is a useful format for exporting the
   project for later import back into novelWriter.

.. versionadded:: 2.6

   Microsoft Word and PDF output options were added.


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 used by the preview are included.

The text body is saved in a two-level list. The outer list contains one entry per document, in the
order they appear in the project tree. Each document is then split up into a list as well, with one
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.


.. _docs_ui_manuscript_print:

Printing
========

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 **Print Preview** dialog.