154 lines
4.4 KiB
Markdown
154 lines
4.4 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, 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"></a>
|