Edited the remaining documentation files

2020-08-06 23:06:51 +02:00
parent f227099eb4
commit 4e7e888a53
3 changed files with 176 additions and 87 deletions
@@ -4,58 +4,99 @@
 Exporting Projects
 ##################
-The novelWriter project can be exported in various formats using the build tool available from :menuselection:`Project --> Build Project` or by pressing :kbd:`F5`.
+The novelWriter project can be exported in various formats using the build tool available from
 :guilabel:`Build Novel Project` in the :guilabel:`Tools` menu, or by pressing :kbd:`F5`.
 .. _a_export_headers:
 *****************
 Header Formatting
 *****************
 The titles for the four levels of story structure can be formatted collectively in the export tool.
-This is done through a series of keyword–replace steps.
+This is done through a series of keyword–replace steps. They are all on the format ``%keyword%``.
-The keyword ``%title%`` will always be replaced by the text you put after the ``#`` characters in your document.
+``%title%``
   This keyword will always be replaced with the title text you put after the ``#`` characters in
   your document.
-The keywords ``%ch%`` and ``%chw%`` is replaced by a number, or a number word, respectively.
+``%ch%``
-You can also use ``%chi%`` or ``%chI%`` for lower and upper case Roman numbers.
+   This is replaced by a chapter number. The number is incremented by one each time the build tool
-The number is incremented by one each time the build tool sees a new heading of level two in a file with layout "Chapter".
+   sees a new heading of level two in a file with layout :guilabel:`Chapter`. If the file has layout
-If the file has layout "Unnumbered", the counter is *not* incremented.
+   :guilabel:`Unnumbered`, the counter is *not* incremented. The latter is useful for for instance
-The latter is useful for for instance Prologue and Epilogue chapters.
+   Prologue and Epilogue chapters.
-Likewise, the keywords ``%sc%`` and ``%sca%`` are number counters for scene files.
+``%chw%``
-These are incremented each time a heading of level three is encountered.
+   This is like ``%ch%``, but the number is expressed as a word like for instance "One", "Two", etc.
 The former keyword is reset to one for each new chapter, while the latter is not reset but counts from first scene encountered in the project.
-If you want to insert a line break in your title format, add two backslashes ``\\``.
+``%chi%``
   This is also like ``%ch%``, but the number is represented as a lower case Roman number.
 ``%chI%``
   This is also like ``%ch%``, but the number is represented as an upper case Roman number.
 ``%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%``
   This is like ``%sc%``, but the number is *not* reset to 1 for each chapter. Instead it runs from
   1 from the beginning of the novel.
 ``\\``
   This inserts a line break within the title.
 .. note::
-   Header formatting only applies to novel files.
+   Header formatting only applies to novel files. Headings in note files will will be left as-is on
-   Headings in note files will will be left as-is, but heading levels 1 through 4 are converted to the correct heading level in the respective output formats.
+   export. However, heading levels 1 through 4 are converted to the correct heading level in the
   respective output formats.
 .. _a_export_scenes:
 ****************
 Scene Separators
 ****************
-If you don't want any titles for your scenes (and for your sections if you have them), you can leave the boxes empty, and an empty paragraph will be inserted between the scenes or sections instead.
+If you don't want any titles for your scenes (and for your sections if you have them), you can leave
-Alternatively, if you want a separator between them, like the common "\*\*\*", you can also enter that in the box.
+the boxes empty, and an empty paragraph will be inserted between the scenes or sections instead.
-In fact, if the format is a piece of static text, it will always be treated as a separator.
+
 Alternatively, if you want a separator between them, like the common ``* * *``, you can also enter
 that in the 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 files are selected for export can be controlled from the options on the left side of the dialog window.
