| 1 | # SuperbChemistry |
| 2 | |
| 3 | This is an extension for [OpenOffice](https://www.openoffice.org/) and |
| 4 | [LibreOffice](https://www.libreoffice.org/) that applies superscript and |
| 5 | subscript formatting to chemical formulas in bulk in Writer documents. See [the |
| 6 | web page](https://mattmccutchen.net/superbchemistry/) for user documentation. |
| 7 | |
| 8 | The rest of this document refers to LibreOffice, but the same remarks apply to |
| 9 | OpenOffice. |
| 10 | |
| 11 | ## Development |
| 12 | |
| 13 | Run `make clean all` to generate `SuperbChemistry.oxt`, which you can install in |
| 14 | LibreOffice via "Tools" -> "Extension Manager". |
| 15 | |
| 16 | By default, the library is installed read-only to prevent users from making |
| 17 | changes that would be lost without warning if they uninstall the extension. For |
| 18 | development, you can change `library:readonly="true"` to |
| 19 | `library:readonly="false"` in `extension/SuperbChemistry/*.xlb` so you can edit |
| 20 | the library in LibreOffice. Then you can copy the edited `Main.xba` from your |
| 21 | profile (a typical location is |
| 22 | `~/.config/libreoffice/4/user/uno_packages/cache/uno_packages/*.tmp_/SuperbChemistry.oxt/SuperbChemistry/Main.xba`, |
| 23 | but this will depend on your operating system and application version) back to |
| 24 | this working tree. |
| 25 | |
| 26 | `SuperbChemistry-test.odt` is a test suite that exercises most cases of the |
| 27 | formatting rules. |
| 28 | |
| 29 | ## Formatting rules |
| 30 | |
| 31 | - An _item_ is an element symbol (`[A-Z][a-z]?`) or text that starts or ends |
| 32 | with a group symbol `()[]{}` (depending on which side of the item we're |
| 33 | looking at). |
| 34 | - A _charge symbol_ is `+`, `-` (U+002D hyphen-minus), or `−` (U+2212 minus |
| 35 | sign). |
| 36 | - We recognize the following sequences: |
| 37 | - An item followed by one or more digits and one of the following: another |
| 38 | item, space or tab, closing group symbol `)]}`, sentence punctuation |
| 39 | `.,:;?!'"`, or end of line. |
| 40 | - An item followed by zero or more digits, a charge symbol, and any of the |
| 41 | things allowed in the previous case except for another item (to avoid |
| 42 | matching compound words like `A-B`). This means we won't match something |
| 43 | like `Na+Cl-` , but formulas are rarely written that way. |
| 44 | - A recognized charge symbol of `-` is replaced with `−`. |
| 45 | - In a recognized sequence with no charge symbol, all of the digits are treated |
| 46 | as a quantity. |
| 47 | - In a recognized sequence with a charge symbol, the last digit is treated as a |
| 48 | charge amount and the rest are treated as a quantity. For example, in `Fe3+`, |
| 49 | the digit should be a charge amount. Exception: if there is only one digit, |
| 50 | it is treated as a quantity in two cases: |
| 51 | - If the item is `H`, `O`, `F`, `Cl`, `Br`, or `I`, because these elements |
| 52 | often occur in quantities greater than 1 and rarely have a charge greater |
| 53 | than 1. |
| 54 | - If the item ends in a closing group symbol, because it probably wouldn't |
| 55 | have been enclosed in group symbols if its quantity were 1. |
| 56 | |
| 57 | ## License |
| 58 | |
| 59 | I, Matt McCutchen, the sole author of SuperbChemistry, waive my copyright to it, |
| 60 | placing it in the public domain. SuperbChemistry comes with absolutely no |
| 61 | warranty. |