Updated the README

This commit is contained in:
Dmytro Yeroshkin 2021-10-22 19:22:38 +02:00
parent 9266c54664
commit 44426edb78
1 changed files with 83 additions and 17 deletions

100
README.md
View File

@ -1,6 +1,6 @@
novel-stats produces word count statistics for novels written in Markdown
format, including total word count, per-chapter word counts, per-act word
counts, and counts by chapter "status." You might find this useful if you're
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.
@ -9,21 +9,27 @@ 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:
Example output with no optional data:
```bash
$ novel-stats example.md
chapter 1: 103 words (drafted)
chapter 2: 83 words (dev edited)
chapter 3: 115 words
chapter 4: 96 words
chapter 5: 136 words (drafted)
drafted: 237 words (~43%)
dev edited: 82 words (~15%)
total: 539 words
```
act 1: 187 words (~34%)
act 2: 212 words (~39%)
act 3: 137 words (~25%)
drafted: 239 words (~44%)
dev edited: 83 words (~15%)
Example output with chapter data:
```bash
$ novel-stats example.md -c
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
```
@ -43,6 +49,25 @@ easier):
pip3 install --editable /path/to/novel-stats
```
```bash
novel-stats multi_file.mdpp -pp -c -a
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
```
## Usage
@ -50,9 +75,18 @@ novel-stats takes a single argument: The path to your novel file in markdown
format. For instance:
```bash
novel-stats /path/to/your/novel.md
novel-stats /path/to/your/novel.md[pp] [-c/--chapter] [-a/--act] [-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
@ -126,11 +160,43 @@ 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 an example Markdown file `example.md` that illustrates
the expected Markdown format. Try it out:
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
```
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
```