Reorganise and update README
This commit is contained in:
Veronica K. B. Olsen
+1
-1
@@ -1,4 +1,4 @@
|
||||
# Contributing
|
||||
# Contributing Guide
|
||||
|
||||
When contributing to this repository, please first discuss the change you wish to make via the
|
||||
issue tracker with the owner of this repository before making a change. If you just want to make a
|
||||
|
||||
@@ -15,81 +15,30 @@
|
||||
|
||||
<img align="left" style="margin: 0 16px 4px 0;" src="https://raw.githubusercontent.com/vkbo/novelWriter/main/setup/icons/scaled/icon-novelwriter-96.png">
|
||||
|
||||
novelWriter is a Markdown-like text editor designed for writing novels and larger projects of many
|
||||
smaller plain text documents. It uses its own flavour of Markdown that supports a meta data syntax
|
||||
for comments, synopsis, and cross-referencing between files. It's designed to be a simple text
|
||||
editor that allows for easy organisation of text files and notes, built on plain text files for
|
||||
robustness.
|
||||
novelWriter is a Markdown-like text editor designed for writing novels assembled from many smaller
|
||||
text documents. It uses a minimal formatting syntax inspired by Markdown, and adds a meta data
|
||||
syntax for comments, synopsis, and cross-referencing between files. It's designed to be a simple
|
||||
text editor that allows for easy organisation of text files and notes, built on plain text files
|
||||
for robustness.
|
||||
|
||||
The plain text storage is suitable for version control software, and also well suited for file
|
||||
synchronisation tools. The core project structure is stored in a project XML file. Other meta data
|
||||
is primarily saved in JSON files.
|
||||
The plain text files are suitable for version control software, and also well suited for file
|
||||
synchronisation tools. The core project structure is stored in a single project XML file. Other
|
||||
meta data is primarily saved in JSON files.
|
||||
|
||||
The full documentation is available at
|
||||
[novelwriter.readthedocs.io](https://novelwriter.readthedocs.io/).
|
||||
|
||||
The contributing guide is available at
|
||||
[CONTRIBUTING](https://github.com/vkbo/novelWriter/blob/main/CONTRIBUTING.md).
|
||||
|
||||
|
||||
## Implementation
|
||||
|
||||
The application is written in Python 3 using Qt5 via PyQt5. It is developed on Linux, but it should
|
||||
in principle work fine on other operating systems as well as long as dependencies are met. The unit
|
||||
tests are run on the latest versions of Ubuntu Linux, Windows Server and macOS.
|
||||
|
||||
## Project Contributions
|
||||
|
||||
# Installing and Running
|
||||
|
||||
For install instructions, please check the [documentation](https://novelwriter.readthedocs.io/) in
|
||||
the [Getting Started](https://novelwriter.readthedocs.io/en/latest/int_started.html) section.
|
||||
|
||||
## TLDR Instructions
|
||||
|
||||
**Note:** You may need to replace `python` with `python3` and `pip` with `pip3` in the instructions
|
||||
below on some systems. You may also want to add the `--user` flag for `pip` to install in your user
|
||||
space only.
|
||||
|
||||
### Install from PyPi
|
||||
|
||||
novelWriter is available on [pypi.org](https://pypi.org/project/novelWriter/), and can be installed
|
||||
with:
|
||||
```bash
|
||||
pip install novelwriter
|
||||
```
|
||||
Dependencies should be installed automatically, but can also be installed directly with:
|
||||
```bash
|
||||
pip install pyqt5 lxml pyenchant
|
||||
```
|
||||
|
||||
### Setup on Linux
|
||||
|
||||
If you're running from source, the following commands will set up novelWriter on Linux:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
python setup.py install
|
||||
python setup.py xdg-install
|
||||
```
|
||||
|
||||
### Setup on macOS
|
||||
|
||||
If you're running from source, the following commands will set up novelWriter on macOS:
|
||||
```bash
|
||||
brew install enchant
|
||||
pip3 install --user -r requirements.txt
|
||||
pip3 install --user pyobjc
|
||||
```
|
||||
|
||||
### Setup on Windows
|
||||
|
||||
For Windows, you can either install via PyPi, or use the Windows installer available from the
|
||||
[releases](https://github.com/vkbo/novelWriter/releases) page.
|
||||
|
||||
## Debugging
|
||||
|
||||
If you need to debug novelWriter, you must run it from command line. It takes a few parameters,
|
||||
which can be listed with the switch `--help`. The `--info`, `--debug` or `--verbose` flags are
|
||||
particularly useful for increasing logging output for debugging.
|
||||
Contributions to this project are welcome. However, please read the Contributing Guide before
|
||||
submitting larger additions ot changes to this project. You can find the guide here:
|
||||
[CONTRIBUTING.md](https://github.com/vkbo/novelWriter/blob/main/CONTRIBUTING.md).
|
||||
|
||||
|
||||
# Key Features
|
||||
@@ -99,8 +48,9 @@ Some features of novelWriter are listed below. Consult the
|
||||
|
||||
### Markdown Flavour
|
||||
|
||||
novelWriter is _not_ a full-feature Markdown editor. It allows for a minimal set of formatting
|
||||
needed for writing text documents for novels. These are currently limited to:
|
||||
novelWriter is _not_ a full-feature Markdown editor. It is a plain text editor that uses
|
||||
Markdown-like syntax for adding a minimal set of formatting that is useful for the specific task
|
||||
of writing novels. The formatting is currently limited to:
|
||||
|
||||
* Headings level 1 to 4 using the `#` syntax only.
|
||||
* Emphasised and strongly emphasised text. These are rendered as italicised and bold text.
|
||||
@@ -116,20 +66,19 @@ In addition, novelWriter adds the following, which is otherwise not supported by
|
||||
the comment is indexed and treated as the synopsis for the section of text under the same header.
|
||||
These synopsis comments can be used to build an outline and exported to external documents.
|
||||
* A set of meta data keyword/values starting with the character `@`. This is used for tagging
|
||||
and inter-linking documents, and can be used to generate a project outline.
|
||||
* Non-breaking spaces are supported as long as your system is using at least Qt 5.9. For earlier
|
||||
version, non-breaking spaces are converted to normal spaces when saving the document. This is
|
||||
done by the Qt library.
|
||||
* Thin spaces are also supported, as well as non-breaking thin spaces, with the same library
|
||||
version restriction as above.
|
||||
* Tabs can be used in the text, and should be properly aligned. The width of a tab in pixels can be
|
||||
changed in Preferences. Note that for the HTML format, most browsers will treat a tab as a space,
|
||||
so it may not show up like expected. If you import the HTML file to Libre Office, for instance,
|
||||
they should appear as expected.
|
||||
and inter-linking documents, and can also be included when generate a project outline.
|
||||
* A variety of thin and non-breaking spaces are supported. Some of them depend on the system
|
||||
running at least Qt 5.9.
|
||||
* Tabs can be used in the text, and should be properly aligned in both editor and viewer. This can
|
||||
be used to make simple tables and lists. Full Markdown tables and lists are not supported. Note
|
||||
that for HTML exports, most browsers will treat a tab as a space, so it may not show up like
|
||||
expected. If you import the HTML file to Libre Office, for instance, they should appear as
|
||||
expected.
|
||||
|
||||
The core export format of novelWriter is HTML5. You can also export the entire project as a single
|
||||
novelWriter Markdown-flavour document. In addition, other exports to Open Document, PDF, and plain
|
||||
text is offered through the Qt library, although with limitations to formatting.
|
||||
novelWriter Markdown-flavour document. These can be imported again into novelWriter. In addition,
|
||||
other exports to Open Document, PDF, and plain text is offered through the Qt library, although
|
||||
with limitations to formatting.
|
||||
|
||||
The HTML format is well suited for file conversion tools and import into other text editors.
|
||||
|
||||
@@ -137,20 +86,16 @@ The HTML format is well suited for file conversion tools and import into other t
|
||||
### Colour Themes
|
||||
|
||||
The editor has syntax highlighting for the features it supports, and includes a set of different
|
||||
syntax highlighting themes. The GUI also has an optional dark theme in addition to the default
|
||||
system theme.
|
||||
|
||||
New themes can easily be added to the `nw/assets/themes` folder. Have a look in the existing
|
||||
folders for examples of how to define the colours.
|
||||
syntax highlighting themes. Optional GUI themes are also available, including dark themes.
|
||||
|
||||
|
||||
### Easy Organising of Project Files
|
||||
|
||||
The structure of the project is shown on the left hand side of the main GUI. Project files are
|
||||
organised into root folders, indicating what class of file they are. The most important root folder
|
||||
is the Novel folder, which contains all of the files that makes up the finished novel. Each root
|
||||
folder can have subfolders. Folders have no impact on the final project structure, they are purely
|
||||
tools for organising the files in whatever way the user needs.
|
||||
is the `Novel` folder, which contains all of the files that make up the finished novel. Each root
|
||||
folder can have subfolders. Folders have no impact on the final project structure, they are there
|
||||
for you to organise your files in whatever way you need.
|
||||
|
||||
The editor supports four levels of headings, which determines what level the following text belongs
|
||||
to. Headings of level one signify a book or partition title. Headings of level two signify the
|
||||
@@ -177,7 +122,87 @@ are clickable in the document view pane, and control-clickable in the editor. Th
|
||||
to quickly navigate between the documents while editing.
|
||||
|
||||
|
||||
## Licenses
|
||||
# Installing and Running
|
||||
|
||||
For install instructions, please check the [documentation](https://novelwriter.readthedocs.io/) in
|
||||
the [Getting Started](https://novelwriter.readthedocs.io/en/latest/int_started.html) section.
|
||||
|
||||
|
||||
## TLDR Instructions
|
||||
|
||||
If you want to run novelWriter directly from the source code, you must run the `novelWriter.py`
|
||||
file from command line. For installations on Linux, macOS or Windows, see below.
|
||||
|
||||
**Note:** You may need to replace `python` with `python3` and `pip` with `pip3` in the instructions
|
||||
below on some systems. You may also want to add the `--user` flag for `pip` to install in your user
|
||||
space only.
|
||||
|
||||
|
||||
### Install from PyPi
|
||||
|
||||
novelWriter is available on [pypi.org](https://pypi.org/project/novelWriter/), and can be installed
|
||||
with:
|
||||
```bash
|
||||
pip install novelwriter
|
||||
```
|
||||
Dependencies should be installed automatically, but can also be installed directly with:
|
||||
```bash
|
||||
pip install pyqt5 lxml pyenchant
|
||||
```
|
||||
|
||||
When installing via pip, novelWriter can be launched from command line with:
|
||||
```bash
|
||||
novelWriter
|
||||
```
|
||||
|
||||
Make sure the install location for pip is in your PATH variable. This is not always the case by
|
||||
default.
|
||||
|
||||
|
||||
### Setup on Linux
|
||||
|
||||
If you're installing from source, the following commands will set up novelWriter on Linux:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
python setup.py install
|
||||
python setup.py xdg-install
|
||||
```
|
||||
|
||||
This should make novelWriter available as a regular application on your system, with a launceher
|
||||
icon and file association with novelWriter project files.
|
||||
|
||||
### Setup on macOS
|
||||
|
||||
If you're installing from source, the following commands will set up novelWriter on macOS:
|
||||
```bash
|
||||
brew install enchant
|
||||
pip3 install --user -r requirements.txt
|
||||
pip3 install --user pyobjc
|
||||
python setup.py install
|
||||
```
|
||||
|
||||
At present, novelWriter isn't further integrated into the OS, so you must launch it from command
|
||||
line with:
|
||||
```bash
|
||||
novelWriter
|
||||
```
|
||||
|
||||
|
||||
### Setup on Windows
|
||||
|
||||
For Windows, you can either install via PyPi, or use the Windows installer available from the
|
||||
[releases](https://github.com/vkbo/novelWriter/releases) page. This should add the necessary icons
|
||||
to your desktop and start menu.
|
||||
|
||||
|
||||
## Debugging
|
||||
|
||||
If you need to debug novelWriter, you must run it from command line. It takes a few parameters,
|
||||
which can be listed with the switch `--help`. The `--info`, `--debug` or `--verbose` flags are
|
||||
particularly useful for increasing logging output for debugging.
|
||||
|
||||
|
||||
# Licenses
|
||||
|
||||
This is Open Source software, and novelWriter is licensed under GPLv3. See the
|
||||
[GNU General Public License website](https://www.gnu.org/licenses/gpl-3.0.en.html) for more
|
||||
@@ -204,7 +229,7 @@ Bundled assets have the following licenses:
|
||||
[sdras/night-owl-vscode-theme](https://github.com/sdras/night-owl-vscode-theme).
|
||||
|
||||
|
||||
## Screenshot
|
||||
# Screenshot
|
||||
|
||||
**novelWriter with default system theme:**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user