+Which files are selected for export can also be controlled from the options on the left side of the
-The switch for "Include novel files" will select any file that isn't classified as a note.
+dialog window. The switch for :guilabel:`Include novel files` will select any file that isn't
-That is, files with layout "Book", "Page", "Partition", "Chapet", "Unnumbered", or "Scene".
+classified as a note. That is, files with layout "Book", "Page", "Partition", "Chapet",
-The switch for "Include note files" will select any file that is a note.
+"Unnumbered", or "Scene". The switch for :guilabel:`Include note files` will select any file that is
-That is, files with layout "Note".
+a note. That is, files with layout "Note". This is allows for exporting just the novel, just your
-This is allows for exporting just the novel, just your notes, or both, as you see fit.
+notes, or both, as you see fit.
-In addition, you can select to export the synopsis comments, regular comments, keywords, and even exclude the body text itself.
+In addition, you can select to export the synopsis comments, regular comments, keywords, and even
-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.
+exclude the body text itself.
-If you need to exclude specific files from your exports, like draft files or files you want to take out of your build, but don't want to delete, you can uncheck the "Include when building project" option for each file in the project tree.
+.. tip::
-An included file has a checkmark after the status icon in the "Flags" column.
+   If you for instance want to export a document with an outline of the novel, you can enable
-The "Build Novel Project" tool has a switch to ignore this flag if you need to collectively override these settings.
+   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 files from your exports, like draft files or files you want to take
 out of your build, but don't want to delete, you can un-check the :guilabel:`Include when building
 project` option for each file in the project tree. An included file has a checkmark after the status
 icon in the :guilabel:`Flags` column. The :guilabel:`Build Novel Project` tool has a switch to
 ignore this flag if you need to collectively override these settings.
 .. _a_export_formats:
 **************
 Export Formats
@@ -63,53 +104,65 @@ Export Formats
 Currently, six formats are supported for exporting.
 OpenDocument Format
 ===================
-This is produces an open document ``.odt`` file.
+This is produces an open document ``.odt`` file. The document produced has very little formatting,
-The document produced has very little formatting, and may require further editing afterwards.
+and may require further editing afterwards. For a better formatted office document, you may get a
-For a better formatted office document, you may get a better result with exporting to HTML and the import that HTML document in your office word processor.
+better result with exporting to HTML and the import that HTML document in your office word
 processor.
 PDF Format
 ==========
 The PDF export is just a shortcut for print to file.
 novelWriter HTML
 ================
-The HTML export format writes a single ``.htm`` file with minimal style formatting.
+The HTML export format writes a single ``.htm`` file with minimal style formatting. The exported
-The exported HTML file is suitable for further processing by document conversion tools like Pandoc, for importing in word processors, or for printing from browser.
+HTML file 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 files selected by the filters.
+This is simply a concatenation of the files selected by the filters. The files in the project are
-The files in the project are stacked together in the order they appear in the tree view, with comments, tags, etc. included if they are selected.
+stacked together in the order they appear in the tree view, with comments, tags, etc. included if
-This is a useful format for exporting the project for later import back into novelWriter.
+they are selected. This is a useful format for exporting the project for later import back into
 novelWriter.
 Standard Markdown
 =================
-If you have Qt 5.14 or higher, the option to export to plain Markdown is available.
+If you have Qt 5.14 or higher, the option to export to plain Markdown is available. This feature
-This feature uses Qt's own Markdown export feature.
+uses Qt's own Markdown export feature.
 Plain Text
 ==========
 The plain text export format writes a simple ``.txt`` file without any formatting at all.
 .. _a_export_options:
 *************************
 Additional Export Options
 *************************
-In addition to the above document formats, the novelWriter HTML and Markdown formats can also be wrapped in a JSON file.
+In addition to the above document formats, the novelWriter HTML and Markdown formats can also be
-The files will have a meta data entry and a body entry.
+wrapped in a JSON file. The files will have a meta data entry and a body entry. For HTML, also the
-For HTML, also the accompanying css styles are exported.
+accompanying css styles are exported.
-The text body is saved in a two-level list.
+The text body is saved in a two-level list. The outer list contains one entry per exported file, in
-The outer list contains one entry per exported file, in the order they appear in the project tree.
+the order they appear in the project tree. Each file is then split up into a lst as well, with one
-Each file is then split up into a lst as well, with one entry per line.
+entry per line.
-These files are mainly intended for scripted post-processing for those who want that option.
+These files are mainly intended for scripted post-processing for those who want that option. A JSON
-A JSON file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
+file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
@@ -4,22 +4,40 @@
 Supporting Files (Notes)
 ************************
-Supporting files, or notes, are any files stored in root folders that are not the Novel root folder.
+Supporting files, or notes, are any file stored in root folders that are not a part of the novel
-These files are intended for summaries and outlines of the various plot elements, characters, locations, and so on, of the novel.
+story itself. These files are intended for summaries and outlines of the various plot elements,
-These are not required, but making at least minimal files for each such element, and add a tag to them, makes it possible to use the Outline View feature to see how each element intersects with each section of the novel itself, and add clickable cross-references between document in the editor and viewer.
+characters, locations, and so on, of the novel.
-File Tags
+These files are not required, but making at least minimal files for each such plot element, and add
-=========
+a tag to them, makes it possible to use the :guilabel:`Outline` feature to see how each element
 intersects with each section of the novel itself, and add clickable cross-references between
 documents in the editor and viewer.
 Each new heading in a note file can have a tag associated with it.
 The format of a tag is ``@tag: tagname``, where tagname is a unique identifier.
 Tags can then be referenced in the novel files, or other note files, and will show up in the Outline View and in the back-reference panel when a document is being viewed.
-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.
+.. _a_notes_tags:
 Duplicate tags should be detected as long as the index is up to date.
-The tag is the only part of these files that the application uses.
+Tags in Notes
-The rest of the file is there for the writer to use in whatever way they wish.
+=============
-A note file can also reference other note files in the same way novel files do.
+Each new heading in a note file can have a tag associated with it. The format of a tag is
-When the note file is opened in the view pane, these become clickable links, making it easier to follow connections in the plot.
+``@tag: tagname``, where tagname is a unique identifier. Tags can then be referenced in the novel
 files, or other note files, and will show up in the outline view and in the back-reference panel
 when a document is being viewed.
 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 files that the application uses. The rest of the file content is
 there for the writer to use in whatever way they wish. Of course, the content of the files can be
 exported if you want to compile a single document of all your notes, or include them in an outline.
 A note file can also reference other note files in the same way novel files do. When the note file
 is opened in the view pane, these become clickable links, making it easier to follow connections in
 the plot. Note files 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.
 .. tip::
   If you cross-reference between notes as well, and export your project as an HTML file using the
   export tool, the cross-references also become clickable in the exported document.
@@ -6,52 +6,70 @@ Technical Information
 This section contains details of how novelWriter stores and handles the project data.
 How Data is Stored
 ==================
-All novelWriter files are written with utf-8 encoding.
+All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix line
-Since Python automatically converts Unix line endings to Windows line endings on Windows systems, novelWriter does not make any adaptations to the formatting on Windows systems.
+endings to Windows line endings on Windows systems, novelWriter does not make any adaptations to the
-This is handled entirely by the Python standard library.
+formatting on Windows systems. This is handled entirely by the Python standard library.
 Main Project File
 -----------------
-The project itself requires a dedicated folder for storing its files, where novelWriter will create its own "file system" where the folder and file hierarchy is described in a project XML file.
+The project itself requires a dedicated folder for storing its files, where novelWriter will create
-This is the main project file in the project's root folder with the name ``nwProject.nwx``.
+its own "file system" where the folder and file hierarchy is described in a project XML file. This
-This file also contains all the meta data required for the project, and a number of related project settings.
+is the main project file in the project's root folder with the name ``nwProject.nwx``. This file
 also contains all the meta data required for the project, and a number of related project settings.
-If this file is lost or corrupted, the structure of the project is lost.
+If this file is lost or corrupted, the structure of the project is lost. It is important to keep
-It is important to keep this file backed up, either through the built-in backup tool, or your own backup solution.
+this file backed up, either through the built-in backup tool, or your own backup solution.
-.. note::
+.. tip::
-   The novelWriter project folder is structured so that it can easily be added to a version control system like git.
+   The novelWriter project folder is structured so that it can easily be added to a version control
-   If so, you may want to add a `.gitignore` file to exclude files with the extensions `.json` as JSON files are used to cache the index and various run-time settings.
+   system like git. If so, you may want to add a `.gitignore` file to exclude files with the
   extensions `.json` as JSON files are used to cache the index and various run-time settings and
   are generally large files that change often. You'd also want to exclude the ``cache`` folder.
 The project XML file is indent-formatted, suitable for diff tools and version control, although a
 timesetamp is set in the meta section on line 2 each time the file is saved.
 The project XML file is indent-formatted, suitable for diff tools and version control, although a timesetamp is set in the meta section on line 2 each time the file is saved.
 Project Documents
 -----------------
-The project documents are saved in a folder in the main project folder named ``content``.
+The project documents are saved in a folder in the main project folder named ``content``. Each
-Each document has a file handle taken from the first 13 characters of a SHA256 hash of the system time when the file was first created.
+document has a file handle taken from the first 13 characters of a SHA256 hash of the system time
-The documents are saved with a filename assembled from this hash and the file extension ``.nwd``.
+when the file was first created. The documents are saved with a filename assembled from this hash
-If you wish to find the physical location of a file in the project, you can either look it up in the project XML file, or select :menuselection:`Document --> Show File Details` in the menu when having the document open.
+and the file extension ``.nwd``.
-The reason for this cryptic file naming is to avoid issues with file naming conventions and restrictions on different operating systems, and also to have a file name that does not depend on what the user names the files, or changes it to.
+If you wish to find the physical location of a file in the project, you can either look it up in the
-The file meta data in the tree view, except the file label, is only saved in the project XML file.
+project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu when
 having the document open, or look in one of the ``ToC`` files in the root of the project folder.
-Each document file contains a plain text version of the text from the editor.
+The reason for this cryptic file naming is to avoid issues with file naming conventions and
-The file can in principle be edited in any text editor, and is suitable for diffing and version control if so desired.
+restrictions on different operating systems, and also to have a file name that does not depend on
-Just make sure the file remains in utf-8 encoding, otherwise unicode chatracters may become mangled when opened in novelWriter again.
+what the user names the files, or changes it to. The file meta data in the tree view, except the
 file label, is only saved in the project XML file.
 Each document file contains a plain text version of the text from the editor. The file can in
 principle be edited in any text editor, and is suitable for diffing and version control if so
 desired. Just make sure the file remains in utf-8 encoding, otherwise unicode chatracters may become
 mangled when opened in novelWriter again.
 The first line of the file contains some meta data starting with the characters ``%%~``. This line
 is mainly there to restore some information if it is lost from the project file, and the information
 may be helpful if you do open the file in an external editor as it contains the file label as the
 last entry. The line can be deleted without any consequences to the rest of the content of the file,
 and will be added back next time the file is saved in novelWriter.
 The first line of the file contains some meta data starting with the characters "%%~".
 This line is mainly there to restore some information if it is lost from the project file, and the information may be helpful if you do open the file in an external editor as it contains the file label as the last entry.
 The line can be deleted without any consequences to the rest of the content of the file, and will be added back next time the file is saved in novelWriter.
 The File Saving Process
 -----------------------
 When saving the project file, or any of the documents, the data is first saved to a temporary file.
-If successful, the old data file is removed, and the temporary file becomes the new file.
+If successful, the old data file is removed, and the temporary file becomes the new file. This
-This ensures that the previously saved data is only replaced when the new data has been successfully saved.
+ensures that the previously saved data is only replaced when the new data has been successfully
-For the project XML file, a `.bak` file is kept which will always contain the previous version of the file, although when auto-save is enabled, they may have the same content.
+saved. For the project XML file, a ``.bak`` file is kept which will always contain the previous
 version of the file, although when auto-save is enabled, they may have the same content.