SuperbChemistry 3.0
[superbchemistry/superbchemistry.git] /
1# SuperbChemistry
3This is an extension for [OpenOffice]( and
4[LibreOffice]( that applies superscript and
5subscript formatting to chemical formulas in bulk in Writer documents. See [the
6web page]( for user documentation.
8The rest of this document refers to LibreOffice, but the same remarks apply to
11## Development
13Run `make clean all` to generate `SuperbChemistry.oxt`, which you can install in
14LibreOffice via "Tools" -> "Extension Manager".
16By default, the library is installed read-only to prevent users from making
17changes that would be lost without warning if they uninstall the extension. For
18development, you can change `library:readonly="true"` to
19`library:readonly="false"` in `extension/SuperbChemistry/*.xlb` so you can edit
20the library in LibreOffice. Then you can copy the edited `Main.xba` from your
21profile (a typical location is
23but this will depend on your operating system and application version) back to
24this working tree.
26`SuperbChemistry-test.odt` is a test suite that exercises most cases of the
27formatting rules.
29## Formatting rules
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.
57## License
59I, Matt McCutchen, the sole author of SuperbChemistry, waive my copyright to it,
60placing it in the public domain. SuperbChemistry comes with absolutely no