• View
• Edit
• History
• Attach
• Print
• Backlinks

SimpleChem

Questions answered by this recipe

Is there a simple way to write chemical formulas, such as (C₆H₅)₂CHNH₂, without having to include all those markup characters?

Description

The simplechem.zipΔ extension offers simple, inline markup that easily represents even complex chemical formulas with a minimum of markup characters. The recipe takes advantage of the structured format of chemical formulas, and inserts appropriate markup based on simple context rules. The result is surprisingly powerful, yet leaves chemical formulas easily readable by human chemists while editing.

Notes

The goal of these markup rules is to allow authors to concentrate on the discussion of their chemistry, not the intricacies of marking up the chemical formulas. The chemical formulas used in discussions of chemical reaction schemes are often complex, and it is extremely convenient to write, for instance, "the amino-terminal polymer (H2N-PEO-NH2)", and have the subscripts and other special characters be automatically generated.

Installation

1. Download and extract simplechem.zipΔ to the PmWiki's root directory.
2. Make sure the cookbook/simplechem.php file is readable by the Web server.
3. In your local/config.php file, include the simplechem.php script:

  include_once('cookbook/simplechem.php');

Once installed, chemical formulas on all pages are automatically marked up according to the rules below.

Markup Rules and Syntax

Two types of rules are provided to support chemical formulas in text. A simple, transparent rule automatically subscripts numbers in text that appears to be a chemical formula. A more advanced rule is explicitly invoked by a leading ampersand (&) character, and offers much more powerful markup options.

Simple (transparent) chemical formula markup:

Any string that appears to be a common atom followed by a number is rewritten to subscript the number. Strings like CH3CH2CH2OH, polymer-NH2, and H2SO4 are automatically converted to chemical formulas.

Recognized atoms are C, H, O, N, P, S, Na, Si, Cl, and Br. These represent the most commonly encountered in biochemistry; extending this rule to other atoms is trivial.

This markup makes it natural to write about (for instance) H₂N-C₆H₄-COOH (p-aminobenzoic acid), or simple reactions like this:

3NaOH + H₃PO₄ ↔ Na₃PO₄ + 3H₂O

Some examples of transparent chemical formula markup are:

The transparent method can be combined with explicit markup to extend the repertoire of chemical formulas that can be created:

Clearly, writing the explicit markup quickly becomes cumbersome, and the resulting source is often hard to read and understand while editing.

More advanced chemistry markup:

For more complicated formulas, the author must signal the start of the formula text with a leading ampersand ('&') character. The formula continues until a character other than numbers, letters, or certain punctuation is encountered.

The text "&formula" is interpreted as follows:

• Strings of numbers following letters, periods or parentheses in the chemical formula are subscripted.
• The '.' character is replaced with an HTML middot (·) character, as in 'CuSO₄ · 6H₂O'.
• The string '==' is converted to a triple bond (rendered as a mathematical "≡" character), as in 'CH₃C≡N'.
• Trailing '*' characters are converted to HTML bullet (•) characters (free radicals, e.g. 'HO•').
• Trailing '+' or '-' characters become ionic charges (e.g. the text 'SO4-- ion' becomes 'SO₄^2– ion').
• Lowercase letters following the ')' character in polymer formulas, such as '(PEO)m(PPO)n', are automatically subscripted and italicized ('(PEO)_m(PPO)_n').
• Chemical "R-groups" with numerical indices are superscripted instead of subscripted. For example, 'R1-NH2CH2-R2' is rendered as 'R¹-NH₂CH₂-R² '.

Despite the relative simplicity of these rules, this markup scheme allows a wide range of formulas to be rendered with very minimal markup. See below for more illustrative examples.

Some examples will help demonstrate the power of this markup:

Dabsyl chloride [&(CH3)2N(C6H4)N=N(C6H4)SO2Cl]
reacts with primary amines (-NH2).

NaN3 (sodium azide) has a toxicity
similar to cyanides (e.g. &NaC==N).

&-C-C==N bonds are common. The 
acetylides (&R1-C==C-R2) also exist.

H2O2 exposed to UV light can generate
a hydroxyl radical (&HO*). Organic peroxides
(&R1OOH) can create &R1O* radicals.

Note that the '+/-' symbols representing a charge must terminate an expression. To get multiple charges (e.g. an ionic pair), simply merge two formula statements:

Implementation considerations and limitations

Note that the markup needs to be done after links are resolved, to avoid incorrectly adding HTML markup to link names like:

• This [[CHEMSKETCH2 | link to CHEMSKETCH2]] doesn't work because the '2' in 'H2' is subscripted.

The simple markup rule is fairly specific, but occasionally it will incorrectly mark up a word. To prevent this, simply wrap the offending text in [= ... =] to prevent markup.

For example, the string 'MP3' appears to be a simple chemical formula (because of the P followed by a digit). To prevent the subscript on the '3', just enclose the string in '[= ... =]' markers:

See also

Contributors

Initial implementation by Karl Schilke (Schilkek) for Oregon State University's School of Chemical, Biological and Environmental Engineering.

This script is heavily based on suggestions by Peter Bowers and John Rankin. The author is grateful for their help and code examples.

Comments