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, which is
skipped for formatting purposes. 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
 * put the author last name, project title, and page number into the page header
   (e.g. "Corey / Leviathan Wakes / 99")


### Chapter excerpts

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 a "Heading" style.


## Page header

When constructing the page header, format-novel tries to determine the author
last name from the first line of the manuscript and the project title from the
filename. But if it gets those wrong, you can specify them on them on the
command-line. For example:

```bash
$ format-novel manuscript.docx --author Corey --title "Leviathan Wakes"
```


## Installation

Start by cloning the project with git. Then install it with [pipx](https://pypa.github.io/pipx/). Example:

```bash
pipx 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/
pipx install --editable .
```

### 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
pipx install 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">![Build Status](https://build.torsion.org/api/badges/witten/format-novel/status.svg?ref=refs/heads/master)</a>