156 lines
4.5 KiB
Markdown
156 lines
4.5 KiB
Markdown
format-novel formats an existing Word novel document in a standard style for
|
|
sharing and submission. You might find this useful if you're producing your
|
|
novel document programmatically with another tool like
|
|
[ebook-convert](https://manual.calibre-ebook.com/generated/en/ebook-convert.html)
|
|
and want to add automatic formatting to your your writing workflow.
|
|
|
|
Example usage:
|
|
|
|
```bash
|
|
$ format-novel manuscript.docx
|
|
```
|
|
|
|
This assumes the document already contains a single title page. It applies the
|
|
following formatting, modifying the file in-place:
|
|
|
|
* apply double spacing
|
|
* indent the first line of each paragraph (0.5 inches) except for the initial
|
|
paragraph in a chapter or section
|
|
* remove vertical spacing between paragraphs
|
|
* set a default font of Times New Roman
|
|
* enable page numbering starting on the second page (upper right) or the first page if filtering by chapter
|
|
|
|
|
|
### Chapter excerpting
|
|
|
|
You can optionally filter the output to only include certain chapters by
|
|
number. For instance:
|
|
|
|
```bash
|
|
$ format-novel manuscript.docx --chapters 5 6 7
|
|
```
|
|
|
|
This will only include chapters 5, 6, and 7 in the output file, excluding all
|
|
other chapters. For this to work, the input document must indicate chapter
|
|
titles with the "Heading 2" style.
|
|
|
|
|
|
## Planned features
|
|
|
|
* Support for specifying author and project title to show up in the header
|
|
alongside page number.
|
|
|
|
|
|
## Installation
|
|
|
|
Start by cloning the project with git. Then install it with Python's `pip`.
|
|
Example:
|
|
|
|
```bash
|
|
pip3 install /path/to/format-novel
|
|
```
|
|
|
|
## Usage
|
|
|
|
format-novel takes a single argument: The path to your novel file in Word .docx
|
|
format. For instance:
|
|
|
|
```bash
|
|
format-novel /path/to/your/novel.docx
|
|
```
|
|
|
|
## Contributing
|
|
|
|
format-novel is licensed under the GNU General Public License version 3 or any
|
|
later version.
|
|
|
|
If you'd like to contribute to development, please feel free to submit a [Pull
|
|
Request](https://projects.torsion.org/witten/format-novel/pulls) or open an
|
|
[issue](https://projects.torsion.org/witten/format-novel/issues) first to
|
|
discuss your idea.
|
|
|
|
### Source code
|
|
|
|
To get set up to hack on format-novel, first clone master via HTTPS or SSH:
|
|
|
|
```bash
|
|
git clone https://projects.torsion.org/witten/format-novel.git
|
|
```
|
|
|
|
Or:
|
|
|
|
```bash
|
|
git clone ssh://git@projects.torsion.org:3022/witten/format-novel.git
|
|
```
|
|
|
|
Then, install format-novel
|
|
"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
|
|
so that you can run format-novel commands while you're hacking on them to
|
|
make sure your changes work.
|
|
|
|
```bash
|
|
cd format-novel/
|
|
pip3 install --editable --user .
|
|
```
|
|
|
|
Note that this will typically install the format-novel commands into
|
|
`~/.local/bin`, which may or may not be on your PATH. There are other ways to
|
|
install format-novel editable as well, for instance into the system Python
|
|
install (so without `--user`, as root), or even into a
|
|
[virtualenv](https://virtualenv.pypa.io/en/stable/). How or where you install
|
|
format-novel is up to you, but generally an editable install makes development
|
|
and testing easier.
|
|
|
|
|
|
### Automated tests
|
|
|
|
Assuming you've cloned the format-novel source code as described above, and
|
|
you're in the `format-novel/` working copy, install tox, which is used for
|
|
setting up testing environments:
|
|
|
|
```bash
|
|
pip3 install --user tox
|
|
```
|
|
|
|
Finally, to actually run tests, run:
|
|
|
|
```bash
|
|
cd format-novel
|
|
tox
|
|
```
|
|
|
|
### Code formatting
|
|
|
|
format-novel code uses the [Black](https://black.readthedocs.io/en/stable/) code
|
|
formatter, the [Flake8](http://flake8.pycqa.org/en/latest/) code checker, and
|
|
the [isort](https://github.com/timothycrosley/isort) import orderer, so
|
|
certain code style requirements will be enforced when running automated tests.
|
|
See the Black, Flake8, and isort documentation for more information.
|
|
|
|
If when running tests, you get an error from the
|
|
[Black](https://black.readthedocs.io/en/stable/) code formatter about files
|
|
that would be reformatted, you can ask Black to format them for you via the
|
|
following:
|
|
|
|
```bash
|
|
tox -e black
|
|
```
|
|
|
|
And if you get a complaint from the
|
|
[isort](https://github.com/timothycrosley/isort) Python import orderer, you
|
|
can ask isort to order your imports for you:
|
|
|
|
```bash
|
|
tox -e isort
|
|
```
|
|
|
|
|
|
### Continuous integration
|
|
|
|
Each pull request triggers a continuous integration build which runs the test
|
|
suite. You can view these builds on
|
|
[build.torsion.org](https://build.torsion.org/witten/format-novel), and they're
|
|
also linked from the commits list on each pull request.
|
|
|
|
<a href="https://build.torsion.org/witten/format-novel" alt="build status"></a>
|