better readme

README.md

@@ -1,3 +1,59 @@
-# rubymark
+MMMD (Mark My Message Down)
+============
+
+(Originally titled Rubymark)
 
 Modular, compliant Markdown parser in Ruby
+
+Installation
+------------
+
+This package is available as a gem over at
+[rubygems.org](https://rubygems.org/gems/mmmd).
+
+Installing it is as simple as executing `gem install mmmd`
+
+Usage
+-----
+
+This package is generally intended as a library, but it also
+includes a CLI tool which permits the usage of the library
+for simple document translation tasks.
+
+Examples:
+```sh
+# Render the file in a terminal-oriented format
+$ mmmdpp file.md -
+
+# Read the markdown contents directly from input, output to stdout
+$ external-program | mmmdpp - -
+
+# Render file.md to a complete webpage
+$ mmmdpp -r HTML file.md file.html
+
+# Render file.md into a complete webpage and add extra tags to head and
+# wrap all images with a figure tag with figcaption containing image title
+$ mmmdpp -r HTML -o '"head": ["<meta charset=\"UTF-8\">", "<style>img { max-width: 90%; }</style>"]' -o '"mapping"."PointBlank::DOM::InlineImage".figcaption: true' - -
+
+# Render file.md into a set of HTML tags, without anything extra
+$ mmmdpp -r HTML -o '"nowrap": true' file.md file.html
+```
+
+A lot more usage options are documented on the Wiki page for the project
+
+License
+-------
+
+    Copyright 2025 yessiest@text.512mb.org
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.