From 4e7e888a53cba75937a3ad56987c6ad11005fbd0 Mon Sep 17 00:00:00 2001 From: "Veronica K. B. Olsen" <1619840+vkbo@users.noreply.github.com> Date: Thu, 6 Aug 2020 23:06:51 +0200 Subject: [PATCH] Edited the remaining documentation files --- docs/source/export.rst | 145 ++++++++++++++++++++++++++------------ docs/source/notes.rst | 46 ++++++++---- docs/source/technical.rst | 72 ++++++++++++------- 3 files changed, 176 insertions(+), 87 deletions(-) diff --git a/docs/source/export.rst b/docs/source/export.rst index 5297deb8..36637695 100644 --- a/docs/source/export.rst +++ b/docs/source/export.rst @@ -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. -You can also use ``%chi%`` or ``%chI%`` for lower and upper case Roman numbers. -The number is incremented by one each time the build tool sees a new heading of level two in a file with layout "Chapter". -If the file has layout "Unnumbered", the counter is *not* incremented. -The latter is useful for for instance Prologue and Epilogue chapters. +``%ch%`` + This is 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 file with layout :guilabel:`Chapter`. If the file has layout + :guilabel:`Unnumbered`, the counter is *not* incremented. The latter is useful for for instance + Prologue and Epilogue chapters. -Likewise, the keywords ``%sc%`` and ``%sca%`` are number counters for scene files. -These are incremented each time a heading of level three is encountered. -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. +``%chw%`` + This is like ``%ch%``, but the number is expressed as a word like for instance "One", "Two", etc. -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. - 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. + Header formatting only applies to novel files. Headings in note files will will be left as-is on + 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. -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. +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. + +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. -The switch for "Include novel files" will select any file that isn't classified as a note. -That is, files with layout "Book", "Page", "Partition", "Chapet", "Unnumbered", or "Scene". -The switch for "Include note files" will select any file that is a note. -That is, files with layout "Note". -This is allows for exporting just the novel, just your notes, or both, as you see fit. +Which files are selected for export can also be controlled from the options on the left side of the +dialog window. The switch for :guilabel:`Include novel files` will select any file that isn't +classified as a note. That is, files with layout "Book", "Page", "Partition", "Chapet", +"Unnumbered", or "Scene". The switch for :guilabel:`Include note files` will select any file that is +a note. That is, files with layout "Note". This is allows for exporting just the novel, just your +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. -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. +In addition, you can select to export the synopsis comments, regular comments, keywords, and even +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. -An included file has a checkmark after the status icon in the "Flags" column. -The "Build Novel Project" tool has a switch to ignore this flag if you need to collectively override these settings. +.. 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 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. -The document produced has very little formatting, and may require further editing afterwards. -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. +This is produces an open document ``.odt`` file. The document produced has very little formatting, +and may require further editing afterwards. 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. + 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 exported HTML file is suitable for further processing by document conversion tools like Pandoc, for importing in word processors, or for printing from browser. +The HTML export format writes a single ``.htm`` file with minimal style formatting. 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. + novelWriter Markdown ==================== -This is simply a concatenation of the files selected by the filters. -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. -This is a useful format for exporting the project for later import back into novelWriter. +This is simply a concatenation of the files selected by the filters. 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. 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. -This feature uses Qt's own Markdown export feature. +If you have Qt 5.14 or higher, the option to export to plain Markdown is available. This 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. -The files will have a meta data entry and a body entry. -For HTML, also the accompanying css styles are exported. +In addition to the above document formats, the novelWriter HTML and Markdown formats can also be +wrapped in a JSON file. The files will have a meta data entry and a body entry. For HTML, also the +accompanying css styles are exported. -The text body is saved in a two-level list. -The outer list contains one entry per exported file, in the order they appear in the project tree. -Each file is then split up into a lst as well, with one entry per line. +The text body is saved in a two-level list. The outer list contains one entry per exported file, in +the order they appear in the project tree. Each file is then split up into a lst as well, with one +entry per line. -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. +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/notes.rst b/docs/source/notes.rst index 6b3b68a4..5368cb6a 100644 --- a/docs/source/notes.rst +++ b/docs/source/notes.rst @@ -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. -These files are intended for summaries and outlines of the various plot elements, characters, locations, and so on, of the novel. -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. +Supporting files, or notes, are any file stored in root folders that are not a part of the novel +story itself. These files are intended for summaries and outlines of the various plot elements, +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. -Duplicate tags should be detected as long as the index is up to date. +.. _a_notes_tags: -The tag is the only part of these files that the application uses. -The rest of the file is there for the writer to use in whatever way they wish. +Tags in Notes +============= -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. +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. 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. diff --git a/docs/source/technical.rst b/docs/source/technical.rst index 882e7c50..7ceb6593 100644 --- a/docs/source/technical.rst +++ b/docs/source/technical.rst @@ -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. -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. -This is handled entirely by the Python standard library. +All novelWriter files are written with utf-8 encoding. 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. 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. -This 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. +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. This +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. -It is important to keep this file backed up, either through the built-in backup tool, or your own backup solution. +If this file is lost or corrupted, the structure of the project is lost. It is important to keep +this file backed up, either through the built-in backup tool, or your own backup solution. -.. note:: - The novelWriter project folder is structured so that it can easily be added to a version control 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. +.. tip:: + The novelWriter project folder is structured so that it can easily be added to a version control + 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``. -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. -The documents are saved with a filename assembled from this hash and the file extension ``.nwd``. -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. +The project documents are saved in a folder in the main project folder named ``content``. 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. The documents are saved with a filename assembled from this hash +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. -The file meta data in the tree view, except the file label, is only saved in the project XML file. +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, 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 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 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. 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. -This ensures that the previously saved data is only replaced when the new data has been successfully 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. +If successful, the old data file is removed, and the temporary file becomes the new file. This +ensures that the previously saved data is only replaced when the new data has been successfully +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.