From d80eed02d8fa1be2020039ec922b835e164ea0ed Mon Sep 17 00:00:00 2001
From: Patrick Elmer <patrick@elmer.ws>
Date: Sat, 11 Mar 2023 13:05:59 +0900
Subject: [PATCH] Update readme

---
 README.md              | 132 ++++++++++++++++++++++++++++++++++++++++-
 soundchanger/change.py |   2 +-
 2 files changed, 131 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index f018368..1d5c83c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,131 @@
-# SoundChanger
+# Soundchanger
 
-Applies sound changes to words.
\ No newline at end of file
+A Python program to apply sound changes to words based on the notation used in historical linguistics.
+
+This program applies sound changes to a number of words. It can be used either as a python package, or as a command line tool.
+
+The command line tool `sc` can be used in the following way:
+
+```bash
+usage: sc [-h] [-C CATEGORIES] [-i] [-z ZERO_CHARACTERS] [-v] changes strings
+
+positional arguments:
+  changes               Sound change to be applied. Multiple sound changes should be separated by a space.
+  strings               Word that the sound change should be applied to. Multiple words should be separated by a space.
+
+options:
+  -h, --help            show this help message and exit
+  -C CATEGORIES, --categories CATEGORIES
+                        Categories to be used in the sound change.
+  -i, --ignore-errors   Categories to be used in the sound change.
+  -z ZERO_CHARACTERS, --zero-characters ZERO_CHARACTERS
+                        Characters that should be empty strings in the changed words.
+  -v, --version         show program's version number and exit
+```
+
+## Install
+
+Navigate to the directory containing the code for this project and execute the following command:
+
+```
+pip install .
+```
+
+After this, it should be callable from the command line using the `sc` command, or it can be imported in python projects in the following way:
+
+```python
+from soundchanger.project import apply
+```
+
+## Quick start
+
+```python
+from soundchanger.project import apply
+
+
+applied = apply(
+    changes = ['p>ɸ/#_', 'ɸ>h/_u'],
+    strings = ['pana', 'pune']
+)
+```
+
+The variable `applied` will have the following values:
+
+```python
+[
+    'ɸana',
+    'hune'
+]
+```
+
+## Usage
+
+```
+def apply(
+        changes,
+        strings,
+        categories={},
+        ignore_errors=True,
+        zero_characters='∅-'):
+``` 
+
+Applies a sound change or a list of sound changes to a string or
+a list of given strings.
+
+Accepts inputs of type str or list.
+If the input value is of type str, the output will also be of type str.
+
+**Options**
+
+- categories (default: {})
+    Which categories will be detected.
+    For vowels it would be {'V'='aeiou'} or {'V'=['a', 'e', 'i', 'o', 'u']})
+
+- ignore_errors (default: True)
+    If this option is set to `True`, any erroneous sound change will be skipped.
+    If set to `False`, a ValueError will be raised instead.
+
+- zero_characters (default: '∅-')
+    These characters will be removed in the changed words.
+    For example, `apply('h>∅', 'aha')` will return 'aa', not 'a∅a'.
+
+## Description
+
+The input needs to be in the format of sound changes as used in publications of historical linguistics.
+
+The general structure of a sound change is
+
+A > B / C _ D
+
+which can be read as "A changes to B in the environment after C and before D.
+
+A valid sound change must have at least az value for `A` and one `>` character. Thus, the sound change `a>` applied to the word `cat` would result in `ct`. The evironment (/C_D) is optional and can be used to specify environment-specific sound changes. Note that the hashtag symbol (`#`) is used for marking word boundaries (beginning and end of word). Thus, the sound change `p>f/#_` applies only at the beginning of a word. The word `papa` would change to `fapa`.
+
+The input also recognizes categories, which must be specified manually. Common categories invole for example consonants (`C`) and vowels (`V`). A sound change that happens between two vowel must therefore be written in the following way:
+
+```python
+from soundchanger.project import apply
+
+
+applied = apply(
+    changes = ['p>b/V_V'],
+    strings = ['paprepup'],
+    categories = {
+        'V': 'aeiou'
+    },
+)
+```
+
+This would create the output
+
+```python
+[
+    'paprebup'
+]
+```
+
+Categories can also be combined with other characters to form groups. These need to be written inside curly brackets (`{` and `}`) and separated by a comma (`,`) or vertical line (`|`).
+
+`apply(['a>o/{#,C}_'], ['aha', 'pana'], categories={'C': 'mnptkswlj'})` results in `['oha', 'pona']`
+
+Environments can also include several characters. `apply('o>u/cVc_nut#', 'coconut', categories={'V': 'aeiou'})` results in `'cocunut'`.
diff --git a/soundchanger/change.py b/soundchanger/change.py
index 6e5ed75..285dff0 100644
--- a/soundchanger/change.py
+++ b/soundchanger/change.py
@@ -27,7 +27,7 @@ def main():
     parser.add_argument(
         "-i", "--ignore-errors",
         action="store_false",
-        help="Categories to be used in the sound change."
+        help="Ignore sound changes that are not valied."
     )
     parser.add_argument(
         "-z", "--zero-characters",