Reproog/novelWriter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the additional topics section of the docs

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2023-10-15 17:41:22 +02:00
parent 56b4cd3036
commit b16f4477b8
2 changed files with 44 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/tech_storage.rst
+42 -47
View File
@@ -13,10 +13,10 @@ Project Structure
================= =================
All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix 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 line endings to Windows line endings on Windows systems, and vice versa, novelWriter does not make
to the formatting on Windows systems. This is handled entirely by the Python standard library. any adaptations to the formatting on Windows systems. This is handled entirely by the Python
Python also handles this when working on the same files on both Windows and Unix-based operating standard library. Python also handles this when working on the same files on both Windows and
systems. Unix-based operating systems.
Main Project File Main Project File
@@ -25,18 +25,13 @@ Main Project File
The project itself requires a dedicated folder for storing its files, where novelWriter will create 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 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 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. also contains all the meta data required for the project (except the index data), and a number of
related project settings.
If this file is lost or corrupted, the structure of the project is lost, although not the text If this file is lost or corrupted, the structure of the project is lost, although not the text
itself. It is important to keep this file backed up, either through the built-in backup tool, or itself. It is important to keep this file backed up, either through the built-in backup tool, or
your own backup solution. your own backup solution.
.. tip::
The novelWriter project folder is structured so that it can easily be added to a version control
system like git. If you do 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.
The project XML file is indent-formatted, and is suitable for diff tools and version control since The project XML file is indent-formatted, and is suitable for diff tools and version control since
most of the file will stay static, although a timesetamp is set in the meta section on line 2, and most of the file will stay static, although a timesetamp is set in the meta section on line 2, and
various meta data entries incremented, on each save. various meta data entries incremented, on each save.
@@ -54,34 +49,35 @@ various meta data entries incremented, on each save.
Project Documents Project Documents
================= =================
All the project documents are saved in a folder in the main project folder named ``content``. Each All the project documents are saved in a subfolder of the main project folder named ``content``.
document has a file handle based on a 52 bit random number, represented as a hexadecimal string. Each document has a file handle based on a 52 bit random number, represented as a hexadecimal
The documents are saved with a filename assembled from this handle and the file extension ``.nwd``. string. The documents are saved with a filename assembled from this handle and the file extension
``.nwd``.
If you wish to find the file system location of a document in the project, you can either look it If you wish to find the file system location of a document in the project, you can either look it
up in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu up in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu
when having the document open, or look in the ``ToC.txt`` file in the root of the project folder. when having the document open in the editor, or look in the ``ToC.txt`` file in the root of the
The ``ToC.txt`` file has a list of all documents in the project, referenced by their label, and project folder. The ``ToC.txt`` file has a list of all documents in the project, referenced by
where they are saved. their label, and where they are saved.
The reason for this cryptic file naming is to avoid issues with file naming conventions and 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 restrictions on different operating systems, and also to have a file name that does not depend on
what the user names the document within the project, or changes it to. This is particularly useful what you name the document within the project, or changes it to. This is particularly useful when
when using a versioning system. using a versioning system.
Each document file contains a plain text version of the text from the editor. The file can in 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 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 characters may desired. Just make sure the file remains in utf-8 encoding, otherwise unicode characters may
become mangled when the file is opened in novelWriter again. become mangled when the file is opened in novelWriter again.
Editing these files is generally not recommended outside of special circumstances, whatever they Editing these files is generally not recommended. The reason for this is that the index will not be
may be. The reason for this is that the index will not be automatically updated when doing so, automatically updated when doing so, which means novelWriter doesn't know you've altered the file.
which means novelWriter doesn't know you've altered the file. If you do edit a file in this manner, If you *do* edit a file in this manner, you should rebuild the index when you next open the project
you should rebuild the index when you next open the project in novelWriter. in novelWriter.
The first lines of the file may contain some meta data starting with the characters ``%%~``. These The first lines of the file may contain some meta data starting with the characters ``%%~``. These
lines are mainly there to restore some information if it is lost from the project file, and the lines are mainly there to restore some information if the file is lost from the main project file,
information may be helpful if you do open the file in an external editor as it contains the and the information may be helpful if you do open the file in an external editor as it contains the
document label and the document class and layout. The lines can be deleted without any consequences document label and the document class and layout. The lines can be deleted without any consequences
to the rest of the content of the file, and will be added back the next time the document is saved to the rest of the content of the file, and will be added back the next time the document is saved
in novelWriter. in novelWriter.
@@ -91,9 +87,9 @@ The File Saving Process
----------------------- -----------------------
When saving the project file, or any of the documents, the data is first saved to a temporary file. 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 then removed, and the temporary file becomes the new file. This If successful, the old data file is then removed, and the temporary file replaces it. This ensures
ensures that the previously saved data is only replaced when the new data has been successfully that the previously saved data is only replaced when the new data has been successfully saved to
saved to the storage medium. the storage medium.
For the project XML file, a ``.bak`` file is in addition kept, which will always contain the For the project XML file, a ``.bak`` file is in addition kept, which will always contain the
previous version of the file, although when auto-save is enabled, they may have the same content. previous version of the file, although when auto-save is enabled, they may have the same content.
@@ -106,19 +102,19 @@ Project Meta Data
The project folder contains a subfolder named ``meta``, containing a number of files. The meta The project folder contains a subfolder named ``meta``, containing a number of files. The meta
folder contains semi-important files. That is, they can be lost with only minor impact to the folder contains semi-important files. That is, they can be lost with only minor impact to the
project. project. All files in this folder are JSON or JSON Lines files, although some other files may
remain from earlier versions of novelWriter as they haven't all been JSON files in the past.
If you use version control software on your project, you can exclude this folder, although you may If you use version control software on your project, you can exclude this folder, although you may
want to track the session log file and the custom words list. The JSON files within this folder can want to track the session log file and the custom words list.
safely be ignored as they will be automatically regenerated if lost.
The Project Index The Project Index
----------------- -----------------
Between writing sessions, the project index is saved in a JSON file in ``meta/tagsIndex.json``. Between writing sessions, the project index is saved in a JSON file in ``meta/index.json``.
This file is not critical. If it is lost, it can be rebuilt from within novelWriter from the This file is not critical. If it is lost, it can be completely rebuilt from within novelWriter from
:guilabel:`Tools` menu. the :guilabel:`Tools` menu.
The index is maintained and updated whenever a document or note is saved in the editor. It contains The index is maintained and updated whenever a document or note is saved in the editor. It contains
all references and tags in documents and notes, as well as the location of all headers in the all references and tags in documents and notes, as well as the location of all headers in the
@@ -131,10 +127,17 @@ check somehow fails and novelWriter keeps crashing, you can delete the file manu
the index. If this too fails, you have likely encountered a bug. the index. If this too fails, you have likely encountered a bug.
Build Definitions
-----------------
The build definitions from the :guilabel:`Manuscript Build` tool are kept in the
``meta/builds.json`` file. If this file is lost, all custom build definitions are lost too.
Cached GUI Options Cached GUI Options
------------------ ------------------
A file named ``meta/guiOptions.json`` contains the latest state of various GUI buttons, switches, A file named ``meta/options.json`` contains the latest state of various GUI buttons, switches,
dialog window sizes, column sizes, etc, from the GUI. These are the GUI settings that are specific dialog window sizes, column sizes, etc, from the GUI. These are the GUI settings that are specific
to the project. Global GUI settings are stored in the main config file. to the project. Global GUI settings are stored in the main config file.
@@ -145,7 +148,7 @@ settings.
Custom Word List Custom Word List
---------------- ----------------
A file named ``meta/wordlist.txt`` contains all the custom words you've added to the project for A file named ``meta/userdict.json`` contains all the custom words you've added to the project for
spell checking purposes. The content of the file can be edited from the :guilabel:`Tools` menu. If spell checking purposes. The content of the file can be edited from the :guilabel:`Tools` menu. If
you lose this file, all your custom spell check words will be lost too. you lose this file, all your custom spell check words will be lost too.
@@ -153,18 +156,10 @@ you lose this file, all your custom spell check words will be lost too.
Session Stats Session Stats
------------- -------------
The writing progress is saved in the ``meta/sessionStats.log`` file. This file records the length The writing progress is saved in the ``meta/sessions.jsonl`` file. This file records the length
and word counts of each writing session on the given project. The file is used by the and word counts of each writing session on the given project. The file is used by the
:guilabel:`Writing Statistics` tool. If this file is lost, the history it contains is also lost, :guilabel:`Writing Statistics` tool. If this file is lost, the history it contains is also lost,
but it has otherwise no impact on the project. but it has otherwise no impact on the project.
Each session is recorded as a JSON object on a single line of the file. Each session record is
Project Cache appended tot he file.
=============
The project ``cache`` folder contains non-critical files. If these files are lost, there is no
impact on the functionality of novelWriter or the history of the project. It contains temporary
files, like the preview document in the :guilabel:`Build Novel Project` tool.
It should be excluded from version control tools if such are used. The folder will be removed
entirely in novelWriter 2.1.