284 lines
7.0 KiB
Markdown
284 lines
7.0 KiB
Markdown
novel-stats produces word count statistics for novels written in Markdown
|
|
format, including total word count, word count by status, and optionally
|
|
per-chapter and per-act word counts. You might find this useful if you're
|
|
already using tools like Git and Markdown processing as part of your writing
|
|
workflow (or are looking to start) and want some basic statistics about your
|
|
novel as you're writing it.
|
|
|
|
novel-stats is fairly particular about the format of the novel and doesn't
|
|
currently include much in the way of error checking. Word counts may not be
|
|
exact.
|
|
|
|
Example output without any flags:
|
|
|
|
```bash
|
|
$ novel-stats example.md
|
|
drafted: 237 words (~43%)
|
|
dev edited: 82 words (~15%)
|
|
total: 539 words
|
|
```
|
|
|
|
Example output with chapter data:
|
|
|
|
```bash
|
|
$ novel-stats -c example.md
|
|
chapter 1: 103 (drafted)
|
|
chapter 2: 83 (dev edited)
|
|
chapter 3: 115
|
|
chapter 4: 96
|
|
chapter 5: 136 (drafted)
|
|
|
|
drafted: 237 words (~43%)
|
|
dev edited: 82 words (~15%)
|
|
total: 539 words
|
|
```
|
|
|
|
Example with multi-file markdown:
|
|
|
|
```bash
|
|
$ novel-stats -pp -c -a multi_file.mdpp
|
|
chapter 1 Lorem:
|
|
203 (drafted)
|
|
303 (dev edited)
|
|
506 words (total)
|
|
chapter 2 Ipsum: 84 (dev edited)
|
|
chapter 3 Dolor: 116
|
|
chapter 4 Sit: 97
|
|
chapter 5 Amet: 137 (drafted)
|
|
|
|
act 1: 591 words (~62%)
|
|
act 2: 214 words (~22%)
|
|
act 3: 138 words (~14%)
|
|
|
|
drafted: 336 words (~35%)
|
|
dev edited: 385 words (~40%)
|
|
total: 946 words
|
|
```
|
|
|
|
## Installation
|
|
|
|
Start by cloning the project with git. Then install it with
|
|
[pipx](https://pypa.github.io/pipx/). Example:
|
|
|
|
```bash
|
|
pipx install /path/to/novel-stats
|
|
```
|
|
|
|
## Usage
|
|
|
|
novel-stats takes a single argument: The path to your novel file in markdown
|
|
format. For instance:
|
|
|
|
```bash
|
|
novel-stats [-c/--chapter] [-a/--act] [-pp] /path/to/your/novel.md[pp]
|
|
```
|
|
|
|
### Optional flags
|
|
|
|
* `-c` or `--chapter` — output chapter-by-chapter breakdown of word counts,
|
|
including how many words in each chapter are tagged with which status
|
|
* `-a` or `--act` — output act-by-act breakdown of word counts (total only)
|
|
* `-pp` — run markdown pre-processor, this allows for a multi-file input
|
|
(e.g. each chapter in its own file), but requires the MarkdownPP python
|
|
library.
|
|
|
|
## Markdown format
|
|
|
|
You'll need to format your novel in the expected format for novel-stats to
|
|
work.
|
|
|
|
### Title and author
|
|
|
|
Use `#` for the title and `###` for author name. Example:
|
|
|
|
```yaml
|
|
# Title of the Novel
|
|
### Author Name
|
|
```
|
|
|
|
These lines are generally ignored, although they do show up in the total word
|
|
count.
|
|
|
|
### Chapters
|
|
|
|
novel-stats expects chapters to start with `##` and to have a numeric title
|
|
(no "Chapter", etc.). Example:
|
|
|
|
```yaml
|
|
## 1
|
|
|
|
Once upon a time ...
|
|
```
|
|
|
|
### Chapter status
|
|
|
|
Chapter "status" is an optional feature that lets you indicate certain
|
|
chapters as "drafted", "dev edited", etc. and then get word count totals for
|
|
each status. This is useful for tracking the progress of your novel
|
|
chapter-by-chapter as you write or revise.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
## 3
|
|
|
|
[status]: # (drafted)
|
|
```
|
|
|
|
Other Markdown processing tools should ignore these "comments", so they
|
|
shouldn't show up in the processed contents of your novel. If you do use this
|
|
feature, you should set the status at the top of each chapter, before the
|
|
actual chapter contents.
|
|
|
|
There are no set values for the chapter status. Use the statuses that make
|
|
sense for your writing workflow.
|
|
|
|
|
|
### Acts
|
|
|
|
Acts are an optional feature that let you indicate certain chapters as part of
|
|
a particular act number and then get word count totals for each act. This is
|
|
useful for keeping an eye on how big your acts are in relation to one another.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
## 8
|
|
|
|
[act]: # (2)
|
|
```
|
|
|
|
You only need to set the act for the *first* chapter in the act. Subsequent
|
|
chapters are assumed to be in the same act unless otherwise indicated.
|
|
|
|
If you do use this feature, you should set the status at the top of each
|
|
chapter, before the actual chapter contents (and after any chapter status).
|
|
|
|
|
|
### Comments
|
|
|
|
Comments, such as outlining notes for yourself, can be added anywhere using:
|
|
|
|
```yaml
|
|
[//]: # This text is completely ignored.
|
|
```
|
|
|
|
These words will not count towards the word count
|
|
|
|
|
|
### Multi-file support
|
|
|
|
Splitting your novel into multiple files is supported using the `MarkdownPP`
|
|
python library. To include a secondary file inside the main one, simply use
|
|
|
|
```yaml
|
|
!INCLUDE "OtherFile.md"
|
|
```
|
|
|
|
and add the `-pp` flag to novel-stats.
|
|
|
|
### Example novel
|
|
|
|
novel-stats includes two examples:
|
|
|
|
1. Markdown file `example.md` that illustrates the expected Markdown format
|
|
for a single file. Try it out:
|
|
|
|
```bash
|
|
$ novel-stats example.md
|
|
```
|
|
|
|
2. A 6 file example in the `example` folder with the main file
|
|
`multi_file.mdpp`. You can try this one out with
|
|
|
|
```bash
|
|
$ cd example
|
|
$ novel-stats multi_file.mdpp -pp
|
|
```
|
|
|
|
## Contributing
|
|
|
|
novel-stats 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/novel-stats/pulls) or open an
|
|
[issue](https://projects.torsion.org/witten/novel-stats/issues) first to
|
|
discuss your idea.
|
|
|
|
### Source code
|
|
|
|
To get set up to hack on novel-stats, first clone master via HTTPS or SSH:
|
|
|
|
```bash
|
|
git clone https://projects.torsion.org/witten/novel-stats.git
|
|
```
|
|
|
|
Or:
|
|
|
|
```bash
|
|
git clone ssh://git@projects.torsion.org:3022/witten/novel-stats.git
|
|
```
|
|
|
|
Then, install novel-stats
|
|
"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
|
|
so that you can run novel-stats commands while you're hacking on them to
|
|
make sure your changes work.
|
|
|
|
```bash
|
|
cd novel-stats/
|
|
pipx install --editable .
|
|
```
|
|
|
|
|
|
### Automated tests
|
|
|
|
Assuming you've cloned the novel-stats source code as described above, and
|
|
you're in the `novel-stats/` working copy, install tox, which is used for
|
|
setting up testing environments:
|
|
|
|
```bash
|
|
pipx install tox
|
|
```
|
|
|
|
Finally, to actually run tests, run:
|
|
|
|
```bash
|
|
cd novel-stats
|
|
tox
|
|
```
|
|
|
|
### Code formatting
|
|
|
|
novel-stats 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/novel-stats), and they're
|
|
also linked from the commits list on each pull request.
|
|
|
|
<a href="https://build.torsion.org/witten/novel-stats" alt="build status"></a>
|