README.md

   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.