better docs for the same fair to middling thinger

README.md

@@ -1,58 +1,65 @@
-
 # KAMADHENU
 
-An udderly absurd soothsayer for your shell.
+An udderly absurd MOTD soothsayer for your *nix `$SHELL`
 
 ![Vaporware](./img/kama-ghost.png)
+![TOC]
 
-## Installation
+## Install
 
-``` sh
+``` shell
 curl -fsSL https://raw.githubusercontent.com/krry/Kamadhenu/main/bootstrap.sh | bash
 ```
 
 Then follow the bouncing bytes...
 
-## Usage
-
 Fresh out of the box,\
 you get a bare minimum of\
-**`275,254,848` squirts of insight**\
+**`275,254,848` spurts of insight**\
 delivered one. at. a. time.
 
-All you have to do is ask:
+## Use
 
-``` sh
-kamadhenu
+All you have to do is call her name.
+
+``` shell
+Kamadhenu
 ```
 
 Who dares put words in the mouth of Kamadhenu?
 
-``` sh
+``` shell
 Kamadhenu Do you love me?
-```
-
-``` sh
+echo ' '
 Kamadhenu Could you learn to love me?
 ```
 
-Kamadhenu can't help you, but you can still ask.
-``` sh
+Kamadhenu may not help, but you can still ask.
+
+``` shell
 Kamadhenu help
 ```
 
-### Oh, dear, is it Terminal?
-Start each shell sesh fresh with Kamadhenu.
+Pick a number between 1 and `Ctrl-C`
+
+``` shell
+Kamadhenu 2021
+```
 
-``` sh
+Start each shell sesh fresh with Kamadhenu
+
+``` shell
 echo Kamadhenu >> .$(basename $SHELL)rc
 ```
 
-#### Coming soon
+Oh, dear, is it Terminal?
+
+### Coming soon (maybe)
+
 Pipe `stdout` to Kamadhenu (like a cat)
 
-``` sh
-# You ever drunk Bailey's out of a shoe? | Kamadhenu
+``` shell
+# echo "You ever drunk Bailey's out of a shoe?" | Kamadhenu
 ```
 
 ## Dependencies
@@ -67,51 +74,37 @@ Pipe `stdout` to Kamadhenu (like a cat)
 
 If you encounter a hiccup, hold your breath. Anything else, check here.
 
-#### No Homebrew, dog? That's otay.
+### No Homebrew, dog? That's otay
 
 The dependencies are listed in the `Brewfile` and right nearby.
-If you gather those, you're most of the way there.
-All that's left is to copy those artisanally curated, hand-fingered
-cows, fonts, and fortunes into their respective homes on your machine.
+If you gather those, you're most of the way there. All that's left is to copy those artisanally curated, hand-fingered cows, fonts, and fortunes into their respective homes on your machine.
 
-#### Flubbed with the dismount? Failed to symlink?
+### Flubbed with the dismount? Failed to symlink?
 
-The likely culprits are file permissions. Make sure you launch the
-bootstrap script from the safety of a locally owned, openly permissioned dir.
+The likely culprits are file permissions. Make sure you launch the bootstrap script from the safety of a locally owned, openly permissioned dir.
 
-If nothing happens when you fire `Kamadhenu` into the command line,
-the symlink probably didn't make it into your `PATH`. Nobody knows
-your `PATH` like you do, so give it an `echo $PATH` and find your way.
+If nothing happens when you fire `Kamadhenu` into the command line, the symlink probably didn't make it into your `PATH`. Nobody knows your `PATH` like you do, so give it an `echo $PATH` and find your way.
 
 #### Missing cows and/or figlets? Fortunes failing?
 
-These need to be where `cowsay`, `figlet`, and `fortune` would look for them.
-Once again, you have a keen advantage in determining this.
+These need to be where `cowsay`, `figlet`, and `fortune` would look for them. Once again, you have a keen advantage in determining this.
 
-On my crusty ol' MacBook, they sticks 'em thusly:
-* cows go in: `/usr/local/share/cows`
-* figlets in: `/usr/local/share/figlet/fonts`
-* fortunes => `/usr/local/share/games/fortunes`
+First determine your `brew --prefix`.
 
-If you especially enjoy Kamadhenu, fork away, or come and play!
-I began this project because I didn't know jack about shell scripting.
+On Macs with Intel chips we tend to use `/usr/local`, and for the Apple Silicon we tend to use `/opt/homebrew`.
 
-Now that it's alive, it'd be fun to glitter the flock out of it.
-Who doesn't need yet another MOTD, amirite?
+- cows go in: `/usr/local/share/cows`
+- figlets in: `/usr/local/share/figlet/fonts`
+- fortunes => `/usr/local/share/games/fortunes`
+
+## Many Gratitudes
+
+If you especially enjoy Kamadhenu, fork away, or come and play!
 
-## TODO (maybe)
+I began this project because I didn't know jack about shell scripting. And I still don't!
 
-- [ ] getopts for:
-  - cow face settings
-  - choose default cow
-  - choose default font
-  - monochrome mode - no lolcat
-  - no cowsay mode
-  - no fortune mode
-  - supersize mode
-- [ ] moar easter eggs and batty interwoven CLI tomfoolery
-- colorschemes!
-- a Linux bootstrap script
+Now that it's alive, it might be fun to glitter the flock out of it.
 
+And who doesn't need yet another MOTD, amirite?
 
-![Suckle at the teat of wisdom](./img/Kamadhenu.jpg)
+![Zuckle at the zipple of wisdom](./img/Kamadhenu.jpg)

docs/TODO.md

@@ -0,0 +1,16 @@
+# TODO
+
+(maybe someday)
+
+- [ ] getopts for:
+  - [ ] cow face settings
+  - [ ] choose default cow
+  - [ ] choose default font
+  - [ ] monochrome mode - no lolcat
+  - [ ] no cowsay mode
+  - [ ] no fortune mode
+  - [ ] supersize mode
+- [ ] moar easter eggs
+- [ ] batty interwoven CLI tomfoolery
+- [ ] colorschemes!
+- [ ] a Linux bootstrap script

docs/index.md

@@ -1,37 +1,30 @@
-## Welcome to GitHub Pages
+# KAMADHENU
 
-You can use the [editor on GitHub](https://github.com/krry/Kamadhenu/edit/master/docs/index.md) to maintain and preview the content for your website in Markdown files.
+A soothsaying [MOTD](https://www.wikiwand.com/en/Motd_(Unix)) goddess for your *nix `$SHELL`.
 
-Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files.
+## To install
 
-### Markdown
-
-Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for
-
-```markdown
-Syntax highlighted code block
+``` shell
+cd where_you_like_to_keep_teh_codez
+curl -fsSL https://raw.githubusercontent.com/krry/Kamadhenu/main/bootstrap.sh | bash
+```
 
-# Header 1
-## Header 2
-### Header 3
+## To use
 
-- Bulleted
-- List
+``` shell
+# Consult Kamadhenu
+Kamadhenu
 
-1. Numbered
-2. List
+# Get help
+Kamadhenu -h
+# or
+Kamadhenu help
 
-**Bold** and _Italic_ and `Code` text
+# Put words in Kama's mouth
+Kamadhenu <words>
 
-[Link](url) and ![Image](src)
+# Request a number of messages
+Kamadhenu <count>
 ```
 
-For more details see [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/).
-
-### Jekyll Themes
-
-Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/krry/Kamadhenu/settings). The name of this theme is saved in the Jekyll `_config.yml` configuration file.
-
-### Support or Contact
-
-Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://support.github.com/contact) and we’ll help you sort it out.
+Thanks for playing.