added README

1 files changed, 112 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9911491
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+
+# ChordPro Charts
+
+In this repository you will find:
+- `chordpro` files in `./src/`
+- A global `JSON` file `./config.json`
+- Song-specific `JSON` files in `./configs/`
+- Helper scripts in `./scripts/`
+
+As a standard, all file names should be lowercase and use `'-'`s instead of `' '`s between words.
+
+# ChordPro format
+
+The `chordpro` files follow the ChordPro 6 format.
+See the [official website](https://www.chordpro.org/chordpro/index.html).
+
+# Helper Scripts
+
+## quick-sanitize.sh
+
+This is a `sh` script intended to be used on `chordpro` files retrieved from the "Worship Online" service.
+These files can be a good starting point for adding a song to this repository.
+However, their syntax and directives differ slightly from what the base `chordpro` command supports.
+
+This script will edit the given file in-place and make several changes.
+
+#### Notable Examples:
+
+- `{start_column}` and `{end_column}` directives don't exist and are thus removed by the script. Use `{column_break}` as needed.
+- Song sections use the syntax `{c:Verse}` or similar. These are replaced with the appropriate opening directive `{sov:Verse}` or similar.
+
+### Usage:
+
+```sh
+./scripts/quick-sanitize.sh ~/path-to/file.chordpro
+```
+
+#### *NOTE:*
+
+*You will **NEED** to manually check the file after the script has run to fix any syntax issues the script failed to catch.*
+*Here's some examples:*
+- *closing `{c}` directives need to be manually replaced with the appropriate ending-tag. Ex: `{eoc}` for end-of-chorus.*
+
+# Build Script
+
+`./scripts/build.sh` is a `zsh` script that can build one or all songs in a requested format.
+The script will automatically detect if a matching `configs/{song-name}.json` file exists and pass it to the `chordpro` executable to be mixed with/override the global `./config.json` file.
+Once complete, the output file(s) can be found at `./out/{song-title}.{format}`.
+
+For a list of all available output formats, see the official `chordpro` command [output documentation](https://www.chordpro.org/chordpro/using-chordpro/#output).
+
+#### *NOTE:*
+
+*If you use an unsupported output format, the resulting file will have your requested file extension (./out/song-title.gibberish), but will actually be a PDF internally.*
+
+## Usage:
+
+```sh
+./scripts/build.sh [song-title|all] [format]
+```
+
+## Build All Examples:
+
+### As PDF
+
+```sh
+./scripts/build.sh
+```
+or
+```sh
+./scripts/build.sh all pdf
+```
+
+### As HTML
+
+```sh
+./scripts/build.sh all html
+```
+
+### As ChordPro
+
+#### *Note:*
+
+```sh
+./scripts/build.sh all cho
+```
+
+*This will output a functional equivalent to the input `./src/{song-name}.chordpro` file with some changes, including:*
+- *removing comments*
+- *expanding variables (composers, tempo, etc)*
+- *transposing*
+
+*This can be useful if you want a copy of the chordpro file with the Nashville numbers instead of notes from the original key*
+
+## Build A Single Song as PDF
+
+#### *Note:*
+
+*Be sure to use the filename as it is found in the `./src/` directory without the file extension*
+
+```sh
+./scripts/build.sh is-he-worthy
+```
+or
+```sh
+./scripts/build.sh is-he-worthy pdf
+```
+
+## Build A Single Song as HTML
+```sh
+./scripts/build.sh is-he-worthy html
+```
\ No newline at end of file