From f7c768bb91fb8a1160ca9d3115f6e78dce2c42ec Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Tue, 17 Aug 2021 20:06:26 +0200 Subject: [PATCH] Add project format documentation and popup box (#855) * Add documentation of the various project file formats * Add an info box for updating to project format 1.3 * Add information on how to access the documentation * Add a note on file format and rename a few things * Fix some typos --- CHANGELOG.md | 2 +- docs/source/index.rst | 6 ++ docs/source/usage_projectformat.rst | 92 +++++++++++++++++++++++++++++ nw/core/project.py | 10 ++++ 4 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 docs/source/usage_projectformat.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index c5649b6d..a8a58fe9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1793,7 +1793,7 @@ planned by GitHub. See their [notes](https://github.com/github/renaming) for mor ---- -## Version 0.10.0 [2020-06-30] +## Version 0.10 [2020-06-30] **Note:** If the project file is opened by this version of novelWriter, the project file can no longer be read by an earlier version due to the change of how autoReplace settings are stored. diff --git a/docs/source/index.rst b/docs/source/index.rst index 115487f8..6c0eb7f2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -48,6 +48,11 @@ This package can be extracted anywhere on your computer, and a setup script can the necessary icons and file associations. See :ref:`a_started`, or one or the setup instructions for your operating system for further details. +.. note:: + Version 1.5 introduces a few changes that will require you to make a few minor modifications to + some of the headings in your project. It should be fairly quick and straightforward. Please see + the :ref:`a_prjfmt_1_3` section for more details. + **Useful Links** * Website: https://novelwriter.io @@ -78,6 +83,7 @@ for your operating system for further details. usage_format usage_shortcuts usage_typography + usage_projectformat .. toctree:: diff --git a/docs/source/usage_projectformat.rst b/docs/source/usage_projectformat.rst new file mode 100644 index 00000000..ea0b55b5 --- /dev/null +++ b/docs/source/usage_projectformat.rst @@ -0,0 +1,92 @@ +.. _a_prjfmt: + +********************** +Project Format Changes +********************** + +Most of the changes to the file formats over the history of novelWriter have no impact on the +user-side of things. The project files are generally updated automatically. However, some of the +changes require minor actions from the user. + +The key changes in the formats are listed below, as well as the user actions required where +applicable. + + +.. _a_prjfmt_1_3: + +Format 1.3 Changes +================== + +This project format vas introduces in novelWriter version 1.5. + +With this format, the number of document layouts was reduced from 8 to 2. The conversion of +document layouts is performed automatically when the project is opened. + +Due to the reduction of layouts, some features that were previously controlled by these layouts +will be lost. These features are instead now controlled by syntax codes, so to recover these +features, some minor modification must be made to select documents by the user. + +The manual changes the user must make should be very few as they apply to document layouts that +should be used only a few places in any given project. These are as follows: + +**Title Pages** + +* The formatting of the level one title on the title page must be changed from ``# Title Text`` to + ``#! Title Text`` in order to retain the previous functionality. See :ref:`a_fmt_head`. +* Any text that was previously centred on the page must be manually centred using the new text + alignment feature. See :ref:`a_fmt_align`. + +**Unnumbered Chapters** + +* Since the specific layout for unnumbered chapters has been dropped, such chapters must all use + the ``##! Chapter Name`` formatting code instead of ``## Chapter Name``. This also includes + chapters marked by an asterisk: ``## *Chapter Name``, as this feature has also been dropped. + See :ref:`a_fmt_head`. + +**Plain Pages** + +* The layout named "Plain Page" has also been removed. The only feature of this layout was that it + ensured that the content always started on a fresh page. In the new format, fresh pages can be + set anywhere in the text with the ``[NEW PAGE]`` code. See :ref:`a_fmt_break`. + + +.. _a_prjfmt_1_2: + +Format 1.2 Changes +================== + +This project format was introduces in novelWriter version 0.10. + +With this format, the way auto-replace entries were stored in the main project XML file changed. +Opening an old project automatically converts the storage format up to and including version 1.1.1. + +Format 1.2 projects can be opened without loss of information up until version 1.1.1, and if the +auto-replace is not being used, can still be opened in novelWriter as of version |release|. + + +.. _a_prjfmt_1_1: + +Format 1.1 Changes +================== + +This project format was introduces in novelWriter version 0.7. + +With this format, the ``content`` folder was introduced in the project storage. Previously, all +novelWriter documents were saved in a series of folders numbered from ``data_0`` to ``data_f``. + +It also reduces the number of meta data and cache files. These files are automatically deleted if +an old project is opened. This was also when the Table of Contents file was introduced. + +Format 1.1 projects can be opened without loss of information up until version 1.1.1, and if the +auto-replace is not being used, can still be opened in novelWriter as of version |release|. + + +.. _a_prjfmt_1_0: + +Format 1.0 Changes +================== + +This is the original file format and project structure. It was in use up to version 0.6.3. + +Format 1.0 projects can be opened without loss of information up until version 1.1.1, and if the +auto-replace is not being used, can still be opened in novelWriter as of version |release|. diff --git a/nw/core/project.py b/nw/core/project.py index 7ca73a32..81c9bdeb 100644 --- a/nw/core/project.py +++ b/nw/core/project.py @@ -491,6 +491,16 @@ class NWProject(): self.clearProject() return False + if fileVersion in ("1.0", "1.1", "1.2"): + self.makeAlert(self.tr( + "The format of your project will now be updated. You may " + "also have to make a few minor changes to your title page " + "and unnumbered chapters. Please check the 'Project " + "Format Changes > File Format 1.3' section of the " + "documentation for more information. It is avialable from " + "the Help menu." + ).format(appVersion), nwAlert.INFO) + # Check novelWriter Version # =========================