0.2.4 (#41)

* remove about.py, version in pyproject.toml
* fixes/polish to docs

README.md

@@ -52,30 +52,31 @@ This returns something like:
 
 1. In the DrawBot menu, click **Python->Install Python Packages**:
 
-2. Enter `git+https://github.com/tallpauley/wordsiv` and click **Go!**:
+2. Enter ```git+https://github.com/tallpauley/wordsiv``` and click **Go!**
 
 ![Screenshot of DrawBot "Install Python Packages"
 Window](docs/images/drawbot-install.jpg)
 
-#### Notes on Updating WordSiv
+#### Updating WordSiv in DrawBot
 
 DrawBot caches Python packages/modules, so I'd recommend this process for
 updating to the latest version of WordSiv:
 
 1. In the DrawBot menu, click **Python->Install Python Packages**.
-2. Click the dropdown **Install / Upgrade** and select **Uninstall**.
-3. Enter `wordsiv` and click **Go!**.
+    - Click the dropdown **Install / Upgrade** and select **Uninstall**.
+    - Enter `wordsiv` and click **Go!**.
 4. Restart DrawBot.
-5. Follow the [above instructions](#installing-in-drawbot) to install WordSiv
-   again.
+5. Follow the [above instructions](#installing-in-drawbot) to install the latest
+   version of WordSiv.
+
 
 ### Installing Outside of DrawBot
 
 You can also install WordSiv on your system and use it in any Python script.
 You'll probably want to use a [virtual environment][venv] or a
 [Python tool][tool] that manages these for you, but I'll leave that up to you!
 
-First make sure you have Python 3.9+. Then:
+First, make sure you have Python 3.9+. Then:
 
 ```bash
 pip install git+https://github.com/tallpauley/wordsiv
@@ -85,20 +86,20 @@ pip install git+https://github.com/tallpauley/wordsiv
 
 Proofing text doesn't necessarily have to be syntactically correct or have
 meaning. It just needs the right amount of common and uncommon words to give it
-a "realistic" *shape*. Often type designers do this manually, such as in
+a "realistic" *shape*. Often, type designers do this manually, such as in
 Jonathan Hoefler's fantastic [proof][proof]:
 >Finally, I wanted the text to have the visual cadences of my native English, in
 >which words of variable but digestible length are punctuated by shorter ones.
 
 If we simply select words randomly, out of a hat which contains many more
-duplicates of say, "the" than "etymology", we'll get a string of words which
+duplicates of, say, "the" than "etymology", we'll get a string of words which
 visually resembles a sentence. This is how WordSiv works: sampling words from a
 *probability distribution* which is determined by the occurrence counts of words
 in a corpus of text.
 
-Of course, the more we restrict our glyph set the more we've tampered with the
-natural distribution of words, since most the longer, less-common words aren't
-available (which make up the long tail of the [Zipf's law][zipf]).
+Of course, the more we restrict our glyph set, the more we've tampered with the
+natural distribution of words, since most of the longer, less-common words
+aren't available (which make up the long tail of the [Zipf Distribution][zipf]).
 However, we can blend in a bit of randomness to make it look like real text at a
 glance!
 

docs/examples/hoefler-style-proof.md

@@ -1,8 +1,9 @@
 # Proof inspired by Jonathan Hoefler
 
 If you've been proofing typefaces, you've inevitably come across Jonathan
-Hoefler's highly-useful English proofs. Here is a version of it that dynamically
-adjusts to your glyph set (`MY_GLYPHS`).
+Hoefler's [highly-useful English
+proofs](https://jonathanhoefler.com/articles/how-to-proof-a-typeface). Here is a
+take on it that dynamically adjusts to your glyph set (`MY_GLYPHS`).
 
 ```python
 --8<-- "hflr-proof.py"

docs/index.md

@@ -72,7 +72,7 @@ You can also install WordSiv on your system and use it in any Python script.
 You'll probably want to use a [virtual environment][venv] or a
 [Python tool][tool] that manages these for you, but I'll leave that up to you!
 
-First make sure you have Python 3.9+. Then:
+First, make sure you have Python 3.9+. Then:
 
 ```bash
 pip install git+https://github.com/tallpauley/wordsiv
@@ -82,20 +82,20 @@ pip install git+https://github.com/tallpauley/wordsiv
 
 Proofing text doesn't necessarily have to be syntactically correct or have
 meaning. It just needs the right amount of common and uncommon words to give it
-a "realistic" *shape*. Often type designers do this manually, such as in
+a "realistic" *shape*. Often, type designers do this manually, such as in
 Jonathan Hoefler's fantastic [proof][proof]:
 >Finally, I wanted the text to have the visual cadences of my native English, in
 >which words of variable but digestible length are punctuated by shorter ones.
 
 If we simply select words randomly, out of a hat which contains many more
-duplicates of say, "the" than "etymology", we'll get a string of words which
+duplicates of, say, "the" than "etymology", we'll get a string of words which
 visually resembles a sentence. This is how WordSiv works: sampling words from a
 *probability distribution* which is determined by the occurrence counts of words
 in a corpus of text.
 
-Of course, the more we restrict our glyph set the more we've tampered with the
-natural distribution of words, since most the longer, less-common words aren't
-available (which make up the long tail of the [Zipf's law][zipf]).
+Of course, the more we restrict our glyph set, the more we've tampered with the
+natural distribution of words, since most of the longer, less-common words
+aren't available (which make up the long tail of the [Zipf Distribution][zipf]).
 However, we can blend in a bit of randomness to make it look like real text at a
 glance!
 

docs/release-notes.md

@@ -1,6 +1,20 @@
-## 0.2.3, 0.2.2, 0.2.1 – 2025-01-20
+## 0.2.4 – 2025-01-21
 
-Minor site/docs fixes
+### Fixed
+
+- Minor site/docs fixes
+
+### Removed
+
+- `wordsiv/about.py`: no need to have this, package version in pyproject.toml
+
+## 0.2.1, 0.2.2, 0.2.3 – 2025-01-20
+
+### Fixed
+
+- Minor site/docs fixes
+
+## 0.2.0 - 2025-01-20
 
 ### Added
 

docs/snippets/rnd-punc.py

@@ -0,0 +1,13 @@
+from wordsiv import WordSiv
+
+wsv = WordSiv(vocab="en")
+
+# Default behavior - based on punctuation probabilities
+print(wsv.sent(rnd_punc=0))
+
+# Completely random punctuation selection
+print(wsv.sent(rnd_punc=1))
+
+# Interpolation between totally random punc selection and probability-based punc
+# selection
+print(wsv.sent(rnd_punc=0.5))

docs/snippets/suppress-warnings.py

@@ -11,7 +11,6 @@
 print(wsv.top_word(contains="BLAH"))
 
 # We can suppress these warnings by setting the logging level to ERROR:
-log = logging.getLogger("wordsiv")
 log.setLevel(logging.ERROR)
 
 # No warning this time!

docs/usage/basic-usage.md

@@ -16,22 +16,24 @@ quickly jump into WordSiv, or read on for more detailed information.
 ## Listing Vocabs
 
 WordSiv generates text using [Vocabs](../../api-reference/#wordsiv.Vocab):
-objects that contain a word list (usually with counts) for a given language.
-WordSiv includes some Vocabs, and you can make your own (instructions coming
-soon!). See all available vocabs with: `list_vocabs()`:
+objects that contain a word list (usually with occurrence counts) for a given
+language. WordSiv includes some Vocabs, and you can make your own (instructions
+coming soon!). You can see all available Vocabs with: `list_vocabs()`:
 
 ```python
 --8<-- "list-vocabs.py"
 ```
 
 ## Selecting a Vocab
 
-You can set the default Vocab on `WordSiv` object initialization:
+You can set which Vocab you want to use on `WordSiv` object initialization,
+which will affect all text generation methods you call:
 ```python
 --8<-- "default-vocab.py"
 ```
 
-Or specify `vocab` when you are calling `word()`, `sent()`, etc.:
+Alternatively, you can specify `vocab` when you are calling `word()`, `sent()`,
+etc.:
 ```python
 --8<-- "vocab-arg.py"
 ```
@@ -44,12 +46,17 @@ Or specify `vocab` when you are calling `word()`, `sent()`, etc.:
 
 ## Restricting the Glyph Set
 
-You can set the default glyphs on `WordSiv` object initialization:
+The `glyphs` argument specifies a whitelist of glyphs that WordSiv will use to
+constrain text generation.
+
+You can set `glyphs` on `WordSiv` object initialization, which will affect all
+subsequent text generation methods you call:
 ```python
 --8<-- "set-glyphs.py"
 ```
 
-Or specify `glyphs` when you are calling `word()`, `sent()`, etc.:
+Alternatively, you can specify `glyphs` when you are calling `word()`, `sent()`,
+etc.:
 ```python
 --8<-- "glyphs-arg.py"
 ```

docs/usage/filtering-words.md

@@ -1,11 +1,17 @@
 # Filtering Words
 
-All WordSiv word/text generation functions allow for filtering of the words
-from the Vocab
+WordSiv provides options for filtering the words that are used
+to [generate text](../generating-text):
 
-We demonstrate these arguments with `top_words()` for ease of understanding.
-These arguments are applicable to `word()`, `words()`, `top_word()`,
-`top_words()`, `sent()`, `sents()`, `para()`, `paras()`.
+- **Letter Case: [`case`](#filter-words-by-letter-case)**
+- **Word Length: [`wl`](#filter-words-by-word-length), [`min_wl`](#filter-words-by-word-length), [`max_wl`](#filter-words-by-word-length)**
+- **Substrings: [`startswith`](#word-starts-with-string-startswith), [`endswith`](#word-ends-with-string-endswith), [`contains`](#word-contains-strings-contains), [`inner`](#word-contains-inner-strings-inner)**
+- **Regular Expressions: [`regexp`](#filter-words-by-regex)**
+
+We demonstrate these arguments with `top_words()` so you can see what's
+happening without randomization. You can use these arguments for `word()`,
+`words()`, `top_word()`, `top_words()`, `sent()`, `sents()`, `para()`,
+`paras()`, `text()`.
 
 
 ## Filter Words by Letter Case
@@ -50,11 +56,11 @@ from the vocab.
 
 The `lc` option selects lowercase words from the Vocab (e.g. `"bread"`). It will
 *not* try to lowercase any words with capitals, since we wouldn't want to
-lowercase words like "Paris", "FAA" or "DDoS"
+lowercase words like `"Paris"`, `"FAA"`, or `"DDoS"`
 
 !!! Note "Why no `lc_og`?"
-    There is no need for a `lc_og` option, because `lc` only selects lowercase
-    words from the Vocab.
+    There is no need for a `lc_og` option, because `lc` **already** only selects
+    lowercase words from the Vocab.
 ```python
 --8<-- "case-lc.py"
 ```
@@ -109,11 +115,10 @@ vocab, transforming them to all caps (e.g. `"WWF", "BOAT", "PARIS"`).
 
 ### All Caps, No Case Change (`case='uc_og'`)
 
-The `cap_og` option selects all caps words from the Vocab (e.g. `"WWF"`). It
+The `uc_og` option selects all caps words from the Vocab (e.g. `"WWF"`). It
 does **not** capitalize any lowercase or capitalized words (like `case='uc'`
 does). This is useful for getting all caps words like acronyms.
 
-
 ```python
 --8<-- "case-uc-og.py"
 ```
@@ -138,32 +143,38 @@ the Vocab:
 
 ## Filter Words by Substrings
 
-Arguments `startswith`, `endswith`, `contains`, and `inner` let you select by
-words which contain specific substrings.
+Arguments **[`startswith`](#word-starts-with-string-startswith)**, **[`endswith`](#word-ends-with-string-endswith)**, **[`contains`](#word-contains-strings-contains)**, and **[`inner`](#word-contains-inner-strings-inner)** let you select words which contain specific substrings.
 
 ### Word Starts With String (`startswith`)
+
+Argument `startswith` matches words that have a specific glyph/string at the
+start of the word, *after* any case transformations may have occurred.
+
 ```python
 --8<-- "startswith.py"
 ```
 
 ### Word Ends With String (`endswith`)
 
+Argument `endswith` matches words that have a specific glyph/string at the
+end of the word, *after* any case transformations may have occurred.
+
 ```python
 --8<-- "endswith.py"
 ```
 
 ### Word Contains String(s) (`contains`)
-The `contains` argument looks for string(s) in the word, *after* any case
-transformations may have occurred.
+
+Argument `contains` matches words which contain specific string(s) in the word,
+*after* any case transformations may have occurred.
 
 ```python
 --8<-- "contains.py"
 ```
 
 ### Word Contains Inner String(s) (`inner`)
-The `inner` argument looks for string(s) in all characters of the word except
-for the first and last characters `word[1:-1]`, *after* any case
-transformations may have occurred.
+Argument `inner` matches words which contain specific string(s) in `word[1:-1]` (all
+but first and last glyphs), *after* any case transformations may have occurred.
 
 ```python
 --8<-- "inner.py"
@@ -197,10 +208,9 @@ the given filters. However, you can turn this off by adjusting the log level:
 
 ### Raising Errors
 
-Maybe you want your script to halt if there are no matching words, or
-want to catch the error and try something else. For this you can use the
-`raise_errors` option, which will raise `wordsiv.FilterError` exception if the
-filters return no word matches.
+Maybe you want your script to halt if there are no matching words, or want to
+catch the error and try something else. For this you can use the `raise_errors`
+option, which will raise `wordsiv.FilterError` if there are no word matches.
 
 ```python
 --8<-- "raise-errors.py"