X-Git-Url: https://mattmccutchen.net/superbchemistry/superbchemistry.git/blobdiff_plain/3b4a7e19b216d5010dec1d93b063d51d00666b94..2eec932f44a3bdc4d2f331a5e48c15dc8632bb31:/README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..38e420c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# SuperbChemistry
+
+This is an extension for [OpenOffice](https://www.openoffice.org/) and
+[LibreOffice](https://www.libreoffice.org/) that applies superscript and
+subscript formatting to chemical formulas in bulk in Writer documents.  See [the
+web page](https://mattmccutchen.net/superbchemistry/) for user documentation.
+
+The rest of this document refers to LibreOffice, but the same remarks apply to
+OpenOffice.
+
+## Development
+
+Run `make clean all` to generate `SuperbChemistry.oxt`, which you can install in
+LibreOffice via "Tools" -> "Extension Manager".
+
+By default, the library is installed read-only to prevent users from making
+changes that would be lost without warning if they uninstall the extension.  For
+development, you can change `library:readonly="true"` to
+`library:readonly="false"` in `extension/SuperbChemistry/*.xlb` so you can edit
+the library in LibreOffice.  Then you can copy the edited `Main.xba` from your
+profile (a typical location is
+`~/.config/libreoffice/4/user/uno_packages/cache/uno_packages/*.tmp_/SuperbChemistry.oxt/SuperbChemistry/Main.xba`,
+but this will depend on your operating system and application version) back to
+this working tree.
+
+`SuperbChemistry-test.odt` is a test suite that exercises most cases of the
+formatting rules.
+
+## Formatting rules
+
+- An _item_ is an element symbol (`[A-Z][a-z]?`) or text that starts or ends
+  with a group symbol `()[]{}` (depending on which side of the item we're
+  looking at).
+- A _charge symbol_ is `+`, `-` (U+002D hyphen-minus), or `−` (U+2212 minus
+  sign).
+- We recognize the following sequences:
+  - An item followed by one or more digits and one of the following: another
+    item, space or tab, closing group symbol `)]}`, sentence punctuation
+    `.,:;?!'"`, or end of line.
+  - An item followed by zero or more digits, a charge symbol, and any of the
+    things allowed in the previous case except for another item (to avoid
+    matching compound words like `A-B`).  This means we won't match something
+    like `Na+Cl-` , but formulas are rarely written that way.
+- A recognized charge symbol of `-` is replaced with `−`.
+- In a recognized sequence with no charge symbol, all of the digits are treated
+  as a quantity.
+- In a recognized sequence with a charge symbol, the last digit is treated as a
+  charge amount and the rest are treated as a quantity.  For example, in `Fe3+`,
+  the digit should be a charge amount.  Exception: if there is only one digit,
+  it is treated as a quantity in two cases:
+  - If the item is `H`, `O`, `F`, `Cl`, `Br`, or `I`, because these elements
+    often occur in quantities greater than 1 and rarely have a charge greater
+    than 1.
+  - If the item ends in a closing group symbol, because it probably wouldn't
+    have been enclosed in group symbols if its quantity were 1.
+
+## License
+
+I, Matt McCutchen, the sole author of SuperbChemistry, waive my copyright to it,
+placing it in the public domain.  SuperbChemistry comes with absolutely no
+warranty.