Add README.

This commit is contained in:
Dan Helfman 2021-09-11 17:07:31 -07:00
parent 07731e781a
commit a94d212abc
2 changed files with 124 additions and 1 deletions

123
README.md Normal file
View File

@ -0,0 +1,123 @@
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." It's 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:
```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)
act 1: 187 words
act 2: 212 words
act 3: 137 words
drafted: 239 words
dev edited: 83 words
total: 539 words
```
## Installation
Start by cloning the project with git. Then install it with Python's pip.
Example
```bash
pip3 install /path/to/novel-stats
```
Or, if you'd like to install it "editable" (making development/updates
easier):
```bash
pip3 install --editable /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 /path/to/your/novel.md
```
## 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.
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. Example:
```yaml
## 3
[status]: # (drafted)
```
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. 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).
### Example novel
novel-stats includes an example Markdown file `example.md` that illustrates
the expected Markdown format. Try it out:
```
novel-stats example.md
```

View File

@ -6,7 +6,7 @@ VERSION = '0.1.0'
setup(
name='novel-stats',
version=VERSION,
description='Produce word count statistics for a novel written in Markdown format.',
description='Produce word count statistics for novels written in Markdown format.',
author='Dan Helfman',
author_email='witten@torsion.org',
url='https://projects.torsion.org/witten/novel-stats',