diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/chemformula |
Initial commit
Diffstat (limited to 'macros/latex/contrib/chemformula')
-rw-r--r-- | macros/latex/contrib/chemformula/README | 32 | ||||
-rw-r--r-- | macros/latex/contrib/chemformula/chemformula.sty | 3569 | ||||
-rw-r--r-- | macros/latex/contrib/chemformula/chemformula_en.pdf | bin | 0 -> 957854 bytes | |||
-rw-r--r-- | macros/latex/contrib/chemformula/chemformula_en.tex | 1765 |
4 files changed, 5366 insertions, 0 deletions
diff --git a/macros/latex/contrib/chemformula/README b/macros/latex/contrib/chemformula/README new file mode 100644 index 0000000000..b171813d7d --- /dev/null +++ b/macros/latex/contrib/chemformula/README @@ -0,0 +1,32 @@ +-------------------------------------------------------------------------- +the CHEMFORMULA package v4.15e 2017/03/23 + + typeset chemical compounds and reactions + +-------------------------------------------------------------------------- +Clemens Niederberger +Web: http://www.mychemistry.eu/forums/forum/chemformula/ +E-Mail: contact@mychemistry.eu +-------------------------------------------------------------------------- +Copyright 2011-2017 Clemens Niederberger + +This work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3 +of this license or (at your option) any later version. +The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3 or later is part of all distributions of LaTeX +version 2005/12/01 or later. + +This work has the LPPL maintenance status `maintained'. + +The Current Maintainer of this work is Clemens Niederberger. +-------------------------------------------------------------------------- +The chemformula package consists of the following files + - chemformula.sty, + - chemformula_en.tex, chemformula_en.pdf, + - README +-------------------------------------------------------------------------- +If you have any ideas, questions, suggestions or bugs to report, please +feel free to contact me. +-------------------------------------------------------------------------- diff --git a/macros/latex/contrib/chemformula/chemformula.sty b/macros/latex/contrib/chemformula/chemformula.sty new file mode 100644 index 0000000000..d909b17879 --- /dev/null +++ b/macros/latex/contrib/chemformula/chemformula.sty @@ -0,0 +1,3569 @@ +% -------------------------------------------------------------------------- +% the CHEMFORMULA package +% +% typeset chemical compounds and reactions +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% -------------------------------------------------------------------------- +% https://github.com/cgnieder/chemformula/ +% contact@mychemistry.eu +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +% Copyright 2011-2017 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +\RequirePackage{expl3,xparse,l3keys2e,tikz,amsmath,xfrac,nicefrac,scrlfile} +\usetikzlibrary{arrows.meta} + +\ExplSyntaxOn +\tl_const:Nn \c_chemformula_date_tl {2017/03/23} +\tl_const:Nn \c_chemformula_version_number_tl {4.15} +\tl_const:Nn \c_chemformula_version_suffix_tl {e} +\tl_const:Nx \c_chemformula_version_tl + { \c_chemformula_version_number_tl \c_chemformula_version_suffix_tl } +\tl_const:Nn \c_chemformula_info_tl + {typeset~ chemical~ compounds~ and~ reactions} + +\ProvidesExplPackage + {chemformula} + {\c_chemformula_date_tl} + {\c_chemformula_version_tl} + {\c_chemformula_info_tl \c_space_tl (CN)} + +% -------------------------------------------------------------------------- +% warning and error messages: +\msg_new:nnn {chemformula} {missing-argument} + { + Maybe~you've~forgotten~to~add~the~second~argument~to~name~syntax?~ + "!(<name>)(<chemformula>)".\\ + Or~you~have~forgotten~to~add~a~group~between~an~exclamation~mark~and~ + the~following~parenthesis?~"!~{}()"\\ + Either~way~-~I~don't~know~what~to~do~ \msg_line_context: . + } + +\msg_new:nnn {chemformula} {new-arrow} + { + You've~tried~to~define~the~arrow~type~\tl_to_str:n {#1} \c_space_tl with + ~\token_to_str:N \NewChemArrow \c_space_tl but~it~already~exists. + ~Choose~another~name. + } + +\msg_new:nnn {chemformula} {renew-arrow} + { + You've~tried~to~renew~the~arrow~type~\tl_to_str:n {#1} ~but~it~doesn't~ + exist. + } + +\msg_new:nnn {chemformula} {unknown-arrow} + { + The~ arrow~ type~ \tl_to_str:n {#1} ~ doesn't~ exist~ \msg_line_context: . + } + +\msg_new:nnn {chemformula} {new-bond} + { + You've~tried~to~define~the~bond~type~\tl_to_str:n {#1} \c_space_tl with + ~\token_to_str:N \NewChemBond \c_space_tl but~it~already~exists. + ~Choose~another~name. + } + +\msg_new:nnn {chemformula} {renew-bond} + { + You've~tried~to~renew~the~bond~type~\tl_to_str:n {#1} ~but~it~doesn't~ + exist. + } + +\msg_new:nnn {chemformula} {new-compound-property} + { + You've~ tried~ to~ define~ the~ compound~ property~ `#1'~ with~ + \token_to_str:N \NewChemCompoundProperty \c_space_tl but~ a~ property~ + `#1'~ already~ exists.~ Choose~ another~ symbol. + } + +\msg_new:nnn {chemformula} {renew-compound-property} + { + You've~ tried~ to~ redefine~ the~ compound~ property~ `#1'~ with~ + \token_to_str:N \RenewChemCompoundProperty \c_space_tl but~ a~ property~ + `#1'~ doesn't~ seem~ to~ exist. + } + +\msg_new:nnn {chemformula} {new-addition-symbol} + { + You've~ tried~ to~ define~ the~ addition~ symbol~ `#1'~ (input~ symbol:~ + `#2')~ with~ \token_to_str:N \NewChemAdditionSymbol \c_space_tl but~ a~ + symbol~ with~ the~ name~ `#1'~ or~ the~ input~ `#2'~ already~ exists.~ + Choose~ another~ name/input. + } + +\msg_new:nnn {chemformula} {renew-addition-symbol} + { + You've~ tried~ to~ redefine~ the~ addition~ symbol~ `#1'~ (input~ symbol:~ + `#2')~ but~ a~ symbol~ with~ the~ name~ `#1'~ or~ input~ `#2' doesn't~ + exist. + } + +\msg_new:nnn {chemformula} {new-symbol} + { + You've~ tried~ to~ define~ the~ symbol~ `#1'~ with~ \token_to_str:N + \NewChemSymbol \c_space_tl but~ a~ symbol~ `#1'~ already~ exists.~ + Choose~ another~ input. + } + +\msg_new:nnn {chemformula} {renew-symbol} + { + You've~ tried~ to~ redefine~ the~ symbol~ `#1'~ with~ \token_to_str:N + \NewChemSymbol \c_space_tl but~ a~ symbol~ `#1'~ doesn't~ exist. + } + +\msg_new:nnn {chemformula} {command-deprecated} + { + The~command~\token_to_str:N #1 \c_space_tl is~deprecated.~Use~ + \token_to_str:N #2 \c_space_tl instead. + } + +\cs_new_protected:Npn \chemformula_define_deprecated:NNn #1#2#3 + { + \cs_new_protected:Npn #1 + { + \msg_warning:nnnn {chemformula} {command-deprecated} + {#1} {#2} + #3 + } + } + +% -------------------------------------------------------------------------- +% variants of kernel functions: +\cs_generate_variant:Nn \keys_set:nn { nV } +\cs_generate_variant:Nn \tl_if_blank:nF { V } +\cs_generate_variant:Nn \tl_if_in:nnT { x , nV } +\cs_generate_variant:Nn \tl_if_eq:nnT { V, x } +\cs_generate_variant:Nn \tl_if_eq:nnTF { o } +\cs_generate_variant:Nn \tl_set:Nn { cV } +\cs_generate_variant:Nn \tl_replace_all:Nnn { NV } +\cs_generate_variant:Nn \tl_replace_once:Nnn { Nxx } +\cs_generate_variant:Nn \tl_set_rescan:Nnn { NnV } +\cs_generate_variant:Nn \prop_item:Nn { NV } +\cs_generate_variant:Nn \prop_if_in:NnT { Nx } +\cs_generate_variant:Nn \dim_set:Nn { NV } +\cs_generate_variant:Nn \skip_set:Nn { cV } +\cs_generate_variant:Nn \str_if_eq:nnT { V } + +% -------------------------------------------------------------------------- +% VARIABLES +% temporary variables: +\tl_new:N \l__chemformula_tmpa_tl +\tl_new:N \l__chemformula_tmpb_tl +\tl_new:N \l__chemformula_tmpc_tl + +\dim_new:N \l__chemformula_tmpa_dim +\dim_new:N \l__chemformula_tmpb_dim +\dim_new:N \l__chemformula_tmpc_dim + +\int_new:N \l__chemformula_tmpa_int +\int_new:N \l__chemformula_tmpb_int +\int_new:N \l__chemformula_tmpc_int + +\box_new:N \l__chemformula_tmpa_box +\box_new:N \l__chemformula_tmpb_box + +\seq_new:N \l__chemformula_tmpa_seq + +% booleans: +% these are official: +\bool_new:N \l_chemformula_inside_ch_bool +\bool_new:N \l_chemformula_formal_charges_bool +\bool_new:N \l_chemformula_formal_chem_bool +\bool_set_true:N \l_chemformula_formal_chem_bool +% those are private: +\bool_new:N \l__chemformula_options_bool +\bool_new:N \l__chemformula_is_option_bool +\bool_new:N \l__chemformula_stoich_bool +\bool_new:N \l__chemformula_no_stoich_bool +\bool_new:N \l__chemformula_is_addition_symbol_bool +\bool_new:N \l__chemformula_is_symbol_bool +\bool_new:N \l__chemformula_is_arrow_bool +\bool_new:N \l__chemformula_is_name_bool +\bool_new:N \l__chemformula_stoich_is_iupac_bool +\bool_new:N \l__chemformula_stoich_parse_iupac_bool +\bool_new:N \l__chemformula_first_last_text_bool +\bool_new:N \l__chemformula_first_last_double_bool +\bool_new:N \l__chemformula_first_last_single_bool +\bool_new:N \l__chemformula_first_last_math_bool +\bool_new:N \l__chemformula_first_last_dollar_bool +\bool_new:N \l__chemformula_first_last_mathbraces_bool +\bool_new:N \l__chemformula_number_style_math_bool +\bool_new:N \l__chemformula_charge_style_math_bool +\bool_new:N \l__chemformula_is_isotope_bool +\bool_new:N \l__chemformula_xfrac_bool +\bool_new:N \l__chemformula_nicefrac_bool +\bool_new:N \l__chemformula_mathfrac_bool +\bool_set_true:N \l__chemformula_mathfrac_bool +\bool_new:N \l__chemformula_fss_bool +\bool_new:N \l__chemformula_fontspec_bool +\bool_new:N \l__chemformula_fss_family_bool +\bool_new:N \l__chemformula_fss_series_bool +\bool_new:N \l__chemformula_fss_shape_bool +\bool_new:N \l__chemformula_name_width_bool +\bool_new:N \l__chemformula_charge_full_shift_bool +\bool_new:N \l__chemformula_tikzexternaldisable_bool +\bool_set_true:N \l__chemformula_tikzexternaldisable_bool +\bool_new:N \l__chemformula_kroegervink_bool +\bool_new:N \l__chemformula_inside_subscript_bool +\bool_new:N \l__chemformula_inside_superscript_bool + +% dimensions: +\dim_new:N \l__chemformula_arrow_length_dim +\dim_new:N \l__chemformula_arrow_label_height_dim +\dim_new:N \l__chemformula_arrow_label_offset_dim +\dim_set:Nn \l__chemformula_arrow_label_offset_dim {2pt} +\dim_new:N \l__chemformula_arrow_minimum_length_dim +\dim_new:N \l__chemformula_arrow_shortage_dim +\dim_new:N \l__chemformula_arrow_offset_dim +\dim_new:N \l__chemformula_arrow_yshift_dim +\dim_set:Nn \l__chemformula_arrow_yshift_dim {0pt} +\dim_new:N \l__chemformula_radical_radius_dim +\dim_set:Nn \l__chemformula_radical_radius_dim {.2ex} +\dim_new:N \l__chemformula_radical_hshift_dim +\dim_set:Nn \l__chemformula_radical_hshift_dim {.15em} +\dim_new:N \l__chemformula_radical_vshift_dim +\dim_set:Nn \l__chemformula_radical_vshift_dim {.5ex} +\dim_new:N \l__chemformula_radical_space_dim +\dim_set:Nn \l__chemformula_radical_space_dim {.3em} +\dim_new:N \l__chemformula_arrow_head_dim +\dim_new:N \l__chemformula_name_dim +\dim_new:N \l__chemformula_adduct_space_dim +\dim_set:Nn \l__chemformula_adduct_space_dim {.1333em} +\dim_new:N \l__chemformula_charge_shift_dim +\dim_set:Nn \l__chemformula_charge_shift_dim {.5ex} +\dim_new:N \l__chemformula_subscript_shift_dim +\dim_new:N \l__chemformula_superscript_shift_dim +\dim_new:N \l__chemformula_subscript_dim +\dim_zero:N \l__chemformula_subscript_dim +\dim_new:N \l__chemformula_superscript_dim +\dim_zero:N \l__chemformula_superscript_dim +\dim_new:N \l__chemformula_bond_dim +\dim_set:Nn \l__chemformula_bond_dim {.5833em} +\dim_new:N \l__chemformula_bond_space_dim +\dim_set:Nn \l__chemformula_bond_space_dim {.07em} +\dim_new:N \l__chemformula_elspec_pair_distance_dim +\dim_set:Nn \l__chemformula_elspec_pair_distance_dim {1ex} +\dim_new:N \l__chemformula_elspec_pair_line_length_dim +\dim_set:Nn \l__chemformula_elspec_pair_line_length_dim {1.5ex} +\dim_new:N \l__chemformula_elspec_pair_width_dim +\dim_set:Nn \l__chemformula_elspec_pair_width_dim {1pt} +\dim_new:N \l__chemformula_kroegervink_positive_radius_dim +\dim_set:Nn \l__chemformula_kroegervink_positive_radius_dim {.3ex} +\dim_new:N \l__chemformula_kroegervink_positive_hshift_dim +\dim_set:Nn \l__chemformula_kroegervink_positive_hshift_dim {.15em} +\dim_new:N \l__chemformula_kroegervink_positive_vshift_dim +\dim_set:Nn \l__chemformula_kroegervink_positive_vshift_dim {.5ex} +\dim_new:N \l__chemformula_kroegervink_positive_space_dim +\dim_set:Nn \l__chemformula_kroegervink_positive_space_dim {.4em} + +% skips: +\skip_new:N \l__chemformula_stoich_space_skip +\skip_set:Nn \l__chemformula_stoich_space_skip { .1667em plus .0333em minus .0117em } +\skip_new:N \l__chemformula_math_space_skip +\skip_set:Nn \l__chemformula_math_space_skip { .1667em plus .0333em minus .0117em } + +% integers: +\int_new:N \l__chemformula_count_tokens_int +\int_new:N \g__chemformula_lewis_int + +% token lists: +\tl_new:N \l__chemformula_compound_sep_tl +\tl_set:Nn \l__chemformula_compound_sep_tl {.5em} +\tl_new:N \l__chemformula_compound_tl +\tl_new:N \l__chemformula_arrow_ratio_tl +\tl_set:Nn \l__chemformula_arrow_ratio_tl {.6} +\tl_new:N \l__chemformula_radical_style_tl +\tl_new:N \l__chemformula_arrow_head_tl +\tl_set:Nn \l__chemformula_arrow_head_tl {cf} +\tl_new:N \l__chemformula_upper_label_tl +\tl_new:N \l__chemformula_lower_label_tl +\tl_new:N \l__chemformula_arrow_style_tl +\tl_new:N \l__chemformula_arrow_label_style_tl +\tl_set:Nn \l__chemformula_arrow_label_style_tl { \footnotesize } +\tl_new:N \l__chemformula_arrow_type_tl +\tl_new:N \l__chemformula_arrow_penalty_tl +\tl_set:Nn \l__chemformula_arrow_penalty_tl {0} +\tl_new:N \l__chemformula_arrow_offset_tl +\tl_set:Nn \l__chemformula_arrow_offset_tl {.75em} +\tl_new:N \l__chemformula_bond_penalty_tl +\tl_set:Nn \l__chemformula_bond_penalty_tl {10000} +\tl_new:N \l__chemformula_chemformula_tmpa_tl +\tl_new:N \g__chemformula_options_tl +\tl_new:N \g__chemformula_output_tl +\tl_new:N \l__chemformula_input_tl +\tl_new:N \l__chemformula_stoich_tl +\tl_new:N \l__chemformula_decimal_output_tl +\tl_set:Nn \l__chemformula_decimal_output_tl {.} +\tl_new:N \l__chemformula_font_family_tl +\tl_set_eq:NN \l__chemformula_font_family_tl \f@family +\tl_new:N \l__chemformula_font_series_tl +\tl_set_eq:NN \l__chemformula_font_series_tl \f@series +\tl_new:N \l__chemformula_font_shape_tl +\tl_set_eq:NN \l__chemformula_font_shape_tl \f@shape +\tl_new:N \l__chemformula_format_tl +\tl_new:N \l__chemformula_atom_format_tl +\tl_new:N \l__chemformula_fontspec_options_tl +\tl_new:N \l__chemformula_fontspec_argument_tl +\tl_new:N \l__chemformula_name_format_tl +\tl_set:Nn \l__chemformula_name_format_tl { \scriptsize\centering } +\tl_new:N \l__chemformula_subscript_shift_additional_tl +\tl_set:Nn \l__chemformula_subscript_shift_additional_tl {0pt} +\tl_new:N \l__chemformula_superscript_shift_additional_tl +\tl_set:Nn \l__chemformula_superscript_shift_additional_tl {0pt} +\tl_new:N \l__chemformula_subscript_tl +\tl_new:N \l__chemformula_superscript_tl +\tl_new:N \l__chemformula_elspec_angle_tl +\tl_new:N \l__chemformula_elspec_radius_tl +\tl_set:Nn \l__chemformula_elspec_radius_tl {.5ex} +\tl_new:N \l__chemformula_elspec_default_type_tl +\tl_set:Nn \l__chemformula_elspec_default_type_tl {pair} +\tl_const:Nx \c__chemformula_colon_tl { \token_to_str:N : } +\tl_new:N \l__chemformula_kroegervink_positive_style_tl +\tl_new:N \l__chemformula_kroegervink_neutral_tl +\tl_set:Nn \l__chemformula_kroegervink_neutral_tl {$\times$} +\tl_new:N \l__chemformula_adduct_penalty_tl +\tl_set:Nn \l__chemformula_adduct_penalty_tl {300} + +% property lists: +\prop_new:N \l__chemformula_arrows_code_prop +\prop_new:N \l__chemformula_compound_prop +\prop_new:N \l__chemformula_bonds_prop +\prop_new:N \l__chemformula_stoich_prop +\prop_new:N \l__chemformula_charge_prop +\prop_new:N \l__chemformula_numbers_prop +\prop_new:N \l__chemformula_no_stoich_prop +\prop_new:N \l__chemformula_lewis_elspec_types_prop +\prop_new:N \l__chemformula_kroegervink_prop + +% sequences: +\seq_new:N \l__chemformula_arrows_type_seq +\seq_new:N \l__chemformula_input_seq + +% boxes: +\box_new:N \l__chemformula_arrow_arg_i_box +\box_new:N \l__chemformula_arrow_arg_ii_box +\box_new:N \l__chemformula_superscript_box +\box_new:N \l__chemformula_subscript_box + +% -------------------------------------------------------------------------- +% general and helper functions: +\cs_new_protected:Npn \chemformula_tikz:nn #1#2 + { + \group_begin: + \chemformula_tikzexternaldisable: + \tikz [ #1 ] {#2} + \group_end: + } +\cs_generate_variant:Nn \chemformula_tikz:nn { xn,nf } + +\cs_new_protected:Npn \chemformula_draw:nn #1#2 + { \draw [ #1 ] #2 ; } +\cs_generate_variant:Nn \chemformula_draw:nn { xn,nx,xx,xf,Vn } + +\cs_new_protected:Npn \chemformula_node:nn #1#2 + { \node [ #1 ] {#2} ; } +\cs_generate_variant:Nn \chemformula_node:nn { x } + +\cs_new_protected:Npn \chemformula_node:nnn #1#2#3 + { \node [ #1 ] ( #2 ) {#3} ; } +\cs_generate_variant:Nn \chemformula_node:nnn { nx } + +\cs_new_protected:Npn \chemformula_allow_break: + { \tex_penalty:D \c_zero } + +\cs_new_protected:Npn \chemformula_leave_vmode: + { \hbox_unpack:N \c_empty_box } + +\cs_new_protected:Npn \chemformula_nobreak: + { \tex_penalty:D \c_ten_thousand } + +\cs_new_protected:Npn \chemformula_skip_nobreak:N #1 + { + \chemformula_nobreak: + \skip_horizontal:N #1 + \chemformula_nobreak: + } +\cs_generate_variant:Nn \chemformula_skip_nobreak:N {c} + +\cs_new_protected:Npn \chemformula_skip_nobreak:n #1 + { + \chemformula_nobreak: + \skip_horizontal:n {#1} + \chemformula_nobreak: + } + +\cs_new_protected:Npn \chemformula_skip_nobreak_penalty:Nn #1#2 + { + \chemformula_nobreak: + \skip_horizontal:N #1 + \tex_penalty:D #2 \scan_stop: + } +\cs_generate_variant:Nn \chemformula_skip_nobreak_penalty:Nn {c,NV} + +\cs_new_protected:Npn \chemformula_dim_to_width:Nn #1#2 + { + \hbox_set:Nn \l__chemformula_tmpa_box {#2} + \dim_set:Nn #1 { \box_wd:N \l__chemformula_tmpa_box } + \box_clear:N \l__chemformula_tmpa_box + } + +% -------------------------------------------------------------------------- +% prevent externalisation of tikz parts of the formulae: +\AtBeginDocument { \providecommand \tikzexternaldisable {} } + +\keys_define:nn { chemformula } + { + tikz-external-disable .bool_set:N = + \l__chemformula_tikzexternaldisable_bool + } + +\cs_new_protected:Npn \chemformula_tikzexternaldisable: + { + \bool_if:NT \l__chemformula_tikzexternaldisable_bool + { \tikzexternaldisable } + } + +% -------------------------------------------------------------------------- +% circled charge signs: +\cs_new_protected:Npn \chemformula_fplus: + { \ensuremath { \__chemformula_fplus: } } + +\cs_new_protected:Npn \__chemformula_fplus: + { \mathpalette \__chemformula_fplus_aux: \bigcirc } + +\cs_new_protected:Npn \__chemformula_fplus_aux: #1#2 + { + \ooalign + { + \tex_hfil:D + \c_math_toggle_token + #1 + \chemformula_plain_plus: + \c_math_toggle_token + \tex_hfil:D + \tex_cr:D + \tex_hfil:D + \c_math_toggle_token #1#2 \c_math_toggle_token + \tex_hfil:D + \tex_cr:D + } + } + +\cs_new_protected:Npn \chemformula_fminus: + { \ensuremath { \__chemformula_fminus: } } + +\cs_new_protected:Npn \__chemformula_fminus: + { \mathpalette \__chemformula_fminus_aux_aux: \bigcirc } + +\cs_new_protected:Npn \__chemformula_fminus_aux_aux: #1#2 + { + \ooalign + { + \tex_hfil:D + \c_math_toggle_token + #1 + \chemformula_plain_minus: + \c_math_toggle_token + \tex_hfil:D + \tex_cr:D + \tex_hfil:D + \c_math_toggle_token #1#2 \c_math_toggle_token + \tex_hfil:D + \tex_cr:D + } + } + +\cs_new_protected:Npn \chemformula_plain_plus: + { + \bool_if:NTF \l__chemformula_charge_style_math_bool + { \ensuremath {+} } + { \mode_if_math:TF { \text {+} } {+} } + } + +\cs_new_protected:Npn \chemformula_formal_plus: + { + \bool_if:NTF \l_chemformula_formal_chem_bool + { \chemformula_fplus: } + { + \mode_if_math:TF + { \oplus } + { \c_math_toggle_token \oplus \c_math_toggle_token } + } + } + +\cs_new_protected:Npn \chemformula_plus: + { + \bool_if:NTF \l_chemformula_formal_charges_bool + { \chemformula_formal_plus: } + { \chemformula_plain_plus: } + } + +\cs_new_protected:Npn \chemformula_plain_minus: + { + \bool_if:NTF \l__chemformula_charge_style_math_bool + { \ensuremath {-} } + { \mode_if_math:TF { \text { \textendash } } { \textendash } } + } + +\cs_new_protected:Npn \chemformula_formal_minus: + { + \bool_if:NTF \l_chemformula_formal_chem_bool + { \chemformula_fminus: } + { + \mode_if_math:TF + { \ominus } + { \c_math_toggle_token \ominus \c_math_toggle_token } + } + } + +\cs_new_protected:Npn \chemformula_minus: + { + \bool_if:NTF \l_chemformula_formal_charges_bool + { \chemformula_formal_minus: } + { \chemformula_plain_minus: } + } + +% -------------------------------------------------------------------------- +% Some basic internal commands: + +\cs_new_protected:Npn \chemformula_radical_or_decimal: + { + \peek_meaning:NTF \c_group_begin_token + { \chemformula_decimal: } + { \chemformula_radical: } + } + +\cs_new_protected:Npn \chemformula_radical: + { + \hbox_overlap_right:n + { + \chemformula_tikz:xn + { + \l__chemformula_radical_style_tl , + baseline , + minimum~ height = 0pt , + minimum~ width = 0pt , + inner~ sep = 0pt , + outer~ sep = 0pt , + overlay + } + { + \fill (0,0) + ++( + \l__chemformula_radical_hshift_dim , + \l__chemformula_radical_vshift_dim + ) + circle (\l__chemformula_radical_radius_dim) ; + } + } + \chemformula_skip_nobreak:N \l__chemformula_radical_space_dim + } + +\keys_define:nn {chemformula} + { + % TikZ style: + radical-style .tl_set:N = \l__chemformula_radical_style_tl , + radical-radius .dim_set:N = \l__chemformula_radical_radius_dim , + % shift before: + radical-hshift .dim_set:N = \l__chemformula_radical_hshift_dim , + radical-vshift .dim_set:N = \l__chemformula_radical_vshift_dim , + % space after: + radical-space .dim_set:N = \l__chemformula_radical_space_dim + } + +\cs_new_protected:Npn \chemformula_adduct: + { + \chemformula_skip_nobreak:N \l__chemformula_adduct_space_dim + \textperiodcentered + \chemformula_skip_nobreak_penalty:NV + \l__chemformula_adduct_space_dim + \l__chemformula_adduct_penalty_tl + } +\cs_new_eq:NN \chemformula_star_adduct: \chemformula_adduct: + +% -------------------------------------------------------------------------- +% Kroeger-Vink notation +\cs_new_protected:Npn \chemformula_kroegervink_negative: + { \ensuremath { \prime } } + +\cs_new_protected:Npn \chemformula_kroegervink_neutral: + { \ensuremath { \text {\l__chemformula_kroegervink_neutral_tl } } } + +\cs_new_protected:Npn \chemformula_kroegervink_positive: + { + \hbox_overlap_right:n + { + \chemformula_tikz:xn + { + \l__chemformula_kroegervink_positive_style_tl , + baseline , + minimum~ height = 0pt , + minimum~ width = 0pt , + inner~ sep = 0pt , + outer~ sep = 0pt , + overlay + } + { + \fill (0,0) + ++( + \l__chemformula_kroegervink_positive_hshift_dim , + \l__chemformula_kroegervink_positive_vshift_dim + ) + circle (\l__chemformula_kroegervink_positive_radius_dim) ; + } + } + \chemformula_skip_nobreak:N \l__chemformula_kroegervink_positive_space_dim + } + +\cs_new_protected:Npn \chemformula_prime: + { + \bool_if:NTF \l__chemformula_kroegervink_bool + { \chemformula_kroegervink_negative: } + { ' } + } + +\keys_define:nn {chemformula} + { + kroeger-vink .bool_set:N = + \l__chemformula_kroegervink_bool , + % TikZ style: + kv-positive-style .tl_set:N = + \l__chemformula_kroegervink_positive_style_tl , + kv-positive-radius .dim_set:N = + \l__chemformula_kroegervink_positive_radius_dim , + % spacing: + kv-positive-hshift .dim_set:N = + \l__chemformula_kroegervink_positive_hshift_dim , + kv-positive-vshift .dim_set:N = + \l__chemformula_kroegervink_positive_vshift_dim , + kv-positive-offset .dim_set:N = + \l__chemformula_kroegervink_positive_space_dim , + % symbol: + kv-neutral-symbol .tl_set:N = + \l__chemformula_kroegervink_neutral_tl + } + +% -------------------------------------------------------------------------- +% ARROW DEFINITION +% arrow heads: + +% full tip for pairs +\pgfarrowsdeclare { cf~internal } { cf~internal } + { + \dim_set:Nn \l__chemformula_arrow_head_dim + { 2.5pt + 2.5\pgflinewidth } + \pgfarrowsleftextend { -\l__chemformula_arrow_head_dim } + \pgfarrowsrightextend { .5\pgflinewidth } + } + { + \dim_set:Nn \l__chemformula_arrow_head_dim + { 2.5pt + 2.5\pgflinewidth } + \pgfsetdash {} { 0pt } + \pgfsetroundjoin + \pgfsetroundcap + \pgfpathmoveto { \pgfpoint { 0pt } { 0pt } } + \pgfpathlineto + { + \pgfpoint + { -\l__chemformula_arrow_head_dim } + { .3\l__chemformula_arrow_head_dim } + } + \pgfpathlineto + { \pgfpoint { -.5\l__chemformula_arrow_head_dim } { 0pt } } + \pgfpathlineto + { + \pgfpoint + { -\l__chemformula_arrow_head_dim } + { -.3\l__chemformula_arrow_head_dim } + } + \pgfpathlineto { \pgfpoint { 0pt } { 0pt } } + \pgfusepathqfillstroke + } + +% half tip on the left +\pgfarrowsdeclare { left~cf~internal } { left~cf~internal } + { + \dim_set:Nn \l__chemformula_arrow_head_dim + { 2.5pt + 2.5\pgflinewidth } + \pgfarrowsleftextend { -\l__chemformula_arrow_head_dim } + \pgfarrowsrightextend { .5\pgflinewidth } + } + { + \dim_set:Nn \l__chemformula_arrow_head_dim + { 2.5pt + 2.5\pgflinewidth } + \pgfsetdash {} { 0pt } + \pgfsetroundjoin + \pgfsetroundcap + \pgfpathmoveto { \pgfpoint { 0pt } { 0pt } } + \pgfpathlineto + { + \pgfpoint + { -\l__chemformula_arrow_head_dim } + { .3\l__chemformula_arrow_head_dim } + } + \pgfpathlineto { \pgfpoint { -.5\l__chemformula_arrow_head_dim } { 0pt } } + \pgfpathlineto { \pgfpoint { 0pt } { 0pt } } + \pgfusepathqfillstroke + } + +% half tip in the right +\pgfarrowsdeclare { right~cf~internal } { right~cf~internal } + { + \dim_set:Nn \l__chemformula_arrow_head_dim + { 2.5pt + 2.5\pgflinewidth } + \pgfarrowsleftextend { -\l__chemformula_arrow_head_dim } + \pgfarrowsrightextend { .5\pgflinewidth } + } + { + \dim_set:Nn \l__chemformula_arrow_head_dim + { 2.5pt + 2.5\pgflinewidth } + \pgfsetdash {} { 0pt } + \pgfsetroundjoin + \pgfsetroundcap + \pgfpathmoveto { \pgfpoint { 0pt } { 0pt } } + \pgfpathlineto + { + \pgfpoint + { -\l__chemformula_arrow_head_dim } + { -.3\l__chemformula_arrow_head_dim } + } + \pgfpathlineto { \pgfpoint { -.5\l__chemformula_arrow_head_dim } { 0pt } } + \pgfpathlineto { \pgfpoint { 0pt } { 0pt } } + \pgfusepathqfillstroke + } + +\pgfkeys{ + cf~ /.tip = {cf~internal} , + left~cf~ /.tip = {left~cf~internal} , + right~cf~ /.tip = {right~cf~internal} +} + +% -------------------------------------------------------------------------- +% determine length in dependency of labels +\cs_new_protected:Npn \__chemformula_determine_arrow_length:NN #1#2 + { + \dim_set:NV \l__chemformula_arrow_offset_dim \l__chemformula_arrow_offset_tl + \box_set_eq:NN \l__chemformula_tmpa_box #1 + \dim_set:Nn \l__chemformula_tmpa_dim { \box_wd:N \l__chemformula_tmpa_box } + \box_set_eq:NN \l__chemformula_tmpa_box #2 + \dim_set:Nn \l__chemformula_tmpb_dim { \box_wd:N \l__chemformula_tmpa_box } + \box_clear:N \l__chemformula_tmpa_box + \dim_compare:nTF { \l__chemformula_tmpa_dim >= \l__chemformula_tmpb_dim } + { \dim_set_eq:NN \l__chemformula_arrow_length_dim \l__chemformula_tmpa_dim } + { \dim_set_eq:NN \l__chemformula_arrow_length_dim \l__chemformula_tmpb_dim } + \dim_add:Nn \l__chemformula_arrow_length_dim + { 2\l__chemformula_arrow_offset_dim } + \dim_compare:nF + { \l__chemformula_arrow_length_dim > \l__chemformula_arrow_minimum_length_dim } + { + \dim_set_eq:NN + \l__chemformula_arrow_length_dim + \l__chemformula_arrow_minimum_length_dim + } + \dim_set:Nn \l__chemformula_arrow_shortage_dim + { + ( + \l__chemformula_arrow_length_dim + - + \l__chemformula_arrow_length_dim * + \dim_ratio:nn { \l__chemformula_arrow_ratio_tl pt } { 1pt } + ) * 1/2 + } + \box_set_eq:NN \l__chemformula_tmpa_box #1 + \dim_set:Nn \l__chemformula_tmpa_dim + { \box_ht:N \l__chemformula_tmpa_box + \box_dp:N \l__chemformula_tmpa_box } + \box_set_eq:NN \l__chemformula_tmpa_box #2 + \dim_set:Nn \l__chemformula_tmpb_dim + { \box_ht:N \l__chemformula_tmpa_box + \box_dp:N \l__chemformula_tmpa_box } + \box_clear:N \l__chemformula_tmpa_box + \dim_compare:nTF { \l__chemformula_tmpa_dim >= \l__chemformula_tmpb_dim } + { \dim_set_eq:NN \l__chemformula_arrow_label_height_dim \l__chemformula_tmpa_dim } + { \dim_set_eq:NN \l__chemformula_arrow_label_height_dim \l__chemformula_tmpb_dim } + } + +% -------------------------------------------------------------------------- +% define arrow types + +% draw arrows: +\cs_new_protected:Npn \__chemformula_draw_arrow:nnn #1#2#3 + { + \chemformula_if_is_arrow:nTF {#1} + { + \prop_get:NnN \l__chemformula_arrows_code_prop + {#1} + \l__chemformula_tmpa_tl + \__chemformula_arrow_draw:Vnn \l__chemformula_tmpa_tl {#2} {#3} + } + { \msg_error:nnn {chemformula} {unknown-arrow} {#1} } + } + +% this will be \arrow inside \ch +\DeclareDocumentCommand \charrow { mO{}O{} } + { + \group_begin: + \__chemformula_draw_arrow:nnn {#1} {#2} {#3} + \group_end: + } + +% draw the arrows +\cs_new_protected:Npn \__chemformula_arrow_draw:nnn #1#2#3 + { + \chemformula_nobreak: + % prepare arrow code for drawing: + \tl_set_rescan:Nnn \l__chemformula_tmpc_tl + { \char_set_catcode_letter:N \_ } {#1} + % determine length of the arrow + \hbox_set:Nn \l__chemformula_arrow_arg_i_box + { \tl_use:N \l__chemformula_arrow_label_style_tl #2 } + \hbox_set:Nn \l__chemformula_arrow_arg_ii_box + { \tl_use:N \l__chemformula_arrow_label_style_tl #3 } + \__chemformula_determine_arrow_length:NN + \l__chemformula_arrow_arg_i_box + \l__chemformula_arrow_arg_ii_box + \chemformula_tikz:nf + { inner~sep=0, baseline=(chemformula_arrow_start.base) } + { + % the coordinates + \chemformula_draw:xn + { \l__chemformula_arrow_style_tl } + { + coordinate (chemformula_arrow_start) (0pt,0pt) + ++ ( \l__chemformula_compound_sep_tl , .3432em) + ++ (0pt,\l__chemformula_arrow_yshift_dim) + coordinate (cf_arrow_start) + ++ ( .5 * \dim_use:N \l__chemformula_arrow_length_dim , 0pt) + coordinate (cf_arrow_mid) + ++ ( .5 * \dim_use:N \l__chemformula_arrow_length_dim , 0pt) + coordinate (cf_arrow_end) + ++ ( \l__chemformula_compound_sep_tl , 0pt ) + (cf_arrow_start) ++ (\l__chemformula_arrow_shortage_dim , 0pt) + coordinate (cf_arrow_mid_start) + (cf_arrow_end) ++ (-\l__chemformula_arrow_shortage_dim , 0pt) + coordinate (cf_arrow_mid_end) + } + % the arrow labels: + \draw + node + [ above=\l__chemformula_arrow_label_offset_dim ] at (cf_arrow_mid) + { \box_use:N \l__chemformula_arrow_arg_i_box } + node + [ below=\l__chemformula_arrow_label_offset_dim ] at (cf_arrow_mid) + { \box_use:N \l__chemformula_arrow_arg_ii_box } + ; + \tl_use:N \l__chemformula_tmpc_tl + } + \chemformula_skip_nobreak_penalty:NV + \c_zero_skip + \l__chemformula_arrow_penalty_tl + } +\cs_generate_variant:Nn \__chemformula_arrow_draw:nnn { V } + +\prg_new_conditional:Npnn \chemformula_if_is_arrow:n #1 {p,T,F,TF} + { + \seq_if_in:NnTF \l__chemformula_arrows_type_seq {#1} + { \prg_return_true: } + { \prg_return_false: } + } + +% commands to declare arrows (can also be used by users): +% #1: symbol, #2: code +\NewDocumentCommand \NewChemArrow {mm} + { + \chemformula_if_is_arrow:nTF {#1} + { \msg_error:nnn {chemformula} {new-arrow} {#1} } + { + % store type in the sequence and code in the property list + \seq_put_right:Nn \l__chemformula_arrows_type_seq {#1} + \prop_put:Nnn \l__chemformula_arrows_code_prop {#1} {#2} + } + } + +\NewDocumentCommand \DeclareChemArrow {mm} + { + \chemformula_if_is_arrow:nF {#1} + { \seq_put_right:Nn \l__chemformula_arrows_type_seq {#1} } + % store type in the sequence and code in the property list + \prop_put:Nnn \l__chemformula_arrows_code_prop {#1} {#2} + } + +\NewDocumentCommand \RenewChemArrow {mm} + { + \chemformula_if_is_arrow:nTF {#1} + { \prop_put:Nnn \l__chemformula_arrows_code_prop {#1} {#2} } + { \msg_error:nnn {chemformula} {renew-arrow} {#1} } + } + +\NewDocumentCommand \ProvideChemArrow {mm} + { + \chemformula_if_is_arrow:nF {#1} + { + % store type in the sequence and code in the property list + \seq_put_right:Nn \l__chemformula_arrows_type_seq {#1} + \prop_put:Nnn \l__chemformula_arrows_code_prop {#1} {#2} + } + } + +\NewDocumentCommand \ShowChemArrow {m} + { + \chemformula_if_is_arrow:nT {#1} + { + \prop_get:NnN \l__chemformula_arrows_code_prop {#1} + \l__chemformula_tmpa_tl + \tl_to_str:N \l__chemformula_tmpa_tl + } + } + +% declare arrows: +% standard arrows: +\NewChemArrow {->} + { \draw[chemarrow,-cf] (cf_arrow_start) -- (cf_arrow_end) ; } +\NewChemArrow {<-} + { \draw[chemarrow,cf-] (cf_arrow_start) -- (cf_arrow_end) ; } +\NewChemArrow {<->} + { \draw[chemarrow,cf-cf] (cf_arrow_start) -- (cf_arrow_end) ; } +% equilibria: +\NewChemArrow {<=>} + { + \draw[chemarrow,-left~cf] + ([yshift=.15ex]cf_arrow_start) -- ([yshift=.15ex]cf_arrow_end) ; + \draw[chemarrow,left~cf-] + ([yshift=-.15ex]cf_arrow_start) -- ([yshift=-.15ex]cf_arrow_end) ; + } +\NewChemArrow {<=>>} + { + \draw[chemarrow,-left~cf] + ([yshift=.15ex]cf_arrow_start) -- ([yshift=.15ex]cf_arrow_end) ; + \draw[chemarrow,left~cf-] + ([yshift=-.15ex]cf_arrow_mid_start) -- ([yshift=-.15ex]cf_arrow_mid_end) ; + } +\NewChemArrow {<<=>} + { + \draw[chemarrow,-left~cf] + ([yshift=.15ex]cf_arrow_mid_start) -- ([yshift=.15ex]cf_arrow_mid_end) ; + \draw[chemarrow,left~cf-] + ([yshift=-.15ex]cf_arrow_start) -- ([yshift=-.15ex]cf_arrow_end) ; + } +% two arrows: +\NewChemArrow {<>} + { + \draw[chemarrow,-cf] + ([yshift=.2ex]cf_arrow_start) -- ([yshift=.2ex]cf_arrow_end) ; + \draw[chemarrow,cf-,] + ([yshift=-.2ex]cf_arrow_start) -- ([yshift=-.2ex]cf_arrow_end) ; + } +% isolobal arrow: +\NewChemArrow {<o>} + { + \draw[chemarrow,cf-cf] (cf_arrow_start) -- (cf_arrow_end) ; + \draw[chemarrow] + (cf_arrow_mid) .. controls ++(-.9ex,-1.5ex) and + ++(.9ex,-1.5ex) .. (cf_arrow_mid) ; + } +% equilibria upside down: +\NewChemArrow {>>=<} + { + \draw[chemarrow,right~cf-] + ([yshift=.15ex]cf_arrow_start) -- ([yshift=.15ex]cf_arrow_end) ; + \draw[chemarrow,-right~cf] + ([yshift=-.15ex]cf_arrow_mid_start) -- ([yshift=-.15ex]cf_arrow_mid_end) ; + } +\NewChemArrow {>=<<} + { + \draw[chemarrow,right~cf-] + ([yshift=.15ex]cf_arrow_mid_start) -- ([yshift=.15ex]cf_arrow_mid_end) ; + \draw[chemarrow,-right~cf] + ([yshift=-.15ex]cf_arrow_start) -- ([yshift=-.15ex]cf_arrow_end) ; + } +\NewChemArrow {>=<} + { + \draw[chemarrow,right~cf-] + ([yshift=.15ex]cf_arrow_start) -- ([yshift=.15ex]cf_arrow_end) ; + \draw[chemarrow,-right~cf] + ([yshift=-.15ex]cf_arrow_start) -- ([yshift=-.15ex]cf_arrow_end) ; + } +% +\NewChemArrow {<==>} + { + \draw[chemarrow,double~ equal~ sign~ distance,double,Implies-Implies] + (cf_arrow_start) -- (cf_arrow_end) ; + } +% no reaction: +\NewChemArrow {-/>} + { + \draw[chemarrow,-cf] (cf_arrow_start) -- (cf_arrow_end) ; + \draw[chemarrow] (cf_arrow_mid) ++ (.2ex,.4ex) -- ++(-.4ex,-.8ex) ; + \draw[chemarrow] (cf_arrow_mid) ++ (-.2ex,.4ex) -- ++(-.4ex,-.8ex) ; + } +\NewChemArrow {</-} + { + \draw[chemarrow,cf-] (cf_arrow_start) -- (cf_arrow_end) ; + \draw[chemarrow] (cf_arrow_mid) ++ (.2ex,.4ex) -- ++(-.4ex,-.8ex) ; + \draw[chemarrow] (cf_arrow_mid) ++ (.6ex,.4ex) -- ++(-.4ex,-.8ex) ; + } +% net reaction: +\NewChemArrow {==} { \node at ([yshift=-.2ex]cf_arrow_mid) { = } ; } +% quasi equilibria: +\NewChemArrow{<=o>}{ + \draw[chemarrow,-left~cf] + ([yshift=.15ex]cf_arrow_start) -- ([yshift=.15ex]cf_arrow_end) ; + \draw[chemarrow,left~cf-] + ([yshift=-.15ex]cf_arrow_start) -- ([yshift=-.15ex]cf_arrow_end) ; + \draw[chemarrow] (cf_arrow_mid) circle (.4ex) ; +} +\NewChemArrow{<=o>>}{ + \draw[chemarrow,-left~cf] + ([yshift=.15ex]cf_arrow_start) -- ([yshift=.15ex]cf_arrow_end) ; + \draw[chemarrow,left~cf-] + ([yshift=-.15ex]cf_arrow_mid_start) -- ([yshift=-.15ex]cf_arrow_mid_end) ; + \draw[chemarrow] (cf_arrow_mid) circle (.4ex) ; +} +\NewChemArrow{<<=o>}{ + \draw[chemarrow,-left~cf] + ([yshift=.15ex]cf_arrow_mid_start) -- ([yshift=.15ex]cf_arrow_mid_end) ; + \draw[chemarrow,left~cf-] + ([yshift=-.15ex]cf_arrow_start) -- ([yshift=-.15ex]cf_arrow_end) ; + \draw[chemarrow] (cf_arrow_mid) circle (.4ex) ; +} + +% -------------------------------------------------------------------------- +% arrow customization +\keys_define:nn {chemformula} + { + arrow-offset .tl_set:N = \l__chemformula_arrow_offset_tl , + arrow-min-length .dim_set:N = \l__chemformula_arrow_minimum_length_dim , + arrow-yshift .dim_set:N = \l__chemformula_arrow_yshift_dim , + arrow-ratio .tl_set:N = \l__chemformula_arrow_ratio_tl , + label-offset .dim_set:N = \l__chemformula_arrow_label_offset_dim , + compound-sep .tl_set:N = \l__chemformula_compound_sep_tl , + arrow-style .tl_set:N = \l__chemformula_arrow_style_tl , + label-style .tl_set:N = \l__chemformula_arrow_label_style_tl , + arrow-penalty .tl_set:N = \l__chemformula_arrow_penalty_tl , + arrow-style .code:n = \tikzset { chemarrow/.style={#1} } , + } + +% -------------------------------------------------------------------------- +% MAIN COMMAND +\cs_new_protected:Npn \__chemformula_ch_main:n #1 + { + \group_begin: + % abort if `#1' is blank: + \tl_if_blank:nF {#1} + { + \tl_set:Nn \l__chemmacros_tmpa_tl {#1} + \tl_trim_spaces:N \l__chemmacros_tmpa_tl + \seq_set_split:NnV \l__chemformula_input_seq {~} \l__chemmacros_tmpa_tl + % \seq_show:N \l__chemformula_input_seq + % remove empty items in order to avoid unnecessary processing: + \seq_remove_all:Nn \l__chemformula_input_seq {} + % disable \xspace: + \cs_set_eq:NN \xspace \scan_stop: + \bool_set_true:N \l_chemformula_inside_ch_bool + \tl_if_blank:VF \g__chemformula_options_tl + { + \keys_set:nV + {chemformula} + \g__chemformula_options_tl + } + \seq_map_function:NN + \l__chemformula_input_seq + \__chemformula_input:n + \__chemformula_prepare_output:N \l__chemformula_input_tl + \chemformula_write:V \l__chemformula_input_tl + } + \group_end: + } + +\cs_new_protected:Npn \chemformula_write:n #1 + { + \mode_if_math:TF + { \text { \chemformula_font_inner: #1} } + { { \chemformula_font_inner: #1 } } + } +\cs_generate_variant:Nn \chemformula_write:n { V } + +% internal version of \ch command: +\cs_new_protected:Npn \chemformula_ch:nn #1#2 + { + \group_align_safe_begin: + \chemformula_leave_vmode: + \tl_if_blank:nTF {#1} + { \tl_gclear:N \g__chemformula_options_tl } + { \tl_gset:Nn \g__chemformula_options_tl {#1} } + \__chemformula_ch_newline:w #2 \\ \q_no_value \q_stop + \group_align_safe_end: + \tl_use:N \g__chemformula_output_tl +% \tl_show:N \g__chemformula_output_tl + \tl_gclear:N \g__chemformula_output_tl + } +\cs_generate_variant:Nn \chemformula_ch:nn { V , nV , VV } + +% Trickery to use \ch inside align environment: +% bypass \\: +\cs_new_protected:Npn \__chemformula_ch_newline:w #1 \\ #2 \q_stop + { + \__chemformula_ch_align:w #1 & \q_no_value \q_stop + \quark_if_no_value:nF {#2} + { + \tl_gput_right:Nn \g__chemformula_output_tl { \\ } + % look for optional argument: + \peek_meaning:NTF [ + { \__chemformula_ch_newline_skip:w } + { \__chemformula_ch_newline:w } + #2 \q_stop + } + } + +\cs_new_protected:Npn \__chemformula_ch_newline_skip:w [ #1 ] + { + \tl_gput_right:Nn \g__chemformula_output_tl { [#1] } + \__chemformula_ch_newline:w + } + +% bypass &: +\cs_new_protected:Npn \__chemformula_ch_align:w #1 & #2 \q_stop + { + \__chemformula_ch_intertext:w #1 \intertext{} \q_no_value \q_stop + \quark_if_no_value:nF {#2} + { + \tl_gput_right:Nn \g__chemformula_output_tl { & } + \__chemformula_ch_align:w #2 \q_stop + } + } + +% bypass \intertext: +\cs_new_protected:Npn \__chemformula_ch_intertext:w #1 \intertext#2 #3 \q_stop + { + \__chemformula_ch_shortintertext:w #1 \shortintertext{} \q_no_value \q_stop + \quark_if_no_value:nF {#3} + { + \tl_gput_right:Nn \g__chemformula_output_tl { \intertext {#2} } + \__chemformula_ch_intertext:w #3 \q_stop + } + } + +% bypass \shortintertext: +\cs_new_protected:Npn \__chemformula_ch_shortintertext:w #1 \shortintertext#2 #3 \q_stop + { + \tl_gput_right:Nn \g__chemformula_output_tl + { \__chemformula_ch_main:n {#1} } + \quark_if_no_value:nF {#3} + { + \tl_gput_right:Nn \g__chemformula_output_tl { \shortintertext {#2} } + \__chemformula_ch_shortintertext:w #3 \q_stop + } + } + +% -------------------------------------------------------------------------- +% user commands: +\NewDocumentCommand \ch { O{}m } + { \chemformula_ch:nn {#1} {#2} } + +\cs_new_protected:Npn \chemformula_chcpd:nn #1#2 + { + \group_begin: + \tl_if_blank:nF {#2} + { + \keys_set:nn {chemformula} {#1} + \__chemformula_save_catcodes: + \__chemformula_sanitize:Nn + \l__chemformula_chemformula_tmpa_tl + {#2} + \__chemformula_input_compound_no_check:NV + \l__chemformula_compound_tl + \l__chemformula_chemformula_tmpa_tl + \__chemformula_prepare_output:N \l__chemformula_compound_tl + \chemformula_write:V \l__chemformula_compound_tl + } + \group_end: + } + +\NewDocumentCommand \chcpd { O{}m } + { \chemformula_chcpd:nn {#1} {#2} } + +% -------------------------------------------------------------------------- +% arrow generation & detection +\cs_new_protected:Npn \__chemformula_generate_arrows:Nn #1#2 + { + % TODO: is the rescan necessary? Can't we use strings? + \tl_set_rescan:Nnn \l__chemformula_tmpa_tl + { + \char_set_catcode_other:N \> + \char_set_catcode_other:N \< + \char_set_catcode_other:N \- + \char_set_catcode_other:N \= + } + {#2} + \int_zero:N \l__chemformula_tmpa_int + \seq_clear:N \l__chemformula_tmpa_seq + \seq_map_inline:Nn \l__chemformula_arrows_type_seq + { + \tl_if_in:VnT \l__chemformula_tmpa_tl {##1} + { + \int_incr:N \l__chemformula_tmpa_int + \seq_put_right:Nn \l__chemformula_tmpa_seq {##1} + } + } + \int_compare:nTF { \l__chemformula_tmpa_int = 1 } + { + \tl_replace_once:Nxx \l__chemformula_tmpa_tl + { \seq_item:Nn \l__chemformula_tmpa_seq {1} } + { \exp_not:N \charrow { \seq_item:Nn \l__chemformula_tmpa_seq {1} } } + } + { + \int_zero:N \l__chemformula_tmpa_int + \int_zero:N \l__chemformula_tmpb_int + \int_zero:N \l__chemformula_tmpc_int + \seq_map_inline:Nn \l__chemformula_tmpa_seq + { + \int_incr:N \l__chemformula_tmpa_int + \int_compare:nT { \l__chemformula_tmpb_int < \tl_count:n {##1} } + { + \int_set:Nn \l__chemformula_tmpb_int { \tl_count:n {##1} } + \int_set_eq:NN \l__chemformula_tmpc_int \l__chemformula_tmpa_int + } + } + \tl_replace_once:Nxx \l__chemformula_tmpa_tl + { \seq_item:Nn \l__chemformula_tmpa_seq {\l__chemformula_tmpc_int} } + { + \exp_not:N \charrow + { + \seq_item:Nn \l__chemformula_tmpa_seq + { \l__chemformula_tmpc_int } + } + } + } + \tl_set:NV #1 \l__chemformula_tmpa_tl + } +\cs_generate_variant:Nn \__chemformula_generate_arrows:Nn { NV } + +\cs_new_protected:Npn \__chemformula_detect_arrows:n #1 + { + \bool_set_false:N \l__chemformula_is_arrow_bool + \prop_map_inline:Nn \l__chemformula_arrows_code_prop + { + \__chemformula_sanitize:Nn \l__chemformula_tmpa_tl {##1} + \tl_if_in:nVT {#1} \l__chemformula_tmpa_tl + { + \bool_set_true:N \l__chemformula_is_arrow_bool + \prop_map_break: + } + } + } + +% -------------------------------------------------------------------------- +% compound names +\cs_new_protected:Npn \__chemformula_name_compound:w + { \peek_meaning:NTF ( { \chname } { ! } } + +\NewDocumentCommand \chname { R(){}R(){} } + { \chemformula_chwritebelow:nn {#1} {#2} } + +\cs_new_protected:Npn \chemformula_chwritebelow:nn #1#2 + { + % \tl_set:Nn \l_tmpa_tl {#1} \show \l_tmpa_tl + % \tl_set:Nn \l_tmpa_tl {#2} \show \l_tmpa_tl + \c_math_toggle_token + \underset + { + \bool_if:NF \l__chemformula_name_width_bool + { + \chemformula_dim_to_width:Nn \l__chemformula_name_dim + { + \chemformula_group_begin: + \l__chemformula_name_format_tl {#1} + \chemformula_group_end: + } + } + \parbox + { \dim_use:N \l__chemformula_name_dim } + { + \chemformula_group_begin: + \l__chemformula_name_format_tl {#1} + \chemformula_group_end: + } + } + { + \text + { + \chemformula_group_begin: + \strut #2 + \chemformula_group_end: + } + } + \c_math_toggle_token + } + +\cs_new_protected:Npn \__chemformula_generate_name:Nn #1#2 + { + \__chemformula_sanitize:Nn \l__chemformula_tmpa_tl {#2} + \tl_if_in:VnT \l__chemformula_tmpa_tl { ! } + { + \tl_replace_all:Nnn \l__chemformula_tmpa_tl + { ! } + { \__chemformula_name_compound:w } + } + \tl_set:NV #1 \l__chemformula_tmpa_tl + } +\cs_generate_variant:Nn \__chemformula_generate_name:Nn { NV } + +\cs_new_protected:Npn \__chemformula_detect_name:n #1 + { + \bool_set_false:N \l__chemformula_is_name_bool + \tl_set:Nn \l__chemformula_tmpa_tl {#1} + \tl_if_in:VnT \l__chemformula_tmpa_tl { ! } + { \bool_set_true:N \l__chemformula_is_name_bool } + } + +% -------------------------------------------------------------------------- +% parsing input +% compounds: +\cs_new_protected:Npn \chemformula_new_compound_property:nn #1#2 + { + \prop_if_in:NnTF \l__chemformula_compound_prop {#1} + { \msg_error:nnn {chemformula} {new-compound-property} {#1} } + { \prop_put:Nnn \l__chemformula_compound_prop {#1} {#2} } + } + +\cs_new_protected:Npn \chemformula_renew_compound_property:nn #1#2 + { + \prop_if_in:NnTF \l__chemformula_compound_prop {#1} + { \prop_put:Nnn \l__chemformula_compound_prop {#1} {#2} } + { \msg_error:nnn {chemformula} {renew-compound-property} {#1} } + } + +\cs_new_protected:Npn \chemformula_provide_compound_property:nn #1#2 + { \prop_put_if_new:Nnn \l__chemformula_compound_prop {#1} {#2} } + +\cs_new_protected:Npn \chemformula_declare_compound_property:nn #1#2 + { \prop_put:Nnn \l__chemformula_compound_prop {#1} {#2} } + +\cs_new_protected:Npn \chemformula_remove_compound_property:n #1 + { \prop_remove:Nn \l__chemformula_compound_prop {#1} } + +\NewDocumentCommand \NewChemCompoundProperty {mm} + { \chemformula_new_compound_property:nn {#1} {#2} } + +\NewDocumentCommand \RenewChemCompoundProperty {mm} + { \chemformula_renew_compound_property:nn {#1} {#2} } + +\NewDocumentCommand \ProvideChemCompoundProperty {mm} + { \chemformula_provide_compound_property:nn {#1} {#2} } + +\NewDocumentCommand \DeclareChemCompoundProperty {mm} + { \chemformula_declare_compound_property:nn {#1} {#2} } + +\NewDocumentCommand \RemoveChemCompoundProperty {m} + { \chemformula_remove_compound_property:n {#1} } + +\chemformula_new_compound_property:nn { 0 } { \chemformula_subscript:n { 0 } } +\chemformula_new_compound_property:nn { 1 } { \chemformula_subscript:n { 1 } } +\chemformula_new_compound_property:nn { 2 } { \chemformula_subscript:n { 2 } } +\chemformula_new_compound_property:nn { 3 } { \chemformula_subscript:n { 3 } } +\chemformula_new_compound_property:nn { 4 } { \chemformula_subscript:n { 4 } } +\chemformula_new_compound_property:nn { 5 } { \chemformula_subscript:n { 5 } } +\chemformula_new_compound_property:nn { 6 } { \chemformula_subscript:n { 6 } } +\chemformula_new_compound_property:nn { 7 } { \chemformula_subscript:n { 7 } } +\chemformula_new_compound_property:nn { 8 } { \chemformula_subscript:n { 8 } } +\chemformula_new_compound_property:nn { 9 } { \chemformula_subscript:n { 9 } } +\chemformula_new_compound_property:nn { * } { \chemformula_star_adduct: } +\chemformula_new_compound_property:nn { . } { \chemformula_adduct: } +\chemformula_new_compound_property:nn { - } { \chemformula_single_bond: } +\chemformula_new_compound_property:nn { = } { \chemformula_double_bond: } +\chemformula_new_compound_property:nn { + } { \chemformula_triple_bond: } +\chemformula_new_compound_property:nn { ' } { \chemformula_prime: } + +% numbers +\prop_put:Nnn \l__chemformula_numbers_prop { 0 } { 0 } +\prop_put:Nnn \l__chemformula_numbers_prop { 1 } { 1 } +\prop_put:Nnn \l__chemformula_numbers_prop { 2 } { 2 } +\prop_put:Nnn \l__chemformula_numbers_prop { 3 } { 3 } +\prop_put:Nnn \l__chemformula_numbers_prop { 4 } { 4 } +\prop_put:Nnn \l__chemformula_numbers_prop { 5 } { 5 } +\prop_put:Nnn \l__chemformula_numbers_prop { 6 } { 6 } +\prop_put:Nnn \l__chemformula_numbers_prop { 7 } { 7 } +\prop_put:Nnn \l__chemformula_numbers_prop { 8 } { 8 } +\prop_put:Nnn \l__chemformula_numbers_prop { 9 } { 9 } + +% behaviour in a charge +\prop_put:Nnn \l__chemformula_charge_prop { 0 } { \chemformula_charge_style:n { 0 } } +\prop_put:Nnn \l__chemformula_charge_prop { 1 } { \chemformula_charge_style:n { 1 } } +\prop_put:Nnn \l__chemformula_charge_prop { 2 } { \chemformula_charge_style:n { 2 } } +\prop_put:Nnn \l__chemformula_charge_prop { 3 } { \chemformula_charge_style:n { 3 } } +\prop_put:Nnn \l__chemformula_charge_prop { 4 } { \chemformula_charge_style:n { 4 } } +\prop_put:Nnn \l__chemformula_charge_prop { 5 } { \chemformula_charge_style:n { 5 } } +\prop_put:Nnn \l__chemformula_charge_prop { 6 } { \chemformula_charge_style:n { 6 } } +\prop_put:Nnn \l__chemformula_charge_prop { 7 } { \chemformula_charge_style:n { 7 } } +\prop_put:Nnn \l__chemformula_charge_prop { 8 } { \chemformula_charge_style:n { 8 } } +\prop_put:Nnn \l__chemformula_charge_prop { 9 } { \chemformula_charge_style:n { 9 } } +\prop_put:Nnn \l__chemformula_charge_prop { + } { \chemformula_plus: } +\prop_put:Nnn \l__chemformula_charge_prop { - } { \chemformula_minus: } +\prop_put:Nnn \l__chemformula_charge_prop { . } { \chemformula_radical_or_decimal: } +\prop_put:Nnn \l__chemformula_charge_prop { , } { \chemformula_decimal: } + +% stoichiometric factors +\prop_put:Nnn \l__chemformula_stoich_prop { 0 } { 0 } +\prop_put:Nnn \l__chemformula_stoich_prop { 1 } { 1 } +\prop_put:Nnn \l__chemformula_stoich_prop { 2 } { 2 } +\prop_put:Nnn \l__chemformula_stoich_prop { 3 } { 3 } +\prop_put:Nnn \l__chemformula_stoich_prop { 4 } { 4 } +\prop_put:Nnn \l__chemformula_stoich_prop { 5 } { 5 } +\prop_put:Nnn \l__chemformula_stoich_prop { 6 } { 6 } +\prop_put:Nnn \l__chemformula_stoich_prop { 7 } { 7 } +\prop_put:Nnn \l__chemformula_stoich_prop { 8 } { 8 } +\prop_put:Nnn \l__chemformula_stoich_prop { 9 } { 9 } +\prop_put:Nnn \l__chemformula_stoich_prop { . } { \chemformula_decimal: } +\prop_put:Nnn \l__chemformula_stoich_prop { , } { \chemformula_decimal: } +\prop_put:Nnn \l__chemformula_stoich_prop { / } { / } +\prop_put:Nnn \l__chemformula_stoich_prop { _ } { _ } +\prop_put:Nnn \l__chemformula_stoich_prop { ( } { ( } +\prop_put:Nnn \l__chemformula_stoich_prop { ) } { ) } + +\prop_put:Nnn \l__chemformula_no_stoich_prop { . } { } +\prop_put:Nnn \l__chemformula_no_stoich_prop { , } { } +\prop_put:Nnn \l__chemformula_no_stoich_prop { / } { } +\prop_put:Nnn \l__chemformula_no_stoich_prop { _ } { } +\prop_put:Nnn \l__chemformula_no_stoich_prop { ( } { } +\prop_put:Nnn \l__chemformula_no_stoich_prop { ) } { } + +\prop_put:Nnn \l__chemformula_kroegervink_prop { 0 } { \chemformula_charge_style:n { 0 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 1 } { \chemformula_charge_style:n { 1 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 2 } { \chemformula_charge_style:n { 2 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 3 } { \chemformula_charge_style:n { 3 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 4 } { \chemformula_charge_style:n { 4 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 5 } { \chemformula_charge_style:n { 5 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 6 } { \chemformula_charge_style:n { 6 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 7 } { \chemformula_charge_style:n { 7 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 8 } { \chemformula_charge_style:n { 8 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { 9 } { \chemformula_charge_style:n { 9 } } +\prop_put:Nnn \l__chemformula_kroegervink_prop { + } { \chemformula_plus: } +\prop_put:Nnn \l__chemformula_kroegervink_prop { - } { \chemformula_minus: } +\prop_put:Nnn \l__chemformula_kroegervink_prop { . } { \chemformula_radical_or_decimal: } +\prop_put:Nnn \l__chemformula_kroegervink_prop { , } { \chemformula_decimal: } +\prop_put:Nnn \l__chemformula_kroegervink_prop { ' } { \chemformula_kroegervink_negative: } +\prop_put:Nnn \l__chemformula_kroegervink_prop { x } { \chemformula_kroegervink_neutral: } +\prop_put:Nnn \l__chemformula_kroegervink_prop { * } { \chemformula_kroegervink_positive: } +\prop_put:Nnn \l__chemformula_kroegervink_prop { . } { \chemformula_kroegervink_positive: } + +% -------------------------------------------------------------------------- +% bonds: +\cs_new_protected:Npn \chemformula@bondlength + { \l__chemformula_bond_dim } + +\cs_new_protected:Npn \chemformula_single_bond: + { \chemformula_bond:n {single} } + +\cs_new_protected:Npn \chemformula_double_bond: + { \chemformula_bond:n {double} } + +\cs_new_protected:Npn \chemformula_triple_bond: + { \chemformula_bond:n {triple} } + +\cs_new_protected:Npn \chemformula_bond:n #1 + { + \chemformula_skip_nobreak:N \l__chemformula_bond_space_dim + \chemformula_tikz:nn + { + inner~sep = 0pt , + outer~sep = 0pt , + text~height = 1em , + baseline = (chemformula-bond-ground.base) + } + { + \draw node[ draw=none, minimum~height=1em, minimum~width=0 ] + (chemformula-bond-ground) at (0pt,0pt) {}; + \draw (chemformula-bond-ground) ++ (0pt,-.1716em) + coordinate (chemformula-bond-start) ; + \draw (chemformula-bond-start) ++(\l__chemformula_bond_dim ,0pt) + coordinate (chemformula-bond-end) ; + \tl_if_blank:nTF {#1} + { \__chemformula_bond_draw:n {single} } + { \__chemformula_bond_draw:n {#1} } + } + \chemformula_skip_nobreak_penalty:NV + \l__chemformula_bond_space_dim + \l__chemformula_bond_penalty_tl + } + +\cs_new_protected:Npn \__chemformula_bond_draw:n #1 + { + \__chemformula_reset:Nn \l__chemformula_tmpa_tl {#1} + \prop_item:NV \l__chemformula_bonds_prop + \l__chemformula_tmpa_tl + } + +\cs_new_protected:Npn \chemformula_declare_bond:nn #1#2 + { + \cs_if_exist:cTF { chemformula_bond_type_#1: } + { \cs_set:cpn { chemformula_bond_type_#1: } {} } + { \cs_new_protected:cpn { chemformula_bond_type_#1: } {} } + \prop_put:Nnn \l__chemformula_bonds_prop {#1} {#2} + } + +\cs_new_protected:Npn \chemformula_new_bond:nn #1#2 + { + \cs_if_exist:cTF { chemformula_bond_type_#1: } + { \msg_error:nnn {chemformula} {new-bond} {#1} } + { \chemformula_declare_bond:nn {#1} {#2} } + } + +\cs_new_protected:Npn \chemformula_provide_bond:nn #1#2 + { + \cs_if_exist:cF { chemformula_bond_type_#1: } + { \chemformula_declare_bond:nn {#1} {#2} } + } + +\cs_new_protected:Npn \chemformula_renew_bond:nn #1#2 + { + \cs_if_exist:cTF { chemformula_bond_type_#1: } + { \chemformula_declare_bond:nn {#1} {#2} } + { \msg_error:nnn {chemformula} {renew-bond} {#1} } + } + +\cs_new_protected:Npn \chemformula_new_bond_alias:nn #1#2 + { + \cs_if_exist:cTF { chemformula_bond_type_#2: } + { + \cs_if_exist:cTF { chemformula_bond_type_#1: } + { \msg_error:nnn {chemformula} {new-bond} {#1} } + { \cs_new_protected:cpn { chemformula_bond_type_#1: } {} } + \prop_get:NnN \l__chemformula_bonds_prop {#2} \l__chemformula_tmpa_tl + \prop_put:Nno \l__chemformula_bonds_prop {#1} { \l__chemformula_tmpa_tl } + } + { \msg_error:nnnn {chemformula} {bond-alias} {#1} {#2} } + } + +\cs_new_protected:Npn \chemformula_declare_bond_alias:nn #1#2 + { + \cs_if_exist:cTF { chemformula_bond_type_#2: } + { + \cs_if_exist:cF { chemformula_bond_type_#1: } + { \cs_new_protected:cpn { chemformula_bond_type_#1: } {} } + \prop_get:NnN \l__chemformula_bonds_prop {#2} \l__chemformula_tmpa_tl + \prop_put:Nno \l__chemformula_bonds_prop {#1} { \l__chemformula_tmpa_tl } + } + { \msg_error:nnnn {chemformula} {bond-alias} {#1} {#2} } + } + +\cs_new_protected:Npn \chemformula_show_bond:n #1 + { + \prop_get:NnN \l__chemformula_bonds_prop {#1} \l__chemformula_tmpa_tl + \tl_to_str:N \l__chemformula_tmpa_tl + } + +\NewDocumentCommand \NewChemBond {mm} + { \chemformula_new_bond:nn {#1} {#2} } + +\NewDocumentCommand \ProvideChemBond {mm} + { \chemformula_provide_bond:nn {#1} {#2} } + +\NewDocumentCommand \DeclareChemBond {mm} + { \chemformula_declare_bond:nn {#1} {#2} } + +\NewDocumentCommand \RenewChemBond {mm} + { \chemformula_renew_bond:nn {#1} {#2} } + +\NewDocumentCommand \NewChemBondAlias {mm} + { \chemformula_new_bond_alias:nn {#1} {#2} } + +\NewDocumentCommand \DeclareChemBondAlias {mm} + { \chemformula_declare_bond_alias:nn {#1} {#2} } + +\NewDocumentCommand \ShowChemBond {m} + { \chemformula_show_bond:n {#1} } + +\NewDocumentCommand \bond {m} + { \chemformula_bond:n {#1} } + +% now let's declare some default bonds: +\NewChemBond {single} + { \draw[chembond] (chemformula-bond-start) -- (chemformula-bond-end) ; } +\NewChemBondAlias {normal} {single} +\NewChemBondAlias {sb} {single} + +\NewChemBond {semisingle} + { \draw[chembond,densely~dotted] (chemformula-bond-start) -- (chemformula-bond-end) ; } +\NewChemBondAlias {dotted} {semisingle} + +\NewChemBond {double} + { + \foreach \i in {-.0858em,.0858em}{ + \draw[chembond] + ([yshift=\i]chemformula-bond-start) -- ([yshift=\i]chemformula-bond-end) ; + } + } +\NewChemBondAlias {db} {double} + +\NewChemBond {semidouble} + { + \foreach \i/\style in {-.0858em/,.0858em/densely~dotted}{ + \draw[chembond,\style] + ([yshift=\i]chemformula-bond-start) -- ([yshift=\i]chemformula-bond-end) ; + } + } + +\NewChemBondAlias {deloc} {semidouble} + +\NewChemBond {triple} + { + \foreach \i in {-.1287em,0em,.1287em}{ + \draw[chembond] + ([yshift=\i]chemformula-bond-start) -- ([yshift=\i]chemformula-bond-end) ; + } + } +\NewChemBondAlias {tp} {triple} + +\NewChemBond {semitriple} + { + \foreach \i/\style in {-.1287em/,0em/,.1287em/densely~dotted}{ + \draw[chembond,\style] + ([yshift=\i]chemformula-bond-start) -- ([yshift=\i]chemformula-bond-end) ; + } + } +\NewChemBondAlias {tdeloc} {semitriple} + +\NewChemBond {coordright} + { \draw[chembond,Butt~Cap->] (chemformula-bond-start) -- (chemformula-bond-end) ; } +\NewChemBondAlias {co>} {coordright} + +\NewChemBond {coordleft} + { \draw[chembond,<-Butt~Cap] (chemformula-bond-start) -- (chemformula-bond-end) ; } +\NewChemBondAlias {<co} {coordleft} + +% -------------------------------------------------------------------------- +% sub- and superscripts +\cs_new_protected:Npn \__chemformula_number_style:n #1 + { + \bool_if:NTF \l__chemformula_number_style_math_bool + { \ensuremath {#1} } + { \ensuremath { \text {#1} } } + } +\cs_generate_variant:Nn \__chemformula_number_style:n { V } + +\cs_new_protected:Npn \chemformula_charge_style:n #1 + { + \bool_if:NTF \l__chemformula_charge_style_math_bool + { \ensuremath {#1} } + { \ensuremath { \text {#1} } } + } +\cs_generate_variant:Nn \chemformula_charge_style:n { V } + +% subscripts +% remove double or nested sub- and superscripts +\cs_new_protected:Npn \chemformula_subscript:n #1 + { + \chemformula_nobreak: + \tl_if_eq:nnTF {#1} { \chemformula_superscript:n } + { \__chemformula_subscript:n } + { + \tl_if_eq:nnTF {#1} { \chemformula_subscript:n } + { \__chemformula_subscript:n } + { + \tl_set:Nn \l__chemformula_tmpc_tl {#1} + \tl_if_in:nnT {#1} { \chemformula_subscript:n } + { \tl_remove_all:Nn \l__chemformula_tmpc_tl { \chemformula_subscript:n } } + \tl_if_in:nnT {#1} { \chemformula_superscript:n } + { \tl_remove_all:Nn \l__chemformula_tmpc_tl { \chemformula_superscript:n } } + \__chemformula_subscript:V \l__chemformula_tmpc_tl + } + } + } + +% handle subscripts +\cs_new_protected:Npn \__chemformula_subscript:n #1 + { + \tl_put_right:Nn \l__chemformula_subscript_tl {#1} + \__chemformula_clean_subscript: + % if a subscript follows just store and do nothing else + \peek_meaning:NF \chemformula_subscript:n + { + % if a superscript follows store and do nothing else + % if something else follows both sub- and superscript + \peek_meaning:NF \chemformula_superscript:n + { + \__chemformula_measure_subscript:V \l__chemformula_subscript_tl + \__chemformula_measure_superscript:V \l__chemformula_superscript_tl + \__chemformula_use_sub_and_superscript: + } + } + } +\cs_generate_variant:Nn \__chemformula_subscript:n { V } + +% TODO: add hook for cleanup? +% similar to ChemCompoundProperty? +\prop_new:N \l__chemformula_clean_subscript_prop +\seq_new:N \l__chemformula_clean_subscript_seq + +\cs_new_protected:Npn \chemformula_add_subscript_cleanup:nn #1#2 + { + \seq_put_right:Nn \l__chemformula_clean_subscript_seq {#1} + \prop_put:Nnn \l__chemformula_clean_subscript_prop {#1} {#2} + } + +% \NewDocumentCommand \ChemCleanSubscript {mm} +% { \chemformula_add_subscript_cleanup:nn {#1} {#2} } + +\chemformula_add_subscript_cleanup:nn + { \chemformula_single_bond: } + { \chemformula_minus: } +\chemformula_add_subscript_cleanup:nn + { \chemformula_triple_bond: } + { \chemformula_plus: } +\chemformula_add_subscript_cleanup:nn + { \chemformula_adduct: } + { . } +\chemformula_add_subscript_cleanup:nn + { \chemformula_star_adduct: } + { * } + +\cs_new_protected:Npn \__chemformula_clean_subscript: + { + \seq_map_inline:Nn \l__chemformula_clean_subscript_seq + { + \tl_replace_all:Nnx \l__chemformula_subscript_tl + {##1} + { \prop_item:Nn \l__chemformula_clean_subscript_prop {##1} } + } + % \tl_replace_all:Nnn \l__chemformula_subscript_tl + % { \chemformula_single_bond: } { \chemformula_minus: } + % \tl_replace_all:Nnn \l__chemformula_subscript_tl + % { \chemformula_triple_bond: } { \chemformula_plus: } + % \tl_replace_all:Nnn \l__chemformula_subscript_tl + % { \chemformula_adduct: } { . } + % \tl_replace_all:Nnn \l__chemformula_subscript_tl + % { \chemformula_star_adduct: } { * } + } +\cs_generate_variant:Nn \tl_replace_all:Nnn {Nnx} + +\cs_new_protected:Npn \__chemformula_subscript_raise:N #1 + { + \hbox_set:Nn \l__chemformula_tmpa_box + { \c_math_toggle_token \scriptstyle Hg \c_math_toggle_token } + \hbox_set:Nn \l__chemformula_tmpb_box { Hg } + \dim_set:Nn #1 + { + - \box_ht:N \l__chemformula_tmpa_box + + .4 \box_ht:N \l__chemformula_tmpb_box + + \l__chemformula_subscript_shift_additional_tl + } + \chemformula_leave_vmode: + \tex_raise:D #1 + } + +\cs_new_protected:Npn \__chemformula_subscript_write:n #1 + { + \chemformula_nobreak: + \group_begin: + \bool_set_true:N \l__chemformula_inside_subscript_bool + \tl_set_eq:NN \chemformula_subscript:n \use:n + \tl_set_eq:NN \chemformula_superscript:n \use:n + \__chemformula_subscript_raise:N \l__chemformula_subscript_shift_dim + \hbox:n + { + \c_math_toggle_token + \scriptstyle + \prop_get:NoNTF \l__chemformula_numbers_prop + {#1} \l__chemformula_tmpa_tl + { \__chemformula_number_style:V \l__chemformula_tmpa_tl } + { \__chemformula_number_style:n {#1} } + \c_math_toggle_token + } + \group_end: + } +\cs_generate_variant:Nn \__chemformula_subscript_write:n { V } + +\cs_new_protected:Npn \__chemformula_measure_subscript:n #1 + { + \hbox_set:Nn \l__chemformula_tmpa_box + { \__chemformula_subscript_write:n {#1} } + \dim_set:Nn \l__chemformula_subscript_dim + { -\box_wd:N \l__chemformula_tmpa_box } + \box_clear:N \l__chemformula_tmpa_box + } +\cs_generate_variant:Nn \__chemformula_measure_subscript:n { V } + +% superscripts +% remove double or nested sub- and superscripts +\cs_new_protected:Npn \chemformula_superscript:n #1 + { + \chemformula_nobreak: + \tl_if_eq:nnTF {#1} { \chemformula_superscript:n } + { \__chemformula_superscript:n } + { + \tl_if_eq:nnTF {#1} { \chemformula_subscript:n } + { \__chemformula_superscript:n } + { + \tl_set:Nn \l__chemformula_tmpc_tl {#1} + \tl_if_in:nnT {#1} { \chemformula_subscript:n } + { \tl_remove_all:Nn \l__chemformula_tmpc_tl { \chemformula_subscript:n } } + \tl_if_in:nnT {#1} { \chemformula_superscript:n } + { \tl_remove_all:Nn \l__chemformula_tmpc_tl { \chemformula_superscript:n } } + \__chemformula_superscript:V \l__chemformula_tmpc_tl + } + } + } + +% handle superscripts +\cs_new_protected:Npn \__chemformula_superscript:n #1 + { + \tl_put_right:Nn \l__chemformula_superscript_tl {#1} + \__chemformula_clean_superscript: + \peek_meaning:NF \chemformula_superscript:n + { + \peek_meaning:NF \chemformula_subscript:n + { + \__chemformula_measure_subscript:V \l__chemformula_subscript_tl + \__chemformula_measure_superscript:V \l__chemformula_superscript_tl + \__chemformula_use_sub_and_superscript: + } + } + } +\cs_generate_variant:Nn \__chemformula_superscript:n { V } + +% TODO: add hook for cleanup? +% \prop_new:N \l__chemformula_clean_superscript_prop +% \seq_new:N \l__chemformula_clean_superscript_seq + +% \cs_new_protected:Npn \chemformula_add_superscript_cleanup:nnn #1#2#3 +% { +% \seq_put_right:Nn \l__chemformula_clean_superscript_seq {#1} +% \prop_put:Nnn \l__chemformula_clean_superscript_prop {#1} +% { \bool_if:NTF \l__chemformula_kroegervink_bool {#2} {#3} } +% } + +% \chemformula_add_superscript_cleanup:nnn +% { \chemformula_single_bond: } +% { \chemformula_minus: } +% { \chemformula_minus: } +% \chemformula_add_superscript_cleanup:nnn +% { - } +% { \chemformula_minus: } +% { \chemformula_minus: } +% \chemformula_add_superscript_cleanup:nnn +% { \chemformula_triple_bond: } +% { \chemformula_plus: } +% { \chemformula_plus: } +% \chemformula_add_superscript_cleanup:nnn +% { + } +% { \chemformula_plus: } +% { \chemformula_plus: } +% \chemformula_add_superscript_cleanup:nnn +% { . } +% { \chemformula_radical_or_decimal: } +% { \chemformula_kroegervink_positive: } +% \chemformula_add_superscript_cleanup:nnn +% { \chemformula_adduct: } +% { \chemformula_radical_or_decimal: } +% { \chemformula_kroegervink_positive: } +% \chemformula_add_superscript_cleanup:nnn +% { \chemformula_radical_or_decimal: } +% { \chemformula_radical_or_decimal: } +% { \chemformula_kroegervink_positive: } +% \chemformula_add_superscript_cleanup:nnn +% { \chemformula_star_adduct: } +% { * } +% { \chemformula_kroegervink_positive: } +% \chemformula_add_superscript_cleanup:nnn +% { * } +% { * } +% { \chemformula_kroegervink_positive: } +% \chemformula_add_superscript_cleanup:nnn +% { ' } +% { ' } +% { \chemformula_kroegervink_negative: } +% \chemformula_add_superscript_cleanup:nnn +% { \chemformula_prime: } +% { \chemformula_prime: } +% { \chemformula_kroegervink_negative: } +% \chemformula_add_superscript_cleanup:nnn +% { , } +% { \chemformula_decimal: } +% { , } + +% rename this function into treatment instead of cleanup +\cs_new_protected:Npn \__chemformula_clean_superscript: + { + % \seq_map_inline:Nn \l__chemformula_clean_superscript_seq + % { + % \tl_replace_all:Nnx \l__chemformula_superscript_tl + % {##1} + % { \prop_item:Nn \l__chemformula_clean_superscript_prop {##1} } + % } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_single_bond: } { \chemformula_minus: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { - } { \chemformula_minus: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_triple_bond: } { \chemformula_plus: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { + } { \chemformula_plus: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_adduct: } { \chemformula_radical_or_decimal: } + \bool_if:NTF \l__chemformula_kroegervink_bool + { + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { ' } { \chemformula_kroegervink_negative: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_adduct: } { . } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_star_adduct: } { * } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_radical_or_decimal: } { . } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_prime: } { \chemformula_kroegervink_negative: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { * } { \chemformula_kroegervink_positive: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { . } { \chemformula_kroegervink_positive: } + } + { + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { \chemformula_star_adduct: } { * } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { . } { \chemformula_radical_or_decimal: } + \tl_replace_all:Nnn \l__chemformula_superscript_tl + { , } { \chemformula_decimal: } + } + } + +\cs_new_protected:Npn \__chemformula_superscript_raise:N #1 + { + \hbox_set:Nn \l__chemformula_tmpa_box + { \c_math_toggle_token \scriptstyle Hg \c_math_toggle_token } + \hbox_set:Nn \l__chemformula_tmpb_box { Hg } + \dim_set:Nn #1 + { + + \box_ht:N \l__chemformula_tmpb_box + - .5 \box_ht:N \l__chemformula_tmpa_box + + \l__chemformula_superscript_shift_additional_tl + } + \chemformula_leave_vmode: + \tex_raise:D #1 + } + +\cs_new_protected:Npn \__chemformula_superscript_write:n #1 + { + \chemformula_nobreak: + \group_begin: + \bool_set_true:N \l__chemformula_inside_superscript_bool + \tl_set_eq:NN \chemformula_subscript:n \use:n + \tl_set_eq:NN \chemformula_superscript:n \use:n + \__chemformula_superscript_raise:N \l__chemformula_superscript_shift_dim + \hbox:n + { + \c_math_toggle_token + \scriptstyle + % TODO: this is at the wrong place here -- we need to map through + % the superscript tokens! + \bool_if:NTF \l__chemformula_kroegervink_bool + { % TODO: is the o argument necessary? + \prop_get:NoNTF \l__chemformula_kroegervink_prop + {#1} \l__chemformula_tmpa_tl + { \tl_use:N \l__chemformula_tmpa_tl } + { \chemformula_charge_style:n {#1} } + } + { % TODO: is the o argument necessary? + \prop_get:NoNTF \l__chemformula_charge_prop + {#1} \l__chemformula_tmpa_tl + { \tl_use:N \l__chemformula_tmpa_tl } + { \chemformula_charge_style:n {#1} } + } + \c_math_toggle_token + } + \group_end: + } +\cs_generate_variant:Nn \__chemformula_superscript_write:n { V } + +\cs_new_protected:Npn \__chemformula_measure_superscript:n #1 + { + \hbox_set:Nn \l__chemformula_tmpa_box + { \__chemformula_superscript_write:n {#1} } + \dim_set:Nn \l__chemformula_superscript_dim + { -\box_wd:N \l__chemformula_tmpa_box } + \box_clear:N \l__chemformula_tmpa_box + } +\cs_generate_variant:Nn \__chemformula_measure_superscript:n { V } + +% typeset both sub- and superscripts +\cs_new_protected:Npn \__chemformula_use_sub_and_superscript: + { + \group_begin: + % No shift for excited state + \tl_if_eq:VnT \l__chemformula_superscript_tl {*} + { + \bool_set_false:N \l__chemformula_charge_full_shift_bool + \dim_zero:N \l__chemformula_charge_shift_dim + } + % no shift for Kroeger Vink notation + \bool_if:NT \l__chemformula_kroegervink_bool + { + \bool_set_false:N \l__chemformula_charge_full_shift_bool + \dim_zero:N \l__chemformula_charge_shift_dim + } + % align to the right if isotope else to the left + \bool_if:NTF \l__chemformula_is_isotope_bool + { + \tl_if_blank:VF \l__chemformula_superscript_tl + { + \dim_compare:nT + { \l__chemformula_subscript_dim < \l__chemformula_superscript_dim } + { + \chemformula_skip_nobreak:n { -\l__chemformula_subscript_dim } + \chemformula_skip_nobreak:N \l__chemformula_superscript_dim + } + } + } + { + % add hshift to the superscript if there also is a subscript + \tl_if_blank:VF \l__chemformula_superscript_tl + { + \tl_if_blank:VF \l__chemformula_subscript_tl + { + \bool_if:NTF \l__chemformula_charge_full_shift_bool + { \chemformula_skip_nobreak:n { -\l__chemformula_subscript_dim } } + { \chemformula_skip_nobreak:N \l__chemformula_charge_shift_dim } + } + } + } + % typeset superscript + \tl_if_blank:VF \l__chemformula_superscript_tl + { + \__chemformula_superscript_write:V \l__chemformula_superscript_tl + % skip back for the subscript + \tl_if_blank:VF \l__chemformula_subscript_tl + { + \bool_if:NTF \l__chemformula_is_isotope_bool + { \chemformula_skip_nobreak:N \l__chemformula_subscript_dim } + { + \chemformula_skip_nobreak:N \l__chemformula_superscript_dim + \bool_if:NTF \l__chemformula_charge_full_shift_bool + { \chemformula_skip_nobreak:N \l__chemformula_subscript_dim } + { + \chemformula_skip_nobreak:n + { -\l__chemformula_charge_shift_dim } + } + } + } + } + % typeset subscript + \tl_if_blank:VF \l__chemformula_subscript_tl + { \__chemformula_subscript_write:V \l__chemformula_subscript_tl } + \bool_if:NF \l__chemformula_is_isotope_bool + { + \dim_zero:N \l__chemformula_tmpa_dim + \bool_if:NTF \l__chemformula_charge_full_shift_bool + { + \tl_if_blank:VF \l__chemformula_subscript_tl + { \dim_set:Nn \l__chemformula_tmpa_dim + { - \l__chemformula_superscript_dim } } + } + { + \tl_if_blank:VF \l__chemformula_superscript_tl + { + \tl_if_blank:VF \l__chemformula_subscript_tl + { + \dim_set:Nn \l__chemformula_tmpa_dim + { + \l__chemformula_charge_shift_dim + - \l__chemformula_superscript_dim + + \l__chemformula_subscript_dim + } + } + } + } + \dim_compare:nT { \l__chemformula_tmpa_dim > 0pt } + { \chemformula_skip_nobreak:N \l__chemformula_tmpa_dim } + } + \group_end: + % clean up + \bool_set_false:N \l__chemformula_is_isotope_bool + \tl_clear:N \l__chemformula_subscript_tl + \tl_clear:N \l__chemformula_superscript_tl + } + +% -------------------------------------------------------------------------- +% read the input +\cs_new_protected:Npn \__chemformula_input:n #1 + { + \__chemformula_save_catcodes: + \__chemformula_sanitize:Nn \l__chemformula_chemformula_tmpa_tl {#1} + \__chemformula_input_escape_text:V \l__chemformula_chemformula_tmpa_tl + \__chemformula_input_escape_math:n {#1} + \__chemformula_input_stoich:n {#1} + \__chemformula_clean_chemmacros:V \l__chemformula_chemformula_tmpa_tl + \__chemformula_input_compound:NV + \l__chemformula_input_tl + \l__chemformula_chemformula_tmpa_tl + \__chemformula_input_arrow:n {#1} + \__chemformula_input_name:n {#1} + \__chemformula_input_addition:n {#1} + \__chemformula_input_symbol:n {#1} + } + +% -------------------------------------------------------------------------- +% set options for next compound: +\cs_new_protected:Npn \__chemformula_input_options:n #1 + { + % \makeatother + \char_set_catcode_other:N \@ + \tl_set_rescan:Nnn \l__chemformula_tmpa_tl + { \char_set_catcode_letter:N \@ } + {#1} + \tl_if_in:VnTF \l__chemformula_tmpa_tl { @ } + { + \bool_set_true:N \l__chemformula_options_bool + \bool_set_true:N \l__chemformula_is_option_bool + \tl_remove_all:Nn \l__chemformula_tmpa_tl { @ } + \exp_last_unbraced:Nno + \tl_set:Nn \l__chemformula_internal_options_tl + { \l__chemformula_tmpa_tl } + } + { \bool_set_false:N \l__chemformula_is_option_bool } + } + +% -------------------------------------------------------------------------- +% input stoichiometric factors +\cs_new_protected:Npn \chemformula_decimal: { { \l__chemformula_decimal_output_tl } } + +\cs_new_protected:Npn \__chemformula_input_stoich:n #1 + { + \bool_set_true:N \l__chemformula_stoich_bool + % the factor consists only of a parenthesis or a decimal marcer: + \bool_set_true:N \l__chemformula_no_stoich_bool + \tl_map_inline:nn {#1} + { + \prop_if_in:NnF \l__chemformula_no_stoich_prop {##1} + { \bool_set_false:N \l__chemformula_no_stoich_bool } + } + \bool_if:NF \l__chemformula_no_stoich_bool + { + \tl_map_inline:nn {#1} + { + \prop_get:NnNTF \l__chemformula_stoich_prop {##1} \l__chemformula_tmpa_tl + { + \bool_if:NT \l__chemformula_stoich_bool + { \tl_put_right:NV \l__chemformula_stoich_tl \l__chemformula_tmpa_tl } + } + { \bool_set_false:N \l__chemformula_stoich_bool } + } + } + \bool_if:NTF \l__chemformula_stoich_bool + { + \tl_if_blank:VF \l__chemformula_stoich_tl + { + \tl_put_left:Nn \l__chemformula_stoich_tl { \q_mark } + \__chemformula_sanitize:NV + \l__chemformula_stoich_tl + \l__chemformula_stoich_tl + \__chemformula_print_stoich:V + \l__chemformula_stoich_tl + } + } + { \tl_clear:N \l__chemformula_stoich_tl } + } + +\cs_new_protected:Npn \chemformula_bm:n #1 {#1} + +\cs_new_protected:Npn \__chemformula_print_stoich:n #1 + { \chemformula_parse_stoich:n {#1} } +\cs_generate_variant:Nn \__chemformula_print_stoich:n { V } + +\cs_new_protected:Npn \chemformula_parse_stoich:n #1 + { \__chemformula_parse_stoich:w #1 \q_nil } + +\NewDocumentCommand \chstoich {m} + { \chemformula_parse_stoich:n {#1} } + +\cs_new_protected:Npn \__chemformula_parse_stoich:w \q_mark #1 \q_nil + { + \__chemformula_bool_set_if_first_last:Nnnn + \l__chemformula_stoich_is_iupac_bool {#1} { ( } { ) } + \bool_if:NTF \l__chemformula_stoich_is_iupac_bool + { \__chemformula_parse_stoich_iupac:n {#1} } + { \__chemformula_parse_stoich_regular:n {#1} } + } + +\DeclareInstance { xfrac } { chemformula-text-frac } { text } + { + slash-left-kern = -.15em , + numerator-top-sep = 0pt , + slash-right-kern = -.15em + } + +\cs_new_protected:Npn \__chemformula_parse_stoich_regular:n #1 + { + \tl_if_in:nnTF {#1} { / } + { \__chemformula_parse_stoich_frac:n {#1} } + { \__chemformula_parse_stoich_decimal:n {#1} } + } + +\cs_new_protected:Npn \__chemformula_parse_stoich_decimal:n #1 + { + % get head: + \tl_set:Nx \l__chemformula_tmpa_tl { \tl_head:n {#1} } + \tl_set:Nn \l__chemformula_tmpb_tl { \chemformula_decimal: } + % check if stoich starts with decimal-marker and add leading 0 if so: + \tl_if_eq:NNTF \l__chemformula_tmpa_tl \l__chemformula_tmpb_tl + { \tl_put_right:Nn \l__chemformula_input_tl { 0#1 } } + { \tl_put_right:Nn \l__chemformula_input_tl {#1} } + } + +\cs_new_protected:Npn \__chemformula_parse_stoich_frac:n #1 + { + \tl_if_in:nnTF {#1} { _ } + { \__chemformula_parse_stoich_misc_frac:w #1 \q_nil } + { \__chemformula_parse_stoich_frac:w #1 \q_nil } + } + +\cs_new_protected:Npn \__chemformula_parse_stoich_frac:w #1/#2 \q_nil + { + \tl_put_right:Nn \l__chemformula_input_tl + { \__chemformula_frac:nn {#1} {#2} } + } + +\cs_new_protected:Npn \__chemformula_parse_stoich_misc_frac:w #1_#2/#3 \q_nil + { + \tl_put_right:Nn \l__chemformula_input_tl + { \__chemformula_misc_frac:nnn {#1} {#2} {#3} } + } + +\cs_new_protected:Npn \__chemformula_parse_stoich_iupac:n #1 + { + \bool_if:NTF \l__chemformula_stoich_parse_iupac_bool + { \__chemformula_parse_stoich_iupac:w #1 \q_nil } + { \tl_put_right:Nn \l__chemformula_input_tl {#1} } + } + +\cs_new_protected:Npn \__chemformula_parse_stoich_iupac:w (#1) \q_nil + { + \tl_put_right:Nn \l__chemformula_input_tl { ( } + \__chemformula_parse_stoich_regular:n {#1} + \tl_put_right:Nn \l__chemformula_input_tl { ) } + } + +\cs_new_eq:NN \chemformula_math_frac:nn \frac + +\cs_new_protected:Npn \__chemformula_frac:nn #1#2 + { + \bool_if:NT \l__chemformula_xfrac_bool + { \sfrac[chemformula-text-frac]{#1}{#2} } + \bool_if:NT \l__chemformula_nicefrac_bool + { \nicefrac{#1}{#2} } + \bool_if:NT \l__chemformula_mathfrac_bool + { + \c_math_toggle_token + \chemformula_math_frac:nn { \text {#1} } { \text {#2} } + \c_math_toggle_token + } + } + +\cs_new_protected:Npn \__chemformula_misc_frac:nnn #1#2#3 + { + \bool_if:NT \l__chemformula_xfrac_bool + { #1\sfrac[chemformula-text-frac]{#2}{#3} } + \bool_if:NT \l__chemformula_nicefrac_bool + { #1\nicefrac{#2}{#3} } + \bool_if:NT \l__chemformula_mathfrac_bool + { + #1 + \c_math_toggle_token + \chemformula_math_frac:nn { \text {#2} } { \text {#3} } + \c_math_toggle_token + } + } + +% -------------------------------------------------------------------------- +% input compounds +\cs_new_protected:Npn \__chemformula_input_compound:Nn #1#2 + { + % \tl_show:n {#1} + \tl_if_blank:VTF \l__chemformula_stoich_tl + { + % TODO + \__chemformula_detect_addition_symbols:n {#2} + \__chemformula_detect_symbols:n {#2} + \__chemformula_detect_arrows:n {#2} + \__chemformula_detect_name:n {#2} + \__chemformula_input_options:n {#2} + \bool_if:NT \l__chemformula_is_option_bool + { + \tl_put_right:Nn #1 + { + \group_begin: + % open group + \keys_set:nV + {chemformula} + \l__chemformula_internal_options_tl + } + } + \bool_if:nT + { + !\l__chemformula_is_option_bool && + !\l__chemformula_is_addition_symbol_bool && + !\l__chemformula_is_symbol_bool && + !\l__chemformula_is_arrow_bool && + !\l__chemformula_is_name_bool && + !\l__chemformula_first_last_text_bool && + !\l__chemformula_first_last_math_bool + } + { + \__chemformula_input_compound_no_check:Nn #1 {#2} + \bool_if:NT \l__chemformula_options_bool + { + \tl_put_right:Nn #1 + { + % end group + \group_end: + \tl_clear:N \l__chemformula_internal_options_tl + } + \bool_set_false:N \l__chemformula_options_bool + } + } + } + { + \tl_put_right:Nn #1 + { \chemformula_skip_nobreak:N \l__chemformula_stoich_space_skip } + \tl_clear:N \l__chemformula_stoich_tl + } + } +\cs_generate_variant:Nn \__chemformula_input_compound:Nn { NV } + +% TODO: this is redundant at the moment +\bool_new:N \g__chemformula_compound_group_open_bool +\cs_new_protected:Npn \chemformula_group_begin: + { + \bool_if:NF \g__chemformula_compound_group_open_bool + { + % \group_begin: + \bool_gset_true:N \g__chemformula_compound_group_open_bool + } + } +\cs_new_protected:Npn \chemformula_group_end: + { + \bool_if:NT \g__chemformula_compound_group_open_bool + { + % \group_end: + \bool_gset_false:N \g__chemformula_compound_group_open_bool + } + } + +\cs_new_protected:Npn \chemformula_font_inner: + { + \bool_if:NT \l__chemformula_fss_bool + { + \bool_if:NT \l__chemformula_fss_family_bool + { \fontfamily { \l__chemformula_font_family_tl } } + \bool_if:NT \l__chemformula_fss_series_bool + { \fontseries { \l__chemformula_font_series_tl } } + \bool_if:NT \l__chemformula_fss_shape_bool + { \fontshape { \l__chemformula_font_shape_tl } } + \selectfont + } + \bool_if:NT \l__chemformula_fontspec_bool + { \chemformula_font: } + \tl_use:N \l__chemformula_format_tl + \tl_if_eq:onTF { \f@series } {bx} + { \cs_set_eq:NN \chemformula_bm:n \bm } + { \cs_set:Nn \chemformula_bm:n {##1} } + } + +\cs_new_protected:Npn \chemformula_font: {} +\cs_new_protected:Npn \__chemformula_fontspec:n #1 + { + \tl_if_in:nnTF {#1} { [ } + { \__chemformula_fontspec_aux:w #1 \q_stop } + { \__chemformula_fontspec_aux:w [] #1 \q_stop } + } + +\cs_new_protected:Npn \__chemformula_fontspec_aux:w [#1]#2 \q_stop + { \newfontfamily \chemformula_font: [ #1 ] {#2} } + +\cs_new_protected:Npn \__chemformula_save_catcodes: + { + \cs_gset_protected:Npx \__chemformula_restore: + { + \char_set_catcode:nn { 95 } { \char_value_catcode:n { 95 } }% _ + \char_set_catcode:nn { 58 } { \char_value_catcode:n { 58 } }% : + \char_set_catcode:nn { 94 } { \char_value_catcode:n { 94 } }% ^ + \char_set_catcode:nn { 123 } { \char_value_catcode:n { 123 } }% { + \char_set_catcode:nn { 125 } { \char_value_catcode:n { 125 } }% } + \char_set_catcode:nn { 35 } { \char_value_catcode:n { 35 } }% # + \char_set_catcode:nn { 33 } { \char_value_catcode:n { 33 } }% ! + \char_set_catcode:nn { 34 } { \char_value_catcode:n { 34 } }% " + \char_set_catcode:nn { 60 } { \char_value_catcode:n { 60 } }% < + \char_set_catcode:nn { 62 } { \char_value_catcode:n { 62 } }% > + } + } + +\cs_new_protected:Npn \__chemformula_sanitize:Nn #1#2 + { + \tl_set_rescan:Nnn #1 + { + % expl3 catcodes: + \char_set_catcode_letter:N \_ + \char_set_catcode_letter:N \: + % I've forgotten why I put this here: + \char_set_catcode_math_superscript:N \^ + % disable some of the specials (needed for sub- and superscripts): + \char_set_catcode_letter:N \{ + \char_set_catcode_letter:N \} + % this one seems not necessary any more: + % \char_set_catcode_letter:N \\ + \char_set_catcode_letter:N \# + % make the naming work with babel languages like French that make + % ! active: + \char_set_catcode_other:N \! + % make the naming work with babel languages like Spanish that make + % < and > active: + \char_set_catcode_other:N \> + \char_set_catcode_other:N \< + % ensure " is other: + \char_set_catcode_other:N \" + } + {#2} + } +\cs_generate_variant:Nn \__chemformula_sanitize:Nn { NV } + +\cs_new_protected:Npn \__chemformula_prepare_output:N #1 + { + \tl_set_rescan:NnV #1 + { + \__chemformula_restore: + \ExplSyntaxOn + \makeatletter + } + #1 + } + +\cs_new_protected:Npn \__chemformula_reset:Nn #1#2 + { \tl_set_rescan:Nnn #1 { \__chemformula_restore: } {#2} } +\cs_generate_variant:Nn \__chemformula_reset:Nn { NV } + +\prg_new_protected_conditional:Npnn \__chemformula_if_only_parens:n #1 {T,F,TF} + { + \bool_set_true:N \l__chemformula_tmpa_bool + \tl_map_inline:nn {#1} + { + \str_case:nnF {##1} + { + {[} { } + {]} { } + {(} { } + {)} { } + } + { \bool_set_false:N \l__chemformula_tmpa_bool } + } + \bool_if:NTF \l__chemformula_tmpa_bool + { \prg_return_true: } + { \prg_return_false: } + } + +% if the compound starts with a number or a sub- or superscript then it is an +% isotope: +\cs_new_protected:Npn \__chemformula_check_for_isotope:N #1 + { + \tl_if_eq:xnT { \tl_head:V #1 } {^} + { + \tl_put_left:Nn #1 + { \bool_set_true:N \l__chemformula_is_isotope_bool } + } + \tl_if_eq:xnT { \tl_head:V #1 } {_} + { + \tl_put_left:Nn #1 + { \bool_set_true:N \l__chemformula_is_isotope_bool } + } + \prop_if_in:NxT \l__chemformula_numbers_prop + { \tl_head:V #1 } + { + \tl_put_left:Nn #1 + { \bool_set_true:N \l__chemformula_is_isotope_bool } + } + } + +\cs_new_protected:Npn \__chemformula_prepare_sub_and_superscripts:N #1 + { + \tl_if_in:VnT #1 {^} + { \tl_replace_all:Nnn #1 {^} { \chemformula_superscript:n } } + \tl_if_in:VnT #1 {_} + { \tl_replace_all:Nnn #1 {_} { \chemformula_subscript:n } } + } + +% #1: tl that holds compound +% #2: code for each token +\cs_new_protected:Npn \__chemformula_compound_map_inline:Nn #1#2 + { + % ##1: token + % ##2: plus case + % ##3: minus case + % ##4: else case + \cs_set_protected:Npn \__chemformula_if_last_token_charge:nnnF ##1##2##3##4 + { + \int_compare:nTF + { \l__chemformula_count_tokens_int = \tl_count:N #1 } + { + \tl_if_eq:nnTF {##1} {+} + {##2} + { + \tl_if_eq:nnTF {##1} {-} + {##3} + {##4} + } + } + {##4} + } + \int_zero:N \l__chemformula_count_tokens_int + \tl_map_inline:Nn #1 + { + \int_incr:N \l__chemformula_count_tokens_int + % do we end with a charge? + #2 + } + } + +% this is the chemical formula: +% #1: tl var to safe processed formula in +% #2: formula +\cs_new_protected:Npn \__chemformula_input_compound_no_check:Nn #1#2 + { + \__chemformula_if_only_parens:nTF {#2} + { \tl_put_right:Nn #1 {#2} } + { + % start with formatting: + \tl_put_right:Nn #1 + { + \group_begin: + \l__chemformula_atom_format_tl + } + \__chemformula_sanitize:Nn \l__chemformula_tmpa_tl {#2} + % let's see if the compound starts with a sub- or superscript - if yes + % this is an isotope: + \__chemformula_check_for_isotope:N \l__chemformula_tmpa_tl + % preparations for sub- and superscripting: + \__chemformula_prepare_sub_and_superscripts:N \l__chemformula_tmpa_tl + \__chemformula_compound_map_inline:Nn \l__chemformula_tmpa_tl + { + % do we end with a charge? + \__chemformula_if_last_token_charge:nnnF {##1} + { + \tl_put_right:Nn #1 + { \chemformula_superscript:n { \chemformula_plus: } } + } + { + \tl_put_right:Nn #1 + { \chemformula_superscript:n { \chemformula_minus: } } + } + { + \prop_get:NnNTF \l__chemformula_compound_prop + {##1} + \l__chemformula_tmpb_tl + { \tl_put_right:NV #1 \l__chemformula_tmpb_tl } + { \tl_put_right:Nn #1 {##1} } + } + } + % if Kroeger-Vink notation is active: + \bool_if:NT \l__chemformula_kroegervink_bool + { + \tl_replace_all:Nnn #1 + { \chemformula_prime: } + { \chemformula_superscript:n { \chemformula_prime: } } + } + % finish formatting: + \tl_put_right:Nn #1 { \group_end: } + } + \tl_clear:N \l__chemformula_tmpa_tl + } +\cs_generate_variant:Nn \__chemformula_input_compound_no_check:Nn { NV } + +% -------------------------------------------------------------------------- +% clean up chemmacros commands: +\cs_new_protected:Npn \__chemformula_clean_chemmacros:n #1 + { + \cs_set:Nn \chemmacros_text:n + { \mode_if_math:TF { \text {##1} } {##1} } + \cs_set:Npn \chemmacros_xspace: {} + } +\cs_generate_variant:Nn \__chemformula_clean_chemmacros:n { V } + +% -------------------------------------------------------------------------- +% input "and" sign +\prop_new:N \l__chemformula_addition_symbol_prop +\skip_new:N \l__chemformula_additions_symbol_space_skip +\tl_new:N \l__chemformula_additions_symbol_penalty_tl + +\skip_set:Nn \l__chemformula_additions_symbol_space_skip + {.3em plus .1em minus .1em} +\tl_set:Nn \l__chemformula_additions_symbol_penalty_tl {700} + +% #1: name +% #2: input symbol +% #3: output symbol +\cs_new_protected:Npn \chemformula_new_addition_symbol:nnn #1#2#3 + { + \prop_put:Nnn \l__chemformula_addition_symbol_prop {#1} {#2} + \skip_zero_new:c {l__chemformula_#1_space_skip} + \skip_set:cV {l__chemformula_#1_space_skip} + \l__chemformula_additions_symbol_space_skip + \tl_clear_new:c {l__chemformula_#1_penalty_tl} + \tl_set:cV {l__chemformula_#1_penalty_tl} + \l__chemformula_additions_symbol_penalty_tl + \tl_clear_new:c {l__chemformula_#1_output_tl} + \tl_set:cn {l__chemformula_#1_output_tl} {#3} + \keys_define:nn {chemformula} + { + #1-space .skip_set:c = {l__chemformula_#1_space_skip} , + #1-penalty .tl_set:c = {l__chemformula_#1_penalty_tl} , + #1-output-symbol .tl_set:c = {l__chemformula_#1_output_tl} + } + } + +% #1: name +\cs_new_protected:Npn \chemformula_get_addition_symbol:n #1 + { + \chemformula_skip_nobreak:c {l__chemformula_#1_space_skip} + \tl_use:c {l__chemformula_#1_output_tl} + \chemformula_skip_nobreak_penalty:cn + {l__chemformula_#1_space_skip} + { \use:c {l__chemformula_#1_penalty_tl} } + } + +% #1: name +\cs_new_protected:Npn \__chemformula_input_addition:n #1 + { + \prop_map_inline:Nn \l__chemformula_addition_symbol_prop + { + \str_if_eq:nnT {#1} {##2} + { + \tl_put_right:Nn \l__chemformula_input_tl + { \chemformula_get_addition_symbol:n {##1} } + \prop_map_break: + } + } + } + +% #1: input string +\cs_new_protected:Npn \__chemformula_detect_addition_symbols:n #1 + { + \bool_set_false:N \l__chemformula_is_addition_symbol_bool + \chemformula_is_addition_symbol_input:nT {#1} + { \bool_set_true:N \l__chemformula_is_addition_symbol_bool } + } + +\prg_new_protected_conditional:Npnn \chemformula_is_addition_symbol_input:n #1 {T,F,TF} + { + \bool_set_false:N \l__chemformula_tmpa_bool + \prop_map_inline:Nn \l__chemformula_addition_symbol_prop + { + \str_if_eq:nnT {#1} {##2} + { + \bool_set_true:N \l__chemformula_tmpa_bool + \prop_map_break: + } + } + \bool_if:NTF \l__chemformula_tmpa_bool + { \prg_return_true: } + { \prg_return_false: } + } + +\prg_new_conditional:Npnn \chemformula_is_addition_symbol_name:n #1 {T,F,TF} + { + \prop_if_in:NnTF \l__chemformula_addition_symbol_prop {#1} + { \prg_return_true: } + { \prg_return_false: } + } + +\NewDocumentCommand \NewChemAdditionSymbol {mmm} + { + \chemformula_is_addition_symbol_name:nT {#1} + { \msg_error:nnnn {chemformula} {new-addition-symbol} {#1} {#2} } + \chemformula_is_addition_symbol_input:nT {#2} + { \msg_error:nnnn {chemformula} {new-addition-symbol} {#1} {#2} } + \chemformula_new_addition_symbol:nnn {#1} {#2} {#3} + } + +\NewDocumentCommand \ProvideChemAdditionSymbol {mmm} + { + \chemformula_is_addition_symbol_name:nF {#1} + { + \chemformula_is_addition_symbol_input:nF {#2} + { \chemformula_new_addition_symbol:nnn {#1} {#2} {#3} } + } + } + +\NewDocumentCommand \RenewChemAdditionSymbol {mmm} + { + \chemformula_is_addition_symbol_name:nF {#1} + { \msg_error:nnnn {chemformula} {renew-addition-symbol} {#1} {#2} } + \chemformula_is_addition_symbol_input:nF {#2} + { \msg_error:nnnn {chemformula} {renew-addition-symbol} {#1} {#2} } + \chemformula_new_addition_symbol:nnn {#1} {#2} {#3} + } + +\NewDocumentCommand \DeclareChemAdditionSymbol {mmm} + { \chemformula_new_addition_symbol:nnn {#1} {#2} {#3} } + +% default addition symbols: +\NewChemAdditionSymbol {plus} {+} {+} +\NewChemAdditionSymbol {minus} {-} {$-$} + +% -------------------------------------------------------------------------- +% input escaping gas and precipitate +\prop_new:N \l__chemformula_symbols_prop + +\cs_new_protected:Npn \__chemformula_input_symbol:n #1 + { + \prop_map_inline:Nn \l__chemformula_symbols_prop + { + \str_if_eq:nnT {#1} {##1} + { + \tl_put_right:Nn \l__chemformula_input_tl {##2} + \prop_map_break: + } + } + \bool_set_false:N \l__chemformula_is_symbol_bool + } + +\cs_new_protected:Npn \chemformula_new_symbol:nn #1#2 + { \prop_put:Nnn \l__chemformula_symbols_prop {#1} {#2} } + +\cs_new_protected:Npn \__chemformula_detect_symbols:n #1 + { + \bool_set_false:N \l__chemformula_is_symbol_bool + \chemformula_is_symbol:nT {#1} + { \bool_set_true:N \l__chemformula_is_symbol_bool } + } + +\prg_new_conditional:Npnn \chemformula_is_symbol:n #1 {T,F,TF} + { + \prop_if_in:NnTF \l__chemformula_symbols_prop {#1} + { \prg_return_true: } + { \prg_return_false: } + } + +\NewDocumentCommand \NewChemSymbol {mm} + { + \chemformula_is_symbol:nTF {#1} + { \msg_error:nnn {chemformula} {new-symbol} {#1} } + { \chemformula_new_symbol:nn {#1} {#2} } + } + +\NewDocumentCommand \ProvideChemSymbol {mm} + { + \chemformula_is_symbol:nF {#1} + { \chemformula_new_symbol:nn {#1} {#2} } + } + +\NewDocumentCommand \RenewChemSymbol {mm} + { + \chemformula_is_symbol:nTF {#1} + { \chemformula_new_symbol:nn {#1} {#2} } + { \msg_error:nnn {chemformula} {renew-symbol} {#1} } + } + +\NewDocumentCommand \DeclareChemSymbol {mm} + { \chemformula_new_symbol:nn {#1} {#2} } + +\NewChemSymbol {v} {$\downarrow$} +\NewChemSymbol {^} {$\uparrow$} + +% -------------------------------------------------------------------------- +% input arrow +\cs_new_protected:Npn \__chemformula_input_arrow:n #1 + { + \bool_if:nT + { + \l__chemformula_is_arrow_bool && + !\l__chemformula_first_last_text_bool && + !\l__chemformula_first_last_math_bool + } + { + \__chemformula_generate_arrows:Nn \l__chemformula_tmpa_tl {#1} + \tl_put_right:NV \l__chemformula_input_tl \l__chemformula_tmpa_tl + } + \bool_set_false:N \l__chemformula_is_arrow_bool + } +\cs_generate_variant:Nn \__chemformula_input_arrow:n { o,V } + +% -------------------------------------------------------------------------- +% input compound name +\cs_new_protected:Npn \__chemformula_input_name:n #1 + { + \bool_if:nT + { + \l__chemformula_is_name_bool && + !\l__chemformula_first_last_text_bool && + !\l__chemformula_first_last_math_bool + } + { + \__chemformula_generate_name:Nn \l__chemformula_tmpa_tl {#1} + \tl_put_right:NV \l__chemformula_input_tl \l__chemformula_tmpa_tl + } + \bool_set_false:N \l__chemformula_is_name_bool + } + +% -------------------------------------------------------------------------- +% input escaped text +% #1: <bool> #2: <tl> #3: <first> #4: <last> +\cs_new_protected:Npn \__chemformula_bool_set_if_first_last:Nnnn #1#2#3#4 + { + \int_zero:N \l__chemformula_tmpa_int + \int_zero:N \l__chemformula_tmpb_int + \int_set:Nn \l__chemformula_tmpa_int { \tl_count:n {#2} } + \tl_map_inline:nn {#2} + { + \int_incr:N \l__chemformula_tmpb_int + \int_compare:nT { \l__chemformula_tmpb_int = 1 } + { + \tl_if_eq:nnT {##1} {#3} + { \bool_set_true:N #1 } + } + \int_compare:nT { \l__chemformula_tmpb_int = \l__chemformula_tmpa_int } + { + \tl_if_eq:nnF {##1} {#4} + { \bool_set_false:N #1 } + } + } + } + +\cs_new_protected:Npn \__chemformula_input_escape_text:n #1 + { + \__chemformula_first_last_text:n {#1} + \bool_if:NT \l__chemformula_first_last_double_bool + { + \bool_set_true:N \l__chemformula_first_last_text_bool + \__chemformula_read_escape_double:w #1 \q_nil + } + \bool_if:NT \l__chemformula_first_last_single_bool + { + \bool_set_true:N \l__chemformula_first_last_text_bool + \__chemformula_read_escape_single:w #1 \q_nil + } + } +\cs_generate_variant:Nn \__chemformula_input_escape_text:n { V } + +\cs_new_protected:Npn \__chemformula_read_escape_text:n #1 + { + \tl_set_rescan:Nnn \l__chemformula_tmpa_tl + { + \char_set_catcode_letter:N \_ + \char_set_catcode_other:N \: + + } + {#1} + \tl_replace_all:Nnn \l__chemformula_tmpa_tl + { \_ } { chemformulaplaceholder } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl + { _ } { \sb } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl + { chemformulaplaceholder } { \_ } + % those cause trouble with chemmacros' \ox: + % \tl_put_left:Nn \l__chemformula_tmpa_tl + % { \chemformula_group_begin: } + % \tl_put_right:Nn \l__chemformula_tmpa_tl + % { \chemformula_group_end: } + % TODO: waum ist das auskommentiert + % \__chemformula_reset:NV \l__chemformula_tmpa_tl \l__chemformula_tmpa_tl + \tl_put_right:NV \l__chemformula_input_tl \l__chemformula_tmpa_tl + } + +\cs_new_protected:Npn \__chemformula_read_escape_double:w "#1" \q_nil + { \__chemformula_read_escape_text:n {#1} } + +\cs_new_protected:Npn \__chemformula_read_escape_single:w '#1' \q_nil + { \__chemformula_read_escape_text:n {#1} } + +\cs_new_protected:Npn \__chemformula_first_last_text:n #1 + { + \bool_set_false:N \l__chemformula_first_last_double_bool + \bool_set_false:N \l__chemformula_first_last_single_bool + \bool_set_false:N \l__chemformula_first_last_text_bool + \__chemformula_bool_set_if_first_last:Nnnn + \l__chemformula_first_last_double_bool + {#1} + { " } { " } + \bool_if:NF \l__chemformula_first_last_double_bool + { + \__chemformula_bool_set_if_first_last:Nnnn + \l__chemformula_first_last_single_bool + {#1} + { ' } { ' } + } + } + +% -------------------------------------------------------------------------- +% input escaped math +\cs_new_protected:Npn \__chemformula_input_escape_math:n #1 + { + \__chemformula_first_last_math:n {#1} + \bool_if:NT \l__chemformula_first_last_dollar_bool + { + \bool_set_true:N \l__chemformula_first_last_math_bool + \__chemformula_read_escape_dollar:w #1 \q_nil + } + \bool_if:NT \l__chemformula_first_last_mathbraces_bool + { + \bool_set_true:N \l__chemformula_first_last_math_bool + \__chemformula_read_escape_mathbraces:w #1 \q_nil + } + } + +\cs_new_protected:Npn \__chemformula_read_escape_math:n #1 + { + \tl_set_rescan:Nnn \l__chemformula_tmpa_tl + { + \char_set_catcode_letter:N \_ + \char_set_catcode_letter:N \: + } + { \c_math_toggle_token #1 \c_math_toggle_token } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl + { \_ } { chemformulaplaceholder } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl + { _ } { \sb } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl + { chemformulaplaceholder } { \_ } + % \__chemformula_reset:NV \l__chemformula_tmpa_tl \l__chemformula_tmpa_tl + \tl_put_left:Nn \l__chemformula_tmpa_tl + { \chemformula_group_begin: } + \tl_put_right:Nn \l__chemformula_tmpa_tl + { \chemformula_group_end: } + \tl_put_right:NV \l__chemformula_input_tl \l__chemformula_tmpa_tl + \tl_put_right:Nn \l__chemformula_input_tl + { \chemformula_skip_nobreak:N \l__chemformula_math_space_skip } + } + +\cs_new_protected:Npn \__chemformula_read_escape_dollar:w $#1$ \q_nil + { \__chemformula_read_escape_math:n {#1} } + +\cs_new_protected:Npn \__chemformula_read_escape_mathbraces:w \(#1\) \q_nil + { \__chemformula_read_escape_math:n {#1} } + +\cs_new_protected:Npn \__chemformula_first_last_math:n #1 + { + \bool_set_false:N \l__chemformula_first_last_math_bool + \bool_set_false:N \l__chemformula_first_last_dollar_bool + \bool_set_false:N \l__chemformula_first_last_mathbraces_bool + \__chemformula_bool_set_if_first_last:Nnnn + \l__chemformula_first_last_dollar_bool + {#1} + { $ } { $ } + \bool_if:NF \l__chemformula_first_last_dollar_bool + { + \__chemformula_bool_set_if_first_last:Nnnn + \l__chemformula_first_last_mathbraces_bool + {#1} + { \( } { \) } + } + } + +% -------------------------------------------------------------------------- +% customization of output other than arrows +\keys_define:nn {chemformula} + { + circled .choice: , + circled / none .code:n = + { \bool_set_false:N \l_chemformula_formal_charges_bool } , + circled / formal .code:n = + { \bool_set_false:N \l_chemformula_formal_charges_bool } , + circled / all .code:n = + { \bool_set_true:N \l_chemformula_formal_charges_bool } , + circled .default:n = all , + circletype .choice: , + circletype / math .code:n = + { \bool_set_false:N \l_chemformula_formal_chem_bool } , + circletype / chem .code:n = + { \bool_set_true:N \l_chemformula_formal_chem_bool } , + circletype .default:n = chem , + charge-hshift .code:n = + \tl_if_eq:nnTF {#1} { full } + { \bool_set_true:N \l__chemformula_charge_full_shift_bool } + { + \bool_set_false:N \l__chemformula_charge_full_shift_bool + \dim_set:Nn \l__chemformula_charge_shift_dim {#1} + } , + charge-hshift .default:n = .25em , + charge-vshift .tl_set:N = + \l__chemformula_superscript_shift_additional_tl , + charge-style .choice: , + charge-style / text .code:n = + \bool_set_false:N \l__chemformula_charge_style_math_bool , + charge-style / math .code:n = + \bool_set_true:N \l__chemformula_charge_style_math_bool , + subscript-vshift .tl_set:N = + \l__chemformula_subscript_shift_additional_tl , + subscript-vshift .default:n = 0pt , + subscript-style .choice: , + subscript-style / text .code:n = + \bool_set_false:N \l__chemformula_number_style_math_bool , + subscript-style / math .code:n = + \bool_set_true:N \l__chemformula_number_style_math_bool , + decimal-marker .tl_set:N = \l__chemformula_decimal_output_tl , + frac-style .choice: , + frac-style / math .code:n = + \bool_set_false:N \l__chemformula_xfrac_bool + \bool_set_false:N \l__chemformula_nicefrac_bool + \bool_set_true:N \l__chemformula_mathfrac_bool , + frac-style / xfrac .code:n = + \bool_set_true:N \l__chemformula_xfrac_bool + \bool_set_false:N \l__chemformula_nicefrac_bool + \bool_set_false:N \l__chemformula_mathfrac_bool , + frac-style / nicefrac .code:n = + \bool_set_false:N \l__chemformula_xfrac_bool + \bool_set_true:N \l__chemformula_nicefrac_bool + \bool_set_false:N \l__chemformula_mathfrac_bool , + frac-math-cmd .code:n = + { \cs_set_eq:NN \chemformula_math_frac:nn #1 } , + stoich-paren-parse .bool_set:N = \l__chemformula_stoich_parse_iupac_bool , + stoich-space .skip_set:N = \l__chemformula_stoich_space_skip , + stoich-print .code:n = + \cs_set_eq:NN \chemformula_print_stoich:n #1 , + adduct-space .dim_set:N = \l__chemformula_adduct_space_dim , + adduct-penalty .tl_set:N = \l__chemformula_adduct_penalty_tl , + math-space .skip_set:N = \l__chemformula_math_space_skip , + name-format .tl_set:N = \l__chemformula_name_format_tl , + name-width .code:n = + { + \tl_if_eq:nnTF {#1} { auto } + { \bool_set_false:N \l__chemformula_name_width_bool } + { + \bool_set_true:N \l__chemformula_name_width_bool + \dim_set:Nn \l__chemformula_name_dim {#1} + } + } , + bond-length .dim_set:N = \l__chemformula_bond_dim , + bond-offset .dim_set:N = \l__chemformula_bond_space_dim , + bond-style .code:n = + \tikzset { chembond/.style={Butt~Cap-Butt~Cap,#1} } , + bond-penalty .tl_set:N = \l__chemformula_bond_penalty_tl , + font-family .code:n = + \bool_set_true:N \l__chemformula_fss_bool + \bool_set_false:N \l__chemformula_fontspec_bool + \bool_set_true:N \l__chemformula_fss_family_bool + \tl_set:Nn \l__chemformula_font_family_tl {#1} , + font-series .code:n = + \bool_set_true:N \l__chemformula_fss_bool + \bool_set_false:N \l__chemformula_fontspec_bool + \bool_set_true:N \l__chemformula_fss_series_bool + \tl_set:Nn \l__chemformula_font_series_tl {#1} , + font-shape .code:n = + \bool_set_true:N \l__chemformula_fss_bool + \bool_set_false:N \l__chemformula_fontspec_bool + \bool_set_true:N \l__chemformula_fss_shape_bool + \tl_set:Nn \l__chemformula_font_shape_tl {#1} , + font-spec .code:n = + \bool_set_false:N \l__chemformula_fss_bool + \bool_set_true:N \l__chemformula_fontspec_bool + \__chemformula_fontspec:n {#1} , + format .code:n = + \bool_set_false:N \l__chemformula_fss_bool + \bool_set_false:N \l__chemformula_fontspec_bool + \tl_set:Nn \l__chemformula_format_tl {#1} , + atom-format .tl_set:N = \l__chemformula_atom_format_tl + } + +% -------------------------------------------------------------------------- +% \chlewis[opions]{el spec}{atom} + +\keys_define:nn {chemformula} + { + lewis-default .tl_set:N = \l__chemformula_elspec_default_type_tl , + lewis-distance .dim_set:N = \l__chemformula_elspec_pair_distance_dim , + lewis-line-length .dim_set:N = \l__chemformula_elspec_pair_line_length_dim , + lewis-line-width .dim_set:N = \l__chemformula_elspec_pair_width_dim , + lewis-offset .tl_set:N = \l__chemformula_elspec_radius_tl + } + +% #1: options +% #2- el spec +% #3: atom +\cs_new_protected:Npn \chemformula_lewis:nnn #1#2#3 + { + \group_begin: + \keys_set:nn {chemformula} {#1} + \int_gincr:N \g__chemformula_lewis_int + \chemformula_get_lewis_sequence:Nn \l__chemformula_tmpa_seq {#2} + \chemformula_tikz:nn { baseline } + { + \chemformula_node:nxn { anchor=base , inner~sep=0pt } + { chlewis-\int_use:N \g__chemformula_lewis_int } + { + \bool_if:NTF \l_chemformula_inside_ch_bool + {#3} + { \chemformula_chcpd:nn {} {#3} } + } + \seq_map_inline:Nn \l__chemformula_tmpa_seq + { \chemformula_lewis_get_angle_and_spec:n {##1} } + } + \group_end: + } + +\cs_new_protected:Npn \chemformula_get_lewis_sequence:Nn #1#2 + { + \tl_set:Nn \l__chemformula_tmpa_tl {#2} + \tl_replace_all:Nnn \l__chemformula_tmpa_tl { : } { \scan_stop: : , } + \tl_replace_all:NVn \l__chemformula_tmpa_tl \c__chemformula_colon_tl + { \scan_stop: : , } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl { . } { \scan_stop: . , } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl { | } { \scan_stop: | , } + \tl_replace_all:Nnn \l__chemformula_tmpa_tl { o } { \scan_stop: o , } + \seq_set_split:NnV #1 { , } \l__chemformula_tmpa_tl + } + +\cs_new_protected:Npn \chemformula_lewis_get_angle_and_spec:n #1 + { \__chemformula_lewis_get_angle_and_spec:w #1 \scan_stop: \scan_stop: \q_stop } + +\cs_new_protected:Npn + \__chemformula_lewis_get_angle_and_spec:w #1 \scan_stop: #2 \scan_stop: #3 \q_stop + { + \tl_if_blank:nF {#1} + { + \tl_set:Nn \l__chemformula_elspec_angle_tl {#1} + \tl_if_blank:nTF {#2} + { + \tl_set_eq:NN + \l__chemformula_elspec_type_tl + \l__chemformula_elspec_default_type_tl + } + { \tl_set:Nn \l__chemformula_elspec_type_tl {#2} } + \__chemformula_lewis_set_elspec_type:V \l__chemformula_elspec_type_tl + } + } + +\cs_new_protected:Npn \__chemformula_lewis_set_elspec_type:n #1 + { + \prop_get:NnNT \l__chemformula_lewis_elspec_types_prop {#1} + \l__chemformula_tmpa_tl + { \tl_use:N \l__chemformula_tmpa_tl } + } +\cs_generate_variant:Nn \__chemformula_lewis_set_elspec_type:n { V } + +% available types: +\cs_new_protected:Npn \chemformula_declare_lewis_elspec_type:nn #1#2 + { \prop_put:Nnn \l__chemformula_lewis_elspec_types_prop {#1} {#2} } + +\chemformula_declare_lewis_elspec_type:nn + { | } + { \__chemformula_lewis_elspec_pair_line: } + +\chemformula_declare_lewis_elspec_type:nn + { : } + { \__chemformula_lewis_elspec_pair_dots: } + +\chemformula_declare_lewis_elspec_type:nn + { . } + { \__chemformula_lewis_elspec_single: } + +\chemformula_declare_lewis_elspec_type:nn + { o } + { \__chemformula_lewis_elspec_empty: } + +\chemformula_declare_lewis_elspec_type:nn + {pair} + { \__chemformula_lewis_elspec_pair_dots: } + +\chemformula_declare_lewis_elspec_type:nn + {pair~(dotted)} + { \__chemformula_lewis_elspec_pair_dots: } + +\chemformula_declare_lewis_elspec_type:nn + {pair~(line)} + { \__chemformula_lewis_elspec_pair_line: } + +\chemformula_declare_lewis_elspec_type:nn + {single} + { \__chemformula_lewis_elspec_single: } + +\chemformula_declare_lewis_elspec_type:nn + {empty} + { \__chemformula_lewis_elspec_empty: } + +% functions that do the actual drawing: +\cs_new_protected:Npn \__chemformula_lewis_elspec_pair_dots: + { + \chemformula_draw:nn + { + fill, + inner~sep=0pt, + outer~sep=0pt + } + { + (node~cs \c__chemformula_colon_tl + name = chlewis-\int_use:N \g__chemformula_lewis_int , + angle = \l__chemformula_elspec_angle_tl + ) + ++ + ( + \l__chemformula_elspec_angle_tl + \c__chemformula_colon_tl + \l__chemformula_elspec_radius_tl + ) + ++ + ( + \l__chemformula_elspec_angle_tl +90 + \c__chemformula_colon_tl + .5\l__chemformula_elspec_pair_distance_dim + ) + circle (\l__chemformula_radical_radius_dim) + ++ + ( + \l__chemformula_elspec_angle_tl -90 + \c__chemformula_colon_tl + \l__chemformula_elspec_pair_distance_dim + ) + circle (\l__chemformula_radical_radius_dim) + } + } + +\cs_new_protected:Npn \__chemformula_lewis_elspec_pair_line: + { + \chemformula_draw:nn + { line~width = \l__chemformula_elspec_pair_width_dim } + { + (node~cs \c__chemformula_colon_tl + name = chlewis-\int_use:N \g__chemformula_lewis_int , + angle = \l__chemformula_elspec_angle_tl + ) + ++ + ( + \l__chemformula_elspec_angle_tl + \c__chemformula_colon_tl + \l__chemformula_elspec_radius_tl + ) + ++ + ( + \l__chemformula_elspec_angle_tl +90 + \c__chemformula_colon_tl + .5\l__chemformula_elspec_pair_line_length_dim + ) + -- + ++ + ( + \l__chemformula_elspec_angle_tl -90 + \c__chemformula_colon_tl + \l__chemformula_elspec_pair_line_length_dim + ) + } + } + +\cs_new_protected:Npn \__chemformula_lewis_elspec_single: + { + \chemformula_draw:nn + { + fill, + inner~sep=0pt, + outer~sep=0pt + } + { + (node~cs \c__chemformula_colon_tl + name = chlewis-\int_use:N \g__chemformula_lewis_int , + angle = \l__chemformula_elspec_angle_tl + ) + ++ + ( + \l__chemformula_elspec_angle_tl + \c__chemformula_colon_tl + \l__chemformula_elspec_radius_tl + ) + circle (\l__chemformula_radical_radius_dim) + } + } + +\cs_new_protected:Npn \__chemformula_lewis_elspec_empty: + { + \chemformula_draw:nn { } + { + (node~cs \c__chemformula_colon_tl + name = chlewis-\int_use:N \g__chemformula_lewis_int , + angle = \l__chemformula_elspec_angle_tl + ) + ++ + ( + \l__chemformula_elspec_angle_tl + \c__chemformula_colon_tl + \l__chemformula_elspec_radius_tl + ) + ++ + ( + \l__chemformula_elspec_angle_tl +90 + \c__chemformula_colon_tl + .5\l__chemformula_elspec_pair_line_length_dim + ) + coordinate (chlewis-tmp1) + ++ + ( + \l__chemformula_elspec_angle_tl -90 + \c__chemformula_colon_tl + \l__chemformula_elspec_pair_line_length_dim + ) + coordinate (chlewis-tmp2) + ++ + ( + \l__chemformula_elspec_angle_tl + \c__chemformula_colon_tl + .25\l__chemformula_elspec_pair_line_length_dim + ) + coordinate (chlewis-tmp3) + ++ + ( + \l__chemformula_elspec_angle_tl +90 + \c__chemformula_colon_tl + \l__chemformula_elspec_pair_line_length_dim + ) + coordinate (chlewis-tmp4) + (chlewis-tmp1) -- (chlewis-tmp2) -- + (chlewis-tmp3) -- (chlewis-tmp4) -- + cycle + } + } + +\NewDocumentCommand\chlewis{O{}mm} + { \chemformula_lewis:nnn {#1} {#2} {#3} } + +% -------------------------------------------------------------------------- + +\NewDocumentCommand \setchemformula {m} + { \keys_set:nn {chemformula} {#1} } + +\setchemformula{ + bond-style = {} , + arrow-style = {} +} + +% -------------------------------------------------------------------------- +% hyperref support +\AfterPackage* { hyperref } + { + \pdfstringdefDisableCommands + { + \cs_set:Npn \chcpd #1 {#1} + \cs_set:Npn \charrow #1 {#1} + \cs_set:Npn \chname (#1)(#2) { #2~(#1) } + \cs_set:Npn \ch #1 {#1} + \cs_set:Npn \chlewis #1#2 {#2} + } + } + +\tex_endinput:D + +% -------------------------------------------------------------------------- +VERSION HISTORY +2012/01/28 - version 3.0 - bundled with packages `chemmacros' and `ghs' +2012/01/30 - version 3.0a - bugfix + - renamed formula => chemformula + (following a request by Karl Berry for TeXlive) +2012/02/03 - version 3.0b - stepped number with `chemmacros' +2012/02/05 - version 3.0c - stepped number with `chemmacros' +2012/02/10 - version 3.0d - several bugfixes + - new arrow type <> +2012/02/19 - version 3.1 - new arrow types -/>, </- and <o> + - new commands \DeclareChemArrow, \RenewChemArrow and + \ShowChemArrow +2012/02/26 - version 3.1a - stepped number with `chemmacros' +2012/03/03 - version 3.1b - arrow types are stored in a sequence to automate the + search and replace in the right order + - new arrow type == + - IUPAC compliance for stoichiometric factors + - new handling of super- and subscripts to correct + various flaws: clear distinction between isotope and + formula + - new option charge-vshift +2012/03/14 - version 3.1c - improved arrow labels +2012/03/20 - version 3.2 - new: option input via @{<options>} +2012/05/07 - version 3.3 - \ch now bypasses \ref{}, \label{}, and \intertext{} +2012/05/13 - version 3.3a - stepped number with `chemmacros' +2012/05/18 - version 3.3b - stepped number with `chemmacros' +2012/05/18 - version 3.3c - stepped number with `chemmacros' +2012/07/24 - version 3.3d - stepped number with `chemmacros' + - default bond length set to 1.1667ex + - bug fix in the bonds +2012/08/21 - version 3.3e - stepped number with `chemmacros' +2012/09/11 - version 3.4 - cleaned a little, minor bug fixes + - switched to internal scratch variables + - new command \bond, more bond types + - new commands \DeclareChemBond, \DeclareChemBondAlias, + \RenewChemBond and \ShowChemBond + - radical point thicker, new options `radical-style' + and `radical-radius' +2012/10/03 - version 3.4a - stepped number with `chemmacros' +2013/01/04 - version 3.4b - bug fix in the sub- and superscript handling +2013/01/28 - version 3.5 - disallow breaks at bonds + - allow breaks after arrows + - made some spaces in chemformulas stretch- and + shrinkable + - various internal code improvements + - changed defaults for horizontal spaces that have in + set in ex into corresponding values in em. + - improvements to the placement of sub- and superscripts +2013/02/19 - version 3.5a - stepped number with `chemmacros' +2013/02/26 - version 3.6 - support for use with the `breqn' package + - math escaping also via \(\) + - internal: clearer escaping macros + - new options: `radical-vshift', `radical-hshift' + and `radical-space' + - bug fix: `radical-...' options are now correctly set + - stoichiometric factors: add leading 0 if missing + - new option: `stoich-paren-parse' + - internal changes: be way more rigid about protected + and expandable macros + - internal changes: clearer distinction between + private macros and accessable module macros + - internal changes: clearer distinction between + document commands and module level commands + - !()() syntax now also works with babel's French +2013/02/27 - version 3.6a - bug fix: escaped text and math stays escaped, i.e. + also arrow code like `<=>' +2013/04/19 - version 3.6b - new option `arrow-min-length' + - bug fix: stoichiometric fractions correctly displayed +2013/07/06 - version 4.0 - don't need `chemmacros' package any more, + `chemformula' can be used stand-alone; + this has lead to a few definitions that previously + were done by chemmacros; chemmacros will get them + now from chemformula when needed + - bug fix: allow braces in subscripts and superscripts + by disabling superfluous \chemformula_subscript:n + and \chemformula_superscript:n in the scripts write + commands + - remove superfluous rescanning at the begin of the + formula input; this is handled by the sanitize + command later anyway + - changed internal mathshifts from $ ... $ to \( ... \) + - removed superfluous \textstyle from math-frac + definition + - new command \charrow{}[][] that allows direct + access to chemformula's arrows + - new command \chname()() that allows direct access + to chemformula's naming + - new command \chcpd[]{} that allows typesetting a + simple single formula - also not nestable with \ch + - new command \setchemformula + - package option: `strict' + - don't allow a line break before a plus + (`chem-and') + - don't allow a line break between a stoichiometric + factor and a compound + - changed formal charges to match ``plain'' charges +2013/07/26 - version 4.0a - added options `arrow-penalty' (0), `plus-penalty' + (700) and `bond-penalty' (10000) that determine if + there may be a break after an arrow, a bond or the + plus +2013/08/24 - version 4.1 - changed `0' values in TikZ coordinates into `0pt' + see http://tex.stackexchange.com/q/128792/5049 and + http://tex.stackexchange.com/q/118467/5049 for + reference + - new option `tikz-external-disable' + - new option `frac-math-cmd' +2013/10/24 - version 4.2 - \chemformula_font_inner: is only applied /once/ to + a formula, and at the beginning, fixes + https://bitbucket.org/cgnieder/chemmacros/issue/23 + - fixed wrong setting of the TikZ bond style + - new option `arrow-style' + - new command \chlewis +2013/11/04 - version 4.2a - bug fix in \chcpd, + - change sanitizing/restoring of category codes +2014/01/24 - version 4.3 - changed behaviour of \DeclareChem to match + \DeclareRobustCommand, i.e., no check if command + is defined; added a \NewChem variant to each that + /does/ check; use \NewChem instead of \DeclareChem + for definitions + - new option stoich-print + - new command \chstoich +2014/01/29 - version 4.4 - treat a single `-' as a minus sign +2014/04/07 - version 4.5 - make sure that < and > have catcode 12 when read + as parts of arrows + - new arrow types `>=<', `>=<<', `>>=<' and `<==>' + - arrow lengths and compound offset now correctly + adapts to new fontsize if relative lengths (em,ex) + are used + - allow optional arguments to \\ in equation + environments + - allow optional arguments to \label in equation + environments + (credits: http://tex.stackexchange.com/a/166661/5049) + - support for Kröger-Vink notation +2014/06/30 - version 4.6 - fix: a comma in a superscript is typeset according + to `decimal-marker' again + - fix charge type behaviour: option `circled' and + `circletype' are now obeyed if the option is + changed mid-document + - new option `chemformula/circled' similar to + `chemmacros/circled' + - new option `chemformula/circletype' similar to + `chemmacros/circletype' +2014/08/04 - version 4.7 - change dependency: pgf library `arrows.meta' + instead of `arrows' + - new arrow tip definition allows redeclaration to + other existing tips by \pgfkeys{cf/.tip=<tip>} +2014/08/08 - version 4.8 - fix bug introduced in last update: `butt cap' now + needs to be `Butt Cap' with the new `arrows.meta' + library + - split from `chemmacros' bundle as independent + package +2014/10/07 - version 4.9 - new options: `minus-space', `minus-penalty', + `plus-output-symbol' and `minus-output-symbol' +2015/03/16 - version 4.10 - new macros \NewChemCompoundProperty, + \RenewChemCompoundProperty, + \DeclareChemCompoundProperty, + \RemoveChemCompoundProperty +2015/04/03 - version 4.10a - bug fix in \__chemformula_input_stoich:n +2015/06/30 - version 4.11 - small changes in \chcpd + - remove unnecessary \mathchoice => noticable speed + improvement + - \NewChemAdditionSymbol + - \NewChemSymbol +2015/08/12 - version 4.12 - remove chemmacros' `circletype' and `circled' + options. They really belong to chemmacros + - change requirement amsmath -> amstext + - shorten definition of double and triple bonds +2015/08/29 - version 4.12a - \chemformula_formal_plus: , + \chemformula_formal_minus: + \ProvideChem... equivalents to all \NewChem... + macros +2015/09/08 - version 4.12b - trim spaces of \ch input -- due to a change in + l3kernel +2015/01/01 - version 4.13 - clean up code + - check for blank input + - drop support for \[ and \] + - new option `atom-format' +2015/10/21 - version 4.14 - fix issue + https://github.com/cgnieder/chemformula/issues/2 + - new option `adduct-penalty' +2016/01/07 - version 4.14a - \prop_get:Nn => \prop_item:Nn +2016/05/03 - version 4.14b - local options now are correctly working again + - `atom-format' is only applied to formulas +2016/05/11 - version 4.15 - arrow definitions don't have to be made in a + certain order any more + - new quasi equilibria arrows + - bug fix in \RenewChemArrow + - meaningful error if \charrow if used with an + unknown arrow type +2016/06/08 - version 4.15a - change requirement amstext -> amsmath; \chname + uses \underset which needs amsmath +2016/06/08 - version 4.15b - add missing variant of kernel function +2016/08/21 - version 4.15c - corrected redundant definition of + \chemformula_single_bond: + - fix problem with TikZ externalization and + Kroeger-Vink notation +2017/02/02 - version 4.15d - allow `name-format' to end with a macro that + takes an argument +2017/03/23 - version 4.15e - small bug fix (issue #5) + - implement \shortintertext bypass + +% -------------------------------------------------------------------------- +% TODO +- Addukte: Zahlen nach * und . automatisch erkennen? +- make escaped text/math /truely/ escaped, i.e., behave as if it's been input + /outside/ of \ch diff --git a/macros/latex/contrib/chemformula/chemformula_en.pdf b/macros/latex/contrib/chemformula/chemformula_en.pdf Binary files differnew file mode 100644 index 0000000000..f89c0d11e8 --- /dev/null +++ b/macros/latex/contrib/chemformula/chemformula_en.pdf diff --git a/macros/latex/contrib/chemformula/chemformula_en.tex b/macros/latex/contrib/chemformula/chemformula_en.tex new file mode 100644 index 0000000000..0ff1bc0979 --- /dev/null +++ b/macros/latex/contrib/chemformula/chemformula_en.tex @@ -0,0 +1,1765 @@ +% !arara: pdflatex +% !arara: biber +% arara: pdflatex +% arara: pdflatex +% -------------------------------------------------------------------------- +% the CHEMFORMULA package +% +% typeset chemical compounds and reactions +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% -------------------------------------------------------------------------- +% https://github.com/cgnieder/chemformula/ +% contact@mychemistry.eu +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +% Copyright 2011-2017 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +\documentclass[load-preamble+]{cnltx-doc} +\usepackage[utf8]{inputenc} +\usepackage{chemformula} +\usepackage{chemmacros} +\setcnltx{ + package = {chemformula}, + info = {typeset chemical compounds and reactions} , + url = http://www.mychemistry.eu/forums/forum/chemformula/ , + authors = Clemens Niederberger , + email = contact@mychemistry.eu , + abstract = {% + \centering + \includegraphics{chemmacros-logo.pdf} + \par + } , + add-cmds = { + bond, + ce, ch, charrow, chcpd, chemformula@bondlength, chemsetup, chlewis, + chname, + DeclareChemAdditionSymbol, DeclareChemArrow, DeclareChemBond, + DeclareChemBondAlias, DeclareChemCompoundProperty, DeclareChemSymbol, + mch, + NewChemAdditionSymbol, NewChemArrow, NewChemBond, NewChemBondAlias, + NewChemCompoundProperty, NewChemSymbol, + ox, OX, + pch, + redox, RemoveChemCompoundProperty, RenewChemAdditionSymbol, + RenewChemArrow, RenewChemBond, RenewChemCompoundProperty, + RenewChemSymbol, + setchemformula, ShowChemArrow, ShowChemBond + } , + add-silent-cmds = { + addplot, + chemfig, + DeclareInstance, draw, + sample, setatomsep, sfrac, + usetikzlibrary + } , + index-setup = { othercode=\footnotesize, level=\section , noclearpage } , + makeindex-setup = { columns=3, columnsep=1em } +} + +\usepackage{chemfig,booktabs,cancel,varioref} +\usepackage[version=4]{mhchem} + +\expandafter\def\csname libertine@figurestyle\endcsname{LF} +\usepackage[libertine]{newtxmath} +\expandafter\def\csname libertine@figurestyle\endcsname{OsF} + +\chemsetup{ + greek = newtx , + modules = {redox,reactions,units} , + formula = chemformula , + chemformula/format = \libertineLF +} + +\usepackage[biblatex]{embrac} +\ChangeEmph{[}[,.02em]{]}[.055em,-.08em] +\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em] + +\usepackage[accsupp]{acro} +\acsetup{ + long-format = \scshape , + short-format = \scshape +} +\DeclareAcronym{iupac}{ + short = iupac , + long = International Union of Pure and Applied Chemistry , + pdfstring = IUPAC , + accsupp = IUPAC +} + +% \chemsetup{ option/synchronize } +% \setchemformula{ format = \libertineLF } + +\sisetup{ + detect-mode=false, + mode=text, + text-rm=\libertineLF +} + +\usepackage{filecontents} + +\defbibheading{bibliography}{\section{References}} +\addbibresource{\jobname.bib} +\begin{filecontents*}{\jobname.bib} +@book{iupac:greenbook, + author = {E. Richard Cohan and Tomislav Cvita\v{s} and Jeremy G. Frey and + Bertil Holmstr\"om and Kozo Kuchitsu and Roberto Marquardt and Ian Mills and + Franco Pavese and Martin Quack and J\"urgen Stohner and Herbert L. Strauss and + Michio Takami and Anders J Thor} , + title = {``Quantities, Symbols and Units in Physical Chemistry'', \acs{iupac} + Green Book} , + sorttitle = {Quantities, Symbols and Units in Physical Chemistry} , + indexsorttitle = {Quantities, Symbols and Units in Physical Chemistry} , + edition = {3rd Edition. 2nd Printing} , + year = {2008} , + publisher = {\acs{iupac} \&\ RSC Publishing, Cambridge} +} +\end{filecontents*} + +\DeclareInstance{xfrac}{chemformula-text-frac}{text} + { + scale-factor = 1 , + denominator-bot-sep = -.2ex , + denominator-format = \scriptsize #1 , + numerator-top-sep = -.2ex , + numerator-format = \scriptsize #1 , + slash-right-kern = .05em , + slash-left-kern = .05em + } + +\newpackagename\chemmacros{chemmacros} + +\newidxcmd\manual{\textsf{#1}}[\ (manual)] +\newidxcmd\arrowtype{\code{#1}}[\ (arrow type)] + +\makeatletter +\newcommand*\cf@arrow{% + \@ifstar + {\cf@arrow@star} + {\cf@arrow@nostar}% +} +\newrobustcmd*\cf@arrow@star[1]{% + \@ifnextchar[ + {\cf@arrow@star@opt{#1}} + {\cf@arrow@star@opt{#1}[]}% +} +\newrobustcmd*\cf@arrow@nostar[1]{% + \@ifnextchar[ + {\cf@arrow@nostar@opt{#1}} + {\cf@arrow@nostar@opt{#1}[]}% +} +\def\cf@arrow@star@opt#1[#2]{% + \ifblank{#2} + {\item\arrowtype*{#1}} + {\item\arrowtype*{#1}#2}% + \cnltx@checkdefault{\hfill\newline}% +} +\def\cf@arrow@nostar@opt#1[#2]{% + \ifblank{#2} + {\item\arrowtype{#1}} + {\item\arrowtype{#1}#2}% + \cnltx@checkdefault{\hfill\newline}% +} + +\newenvironment{codedesc} + {% + \def\Code##1{\item\code{##1}\hfill\newline}% + \cnltxlist + } + {\endcnltxlist} + +\newenvironment{arrows} + {% + \let\arrow\cf@arrow + \cnltxlist + } + {\endcnltxlist} +\makeatother + +\renewcommand*\AmS{\hologo{AmS}} + +\newcommand*\TikZ{Ti\textit{k}Z} + +\newname\hensel{Martin Hensel} + +\begin{document} + +\section{Introduction} +Probably every chemist using \LaTeXe\ is aware of the great \pkg{mhchem} +package by \hensel. There have always been some difficulties intertwining it +with the \chemmacros\ package, though. Also, some other minor points in +\pkg{mhchem} always bothered me, but they hardly seemed enough for a new +package. They weren't even enough for a feature request to the \pkg{mhchem} +author. The challenge and the fun of creating a new package and the wish for +a highly customizable alternative led to \chemformula\ after all. + +\chemformula\ works very similar to \pkg{mhchem} but is more strict as to how +compounds, stoichiometric factors and arrows are input. In the same time +\chemformula\ offers \emph{many} possibilities to customize the output. + +\section{Licence and Requirements} +\license + +The \chemformula\ package needs and thus loads the packages +\bnd{l3kernel}~\cite{bnd:l3kernel}, \pkg{xparse}, \pkg{l3keys2e} and +\pkg{xfrac} (all three are part of the \bnd{l3packages} +bundle~\cite{bnd:l3packages}), +\pkg{tikz}\footnote{\CTANurl[graphics]{pgf}}~\cite{pkg:pgf}, +\pkg{amstext}~\cite{pkg:amstext}, \pkg{nicefrac}~\cite{pkg:nicefrac} and +\pkg{scrlfile} (from the \KOMAScript\footnote{\CTANurl{koma-script}} +bundle~\cite{bnd:koma-script}). + +\section{Setup} + +If you're using \chemformula\ as a standalone package options are set up with +the following command: +\begin{commands} + \command{setchemformula}[\marg{options}] + Set up \chemformula. +\end{commands} + +\chemformula\ is tightly intertwined with the \chemmacros\ package. If noth +packages are loaded together, \chemformula\ is integrated into the +\chemmacros\ package. Then all of \chemformula's options belong to +\chemmacros' module \module{chemformula}. This means if you load it via +\chemmacros\ or in addition to \chemmacros\ they can be setup with +\begin{commands} + \command{chemsetup}[\Oarg{chemformula}\marg{options}] + Set up options for \chemformula\ exclusively, or + \command{chemsetup}[\Marg{chemformula/\meta{option1},chemformula/\meta{option2}}] + Set up options for \chemformula\ together with others of \chemmacros' + options. +\end{commands} + +\section{The Basic Principle} +\chemformula\ offers one main command. +\begin{commands} + \command{ch}[\oarg{options}\marg{input}] + \chemformula's main command. +\end{commands} +The usage will seem very familiar to you if you're familiar with \pkg{mhchem}: +\begin{example}[side-by-side] + \ch{H2O} \par + \ch{Sb2O3} \par + \ch{H+} \par + \ch{CrO4^2-} \par + \ch{AgCl2-} \par + \ch{[AgCl2]-} \par + \ch{Y^{99}+} \par + \ch{Y^{99+}} \par + \ch{H2_{(aq)}} \par + \ch{NO3-} \par + \ch{(NH4)2S} \par + \ch{^{227}_{90}Th+} \par + $V_{\ch{H2O}}$ \par + \ch{Ce^{IV}} \par + \ch{KCr(SO4)2 * 12 H2O} +\end{example} + +However, there are differences. The most notable one: \chemformula\ +distinguishes between different types of input. These different parts +\emph{have} to be separated with blanks: +\begin{commands} + \command{ch}[\Marg{part1 part2 part3 part4}] +\end{commands} +A blank in the input \emph{never} is a blank in the output. This role of the +blank strictly holds and disregarding it can have unexpected results and even +lead to errors. + +Another notable difference: \chemformula\ tries to avoid math mode whenever +possible: +\begin{example}[side-by-side] + \ch{A + B ->[a] C} \par + \ce{A + B ->[a] C} +\end{example} + +This means that \cs{ch}\Marg{2H2O} is recognized as a \emph{single} part, +which in this case is recognized as a compound. +\begin{example}[side-by-side] + \ch{2H2O} \par + \ch{2 H2O} +\end{example} +This also means, that a part cannot contain a blank since this will +automatically divide it into two parts. If you need an extra blank in the +output you need to use \verbcode+~+. However, since commands in most cases +gobble a space after them a input like \cs{ch}\Marg{\cs*{command} ABC} will be +treated as a single part. If you want or need to divide them you need to add +an empty group: \cs{ch}\Marg{\cs*{command}\marg{} ABC}. The different input +types are described in the following sections. + +% % TODO: Module überdenken, Beschreibung anpassen +% There are some options to customize the output of the \cs{ch} command. They +% can either be applied locally using the optional argument or can be set +% globally using the setup command. All options of \chemformula\ belong to the +% module \module{chemformula} and can be set in different ways: +% \begin{commands} +% \command{chemsetup}[\Oarg{chemformula}\marg{options}] +% when loaded via \chemmacros +% \command{chemsetup}[\Marg{chemformula/\meta{options}}] +% when loaded via \chemmacros +% \command{setchemformula}[\marg{options}] +% independent from \chemmacros +% \end{commands} + +\section{Stoichiometric Factors} +A stoichiometric factor may only contain of numbers and the signs +\verbcode+.,_/()+ +\begin{example}[side-by-side] + \ch{2} \par + \ch{12} + + % decimals: + \ch{.5} \par + \ch{5,75} + + % fractions: + \ch{3/2} \par + \ch{1_1/2} + + % ``iupac'': + \ch{(1/2)} +\end{example} + +As you can see if you input decimal numbers a missing leading zero is added. + +You have to be a little bit careful with the right syntax but I believe it is +rather intuitive. +\begin{sourcecode} + this won't work but will result in an error: \ch{1/1_1} +\end{sourcecode} + +If stoichiometric factors are enclosed with parentheses the fractions are not +recognized and missing leading zeros are not added. What's inside the +parentheses is typeset as is. +\begin{example} + \ch{(1/2) H2O} \ch{1/2 H2O} \ch{0.5 H2O} +\end{example} +You can find many examples like the following for stoichiometric factors in +parentheses in the \acs{iupac} Green Book~\cite{iupac:greenbook}: +\begin{reaction*} + (1/5) K "\ox{7,Mn}" O4 + (8/5) HCl == (1/5) "\ox{2,Mn}" Cl2 + (1/2) Cl2 + (1/5) KCl + (4/5) H2O +\end{reaction*} + +There are a few possibilities to customize the output. +\begin{options} + \keyval{decimal-marker}{marker}\Default{.} + The symbol to indicate the decimal. + \keychoice{frac-style}{math,xfrac,nicefrac}\Default{math} + Determines how fractions are displayed. + \keyval{frac-math-cmd}{command sequence}\Default{\cs*{frac}} + \sinceversion{4.1}Allows you to choose which command is used with + \keyis{frac-style}{math}. This needs to be a command sequence that takes + two arguments that are set in math mode. + \keyval{stoich-space}{skip}\Default{.1667em plus .0333em minus .0117em} + The space that is placed after the stoichiometric factor. A rubber + length. + \keybool{stoich-paren-parse}\Default{false} + If set to true stoichiometric factors enclosed by parentheses also are + parsed. + \keyval{stoich-print}{cs}\Default{\cs{chstoich}} + This option allows to redefine the macro that prints the stoichiometric + factors. \meta{cs} should be a macro that takes one mandatory argument. + \emph{Please note that using this option will disable \chemformula's + stoichiometric parsing as that is done by the default command + \cs{chstoich}.} +\end{options} + +\begin{example} + \ch[decimal-marker={,}]{3.5} \ch[decimal-marker={$\cdot$}]{3,5} +\end{example} + +The option \keyis{frac-style}{xfrac} uses the \cs*{sfrac} command of the +\pkg{xfrac} package. The output strongly depends on the font you use. +\begin{example} + \ch[frac-style=xfrac]{3/2} \ch[frac-style=xfrac]{1_1/2} +\end{example} +\chemformula\ defines the instance \code{chemformula-text-frac} which you can +redefine to your needs. See the \pkg{xfrac} documentation for further +information. The default definition is this: +\begin{sourcecode} + \DeclareInstance{xfrac}{chemformula-text-frac}{text} + { + slash-left-kern = -.15em , + slash-right-kern = -.15em + } +\end{sourcecode} +This document uses the font Linux Libertine~O and the following definition: +\begin{sourcecode} + \DeclareInstance{xfrac}{chemformula-text-frac}{text} + { + scale-factor = 1 , + denominator-bot-sep = -.2ex , + denominator-format = \scriptsize #1 , + numerator-top-sep = -.2ex , + numerator-format = \scriptsize #1 , + slash-right-kern = .05em , + slash-left-kern = .05em + } +\end{sourcecode} + +The option \keyis{frac-style}{nicefrac} uses the \cs*{nicefrac} command of the +\pkg{nicefrac} package. +\begin{example} + \ch[frac-style=nicefrac]{3/2} \ch[frac-style=nicefrac]{1_1/2} +\end{example} + +The option \option{stoich-space} allows you to customize the space between +stoichiometric factor and the group following after it. +\begin{example}[side-by-side] + \ch{2 H2O} \par + \ch[stoich-space=.3em]{2 H2O} +\end{example} + +\section{Compounds}\label{ssec:compounds} +\chemformula\ determines compounds as the type that ``doesn't fit in anywhere +else.'' This point will become more clear when you know what the other types +are. +\begin{example}[side-by-side] + \ch{H2SO4} \par + \ch{[Cu(NH3)4]^2+} +\end{example} + +\subsection{Adducts} +\chemformula\ has two identifiers which will create adducts. +\begin{commands} + \command{ch}[\Marg{A.B}] \ch{A.B} + \command{ch}[\Marg{A*B}] \ch{A*B} +\end{commands} +\begin{example}[side-by-side] + \ch{CaSO4.H2O} \par + \ch{CaSO4*H2O} +\end{example} +Since numbers in a compound always are treated as subscripts (see +section~\ref{ssec:subscripts}) you sometimes need to introduce stoichiometric +factors for the right output: +\begin{example}[side-by-side] + \ch{Na3PO4*12H2O} \par + \ch{Na3PO4* 12 H2O} \par + \ch{Na3PO4 * 12 H2O} +\end{example} + +\subsection{Subscripts}\label{ssec:subscripts} +\emph{All} numbers in a compound are treated as subscripts. +\begin{example}[side-by-side] + \ch{H2SO4} +\end{example} +If you want a letter to be a subscript you can use the math syntax: +\begin{example}[side-by-side] + \ch{A_nB_m} +\end{example} +The subscript recognizes groups. You can also use math inside it. +\begin{example}[side-by-side] + \ch{A_{$n$}B_{$m$}} \par + \ch{NaCl_{(aq)}} +\end{example} + +\subsection{Commands} +Commands are allowed in a compound: +\begin{example}[side-by-side] + \ch{\textbf{A2}B3} \ch{A2\color{red}B3} +\end{example} + +However, if the commands demand numbers as argument, \eg, space commands or +\chemmacros' \verbcode+\ox+ command the direct use will fail. This is +because the numbers are treated as subscripts \emph{before} the command +expands. +\begin{sourcecode} + \ch{A\hspace{2mm}B} will raise an error because \hspace sees something like + this: \hspace{$_2$mm}. Actually not at all like this but equally bad\ldots +\end{sourcecode} +See section~\ref{ssec:text} for a way around this. + +Please also note that formulas are placed inside a group! +\begin{example}[side-by-side] + \ch{A2\color{red}B3 C4} +\end{example} + +\subsection{Charges and Other Superscripts} +\paragraph{Basics} +If a compound \emph{ends} with a plus or minus sign it will be treated as +charge sign and typeset as superscript. In other places a plus is treated as +a triple bond and a dash will be used as a single bond, see +section~\ref{ssec:bonds}. +\begin{example}[side-by-side] + \ch{A+B} \ch{AB+} \par + \ch{A-B} \ch{AB-} +\end{example} + +For longer charge groups or other superscripts you can use the math syntax. +It recognizes groups and you can use math inside them. Inside these groups +neither \code{+} nor \code{-} are treated as bonds. If a dot \code{.} is +inside a superscript it is treated as indicator for a radical. A \code{*} +gives the excited state. +\begin{example}[side-by-side] + \ch{A^{x-}} \par + \ch{A^x-} \par + \ch{A^{x}-} \par + \ch{A^{$x-$}} \par + \ch{RNO2^{-.}} \par + \ch{^31H} \par + \ch{^{14}6C} \par + \ch{^{58}_{26}Fe} \par + \ch{NO^*} +\end{example} + +Actually\changedversion{4.5a} a dot \code{.} is not always treated as +indicator for a radical: if the dot in the superscript is followed by a number +it is interpreted as a decimal sign. It is typeset according to the option +\option{decimal-marker}. This may be a good place to mention that a comma +\code{,} in a superscript is also typeset according to +\option{decimal-marker}. + +\begin{example}[side-by-side] + \ch{^{22,98}_{11}Na} + \ch{^{22.98}_{11}Na}\par + \setchemformula{decimal-marker={,}} + \ch{^{22,98}_{11}Na} + \ch{^{22.98}_{11}Na} +\end{example} + +Ions and ion composites with more than one charge can be typeset quite as +easy: +\begin{example}[side-by-side] + \ch{SO4^2-} \ch{Ca^2+ SO4^2-} +\end{example} + +\paragraph{Charge Commands} +You don't need to use \cs{mch} and related commands inside \cs{ch}. Indeed, +you \emph{shouldn't} use them as they might mess with the subscript and +superscript alignment. The \chemmacros\ option \code{circled} is obeyed by +\cs{ch}. +\begin{example} + \chemsetup[charges]{circled=all} + \ch{H+ + OH- <=> H2O} +\end{example} + +\chemformula\ knows the options \option{circled} and \option{circletype} also +on its own. + +\begin{example} + \setchemformula{circled=all} + \ch{H+ + OH- <=> H2O} +\end{example} + +These options are coupled with \chemmacros\ options, \ie, setting \chemmacros' +options will also set \chemformula's equivalents. The other way around the +options act independently: setting \chemformula's options will \emph{not} set +\chemmacros' options. +\begin{options} + \keychoice{circled}{formal,\default{all},none}\Default{formal} + \chemformula\ uses two different kinds of charges which indicate the usage + of real ($+/-$) and formal (\fplus/\fminus) charges. The choice + \code{formal} distinguishes between them, choice \code{none} displays them + all without circle, choice \code{all} circles all. + % circletype + \keychoice{circletype}{\default{chem},math}\Default{chem} + This option switches between two kinds of circled charge symbols: + \cs{fplus} \fplus\ and \verbcode+$\oplus$+ $\oplus$. +\end{options} + +\paragraph{Behaviour} +The supercripts behave differently depending on their position in a compound, +if there are super- and subscripts following each other directly. +\begin{example} + \ch{^33B} \ch{{}^33B} \ch{3^3B} \ch{B^3} \ch{B3^3} \par + \ch{^{23}_{123}B} \ch{{}^{23}_{123}B} \ch{_{123}^{23}B} + \ch{B^{23}} \ch{B_{123}^{23}} \par + \ch{^{123}_{23}B} \ch{{}^{123}_{23}B} \ch{_{23}^{123}B} + \ch{B^{123}} \ch{B23^{123}} +\end{example} +\begin{itemize} + \item If a compound \emph{starts} with a sub- or superscript both sub- and + superscript are aligned to the \emph{right} else to the \emph{left}. + \item If a compound \emph{does not start} with a sub- or superscript and + there is both a sub- and a superscript, the superscript is shifted + additionally by a length determined from the option + \key{charge-hshift}{dim}, also see page~\pageref{desc:charge-hshift}f. +\end{itemize} +The second point follows \ac{iupac}'s recommendations: +\begin{cnltxquote}[{\acs{iupac} Green Book {\cite[][p.\,51]{iupac:greenbook}}}] + In writing the formula for a complex ion, spacing for charge number can be + added (staggered arrangement), as well as parentheses: + \ch[charge-hshift=full]{SO4^2-}, \ch{(SO4)^2-}. The staggered arrangement + is now recommended. +\end{cnltxquote} + +\subsection{Bonds}\label{ssec:bonds} +\subsubsection{Native Bonds} +There are three kinds of what I will call ``native bonds'': +\begin{example}[side-by-side] + single: \ch{CH3-CH3} \par + double: \ch{CH2=CH2} \par + triple: \ch{CH+CH} +\end{example} + +\subsubsection{Flexible Bonds} +\paragraph{Predefined Bonds} +In addition to the three native bonds there are a few more which can be called +by +\begin{commands} + \command{bond}[\marg{bond name}] + Prints the bond type specified by \meta{bond name}. +\end{commands} +The predefined bond types are shown in table~\vref{tab:bond_types}. + +\begin{table} + \centering + \caption{Bonds available with \cs*{bond}.} + \label{tab:bond_types} + \begin{tabular}{lcl} + \toprule + \bfseries name & \bfseries appearance & \bfseries aliases \\ + \midrule + \code{single} & \bond{single} & \code{normal}, \code{sb} \\ + \code{double} & \bond{double} & \code{db} \\ + \code{triple} & \bond{triple} & \code{tp} \\ + \code{dotted} & \bond{dotted} & \code{semisingle} \\ + \code{deloc} & \bond{deloc} & \code{semidouble} \\ + \code{tdeloc} & \bond{tdeloc} & \code{semitriple} \\ + \code{co>} & \bond{co>} & \code{coordright} \\ + \code{<co} & \bond{<co} & \code{coordleft} \\ + \bottomrule + \end{tabular} +\end{table} + +\begin{example} + \ch{C\bond{sb}C\bond{db}C\bond{tp}C\bond{deloc}C\bond{tdeloc}C\bond{co>}C\bond{<co}C} +\end{example} + +\paragraph{Own Bonds} +\chemformula{} offers commands to define own bond types: +\begin{commands} + \command{NewChemBond}[\marg{name}\marg{code}] + \sinceversion{4.3}Define the new bond type \meta{name}. Issue an error if + a bond \meta{name} already exists. + \command{DeclareChemBond}[\marg{name}\marg{code}] + Define the new bond type \meta{name} or overwrite it if it already + exists. + \command{RenewChemBond}[\marg{name}\marg{code}] + Redefine the existing bond type \meta{name}. Issue an error if a bond + \meta{name} doesn't exist. + \command{ProvideChemBond}[\marg{name}\marg{code}] + \sinceversion{4.12a}Define the new bond type \meta{name} only if it + doesn't exist yet. + \command{NewChemBondAlias}[\marg{new name}\marg{old name}] + \sinceversion{4.3}Declare the bond type \meta{new name} to be an alias of + \meta{old name}. Issue an error if a bond \meta{new name} already + exists. + \command{DeclareChemBondAlias}[\marg{new name}\marg{old name}] + Declare the bond type \meta{new name} to be an alias of \meta{old name}. + \command{ShowChemBond}[\marg{name}] + Print the definition of bond type \meta{name}. +\end{commands} +The usage is best described with an example. So let's see how the +\code{single} bond and the \code{co>} bond are defined: +\begin{sourcecode} + \NewChemBond{single} + { \draw[chembond] (chemformula-bond-start) -- (chemformula-bond-end) ; } + \NewChemBond{coordright} + { + \draw[chembond,butt cap->] + (chemformula-bond-start) -- (chemformula-bond-end) ; + } + \NewChemBondAlias{co>}{coordright} +\end{sourcecode} +Two points are important: the names of the starting and the ending +coordinates, \code{chemformula-bond-start} and \code{chemformula-bond-end}, +and the \TikZ\ style of the bonds \code{chembond}. + +So, let's say you want to define a special kind of dashed bond. You could do +this: +\begin{example} + \usetikzlibrary{decorations.pathreplacing} + \makeatletter + \NewChemBond{dashed} + { + \draw[ + chembond, + decorate, + decoration={ + ticks, + segment length=\chemformula@bondlength/10,amplitude=1.5pt + }] + (chemformula-bond-start) -- (chemformula-bond-end) ; + } + \makeatother + \setchemformula{bond-length=2ex} + \ch{C\bond{dashed}C} +\end{example} + +The last example showed you another macro: \verbcode+\chemformula@bondlength+. +It only exists so you can use it to access the bond length as set with +\option{bond-length} directly. + +\subsection{Customization}\label{ssec:compounds:customization} +These options allow you to customize the ouptut of the compounds: +\begin{options} + \keyval{subscript-vshift}{dim}\Default{0pt} + Extra vertical shift of the subscripts. + \keychoice{subscript-style}{text,math}\Default{text} + Style that is used to typeset the subscripts. + \keyval{charge-hshift}{dim}\Default{.25em} + Shift of superscripts when following a subscript.\label{desc:charge-hshift} + \keyval{charge-vshift}{dim}\Default{0pt} + Extra vertical shift of the superscripts. + \keychoice{charge-style}{text,math}\Default{text} + Style that is used to typeset the superscripts. + \keychoice{circled}{formal,\default{all},none}\Default{formal} + \sinceversion{4.6}Like \chemmacros' package option but local to + \chemformula's \cs{ch}. That is: since \chemmacros' macros use + \chemformula's mechanism this is effectively an alias. + \keychoice{circletype}{\default{chem},math}\Default{chem} + \sinceversion{4.6}Like \chemmacros' package option but local to + \chemformula's \cs{ch}. That is: since \chemmacros' macros use + \chemformula's mechanism this is effectively an alias. + \keyval{adduct-space}{dim}\Default{.1333em} + Space to the left and the right of the adduct point. + \keyval{adduct-penalty}{num}\Default{300} + The\sinceversion{4.14} penalty inserted after the adduct point for + (dis-)allowing line breaks. + \keyval{bond-length}{dim}\Default{.5833em} + The length of the bonds. + \keyval{bond-offset}{dim}\Default{.07em} + Space between bond and atoms. + \keyval{bond-style}{\TikZ}\Default + \TikZ\ options for the bonds. + \keyval{bond-penalty}{num}\Default{10000} + \sinceversion{4.0a}The penalty that is inserted after a bond for + (dis-)allowing line breaks. + \keyval{radical-style}{\TikZ}\Default + \TikZ\ options for the radical point. + \keyval{radical-radius}{dim}\Default{.2ex} + The radius of the radical point. + \keyval{radical-hshift}{dim}\Default{.15em} + Horizontal shift before the radical point is drawn. + \keyval{radical-vshift}{dim}\Default{.5ex} + Vertical shift relative to the current baseline. + \keyval{radical-space}{dim}\Default{.15em} + Horizontal shift after the radical point is drawn. +\end{options} + +Maybe you have noticed that charges of certain ions are shifted to the +right. +\begin{example}[side-by-side] + \ch{SO4^2-} \ch{NH4+} \ch{Na+} +\end{example} +They are shifted if they \emph{follow} a subscript which follows \ac{iupac} +recommendations~\cite[][p.\,51]{iupac:greenbook}. The amount of the shift can +be set with the option \option{charge-hshift}. +\begin{example} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} \par + \setchemformula{charge-hshift=.5ex} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} \par + \setchemformula{charge-hshift=.5pt} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} +\end{example} + +Despite \ac{iupac}'s recommendation \chemformula\ does not make fully staggered +arrangements in the default setting as I find it hard to read in some cases +and ugly in others. Since this is a subjective decision \chemformula\ not only +let's you define the absolute amount of the shift but also provides a +possibility for full staggered arrangements. For this you have to use +\keyis{charge-hshift}{full}. +\begin{example} + \ch[charge-hshift=0pt]{C5H11+} \ch[charge-hshift=0pt]{SO4^2-} \par + \ch{C5H11+} \ch{SO4^2-} \par + \ch[charge-hshift=1ex]{C5H11+} \ch[charge-hshift=1ex]{SO4^2-} \par + \ch[charge-hshift=full]{C5H11+} \ch[charge-hshift=full]{SO4^2-} +\end{example} + +If you don't want the charges to be typeset in text mode you can switch to +math mode: +\begin{example} + \ch{M^x+} \ch{SO4^2-} \par + \setchemformula{charge-style = math} + \ch{M^x+} \ch{SO4^2-} +\end{example} + +The option \option{subscript-vshift} can be used to adjust the vertical shift +of the subscripts: +\begin{example} + \ch{H2SO4} \ch{Na3PO4} \par + \setchemformula{subscript-vshift=.5ex} + \ch{H2SO4} \ch{Na3PO4} \par + \setchemformula{subscript-vshift=-.2ex} + \ch{H2SO4} \ch{Na3PO4} +\end{example} + +You can choose the mode subscripts are typeset in the same way as it is +possible for the charges: +\begin{example} + \ch{A_nB_m} \ch{H2SO4} \par + \setchemformula{subscript-style = math} + \ch{A_nB_m} \ch{H2SO4} +\end{example} + +The option \option{adduct-space} sets the space left and right to the adduct +symbol $\cdot$. +\begin{example} + \ch{Na3PO3*H2O} \par + \setchemformula{adduct-space=.2em} + \ch{Na3PO3*H2O} +\end{example} + +Changing the length of the bonds: +\begin{example} + \setchemformula{bond-length=4mm}% + single: \ch{CH3-CH3} \par + double: \ch{CH2=CH2} \par + triple: \ch{CH+CH} +\end{example} + +You can change the distance between bond and atom, too: +\begin{example} + \ch{H-H + N+N + O=O} \par + \ch[bond-offset=1pt]{H-H + N+N + O=O} +\end{example} + +\subsection{Standalone Formulae} +\chemformula\sinceversion{4.0} offers a command that \emph{only accepts} the +\enquote{compound} input type: +\begin{commands} + \command{chcpd}[\oarg{options}\marg{compound}] + Typeset single compounds. +\end{commands} + +\subsection{Extend Compound Properties}\label{sec:extend-comp-prop} + +It\sinceversion{4.10} is possible to extend the range of special input symbols +within compounds. In the default setting those are \verbcode|*.-=+'| and +arabic numerals. Others can be added or the existing ones be changed with one +of the following commmands: +\begin{commands} + \command{NewChemCompoundProperty}[\marg{token}\marg{replacement}] + \meta{token} will be replaced by \meta{replacement} within compounds. The + property is only added if \meta{token} is not yet part the compounds' + property list. Otherwise an error is issued. + \command{ProvideChemCompoundProperty}[\marg{token}\marg{replacement}] + \meta{token}\sinceversion{4.12a} will be replaced by \meta{replacement} + within compounds. The property is only added if \meta{token} is not yet + part the compounds' property list. + \command{RenewChemCompoundProperty}[\marg{token}\marg{replacement}] + \meta{token} will be replaced by \meta{replacement} within compounds. The + property is only added if \meta{token} is already part the compounds' + property list. Otherwise an error is issued. + \command{DeclareChemCompoundProperty}[\marg{token}\marg{replacement}] + \meta{token} will be replaced by \meta{replacement} within compounds. The + property silently overwrites any previously set \meta{replacement} for + \meta{token} if \meta{token} is already part the compounds' property + list. + \command{RemoveChemCompoundProperty}[\marg{token}] + Removes \meta{token} from the compounds' property list. +\end{commands} + +For example you can use +\begin{sourcecode} + \NewChemCompoundProperty{\}{\slash} +\end{sourcecode} +to allow line breaks after slashes in compounds. + +\section{Special Input Types} +There are some \enquote{special type} input groups. + +\subsection{Single Token Groups} +The first kind are groups which consist of only one token. They are again +divided into two groups, \enquote{addition symbols} and \enquote{symbols}. + +\subsubsection{Addition Symbols}\label{sec:addition-symbols} +\begin{commands} + \command{ch}[\Marg{ + } \ch{ + }] + Creates the plus sign between compounds with space around it:\\ + \cs{ch}\Marg{2 Na + Cl2} \ch{2 Na + Cl2} + \command{ch}[\Marg{ - } \ch{ - }] + \sinceversion{4.3a}Creates the minus sign between compounds with space + around it:\\ + \cs{ch}\Marg{M - H} \ch{M - H} +\end{commands} +Addition symbols are surrounded with space which can be customized according +to options explained in a bit. There is also some penalty prohibiting a line +break after them which also can be customized with an option. + +You can define/redefine your own addition symbols: +\begin{commands} + \command{NewChemAdditionSymbol}[\marg{name}\marg{input}\marg{output}] + Defines\sinceversion{4.11} the addition symbol \meta{name} with input + symbol \meta{input} and output \meta{output}. + \command{ProvideChemAdditionSymbol}[\marg{name}\marg{input}\marg{output}] + Defines\sinceversion{4.12a} the addition symbol \meta{name} with input + symbol \meta{input} and output \meta{output} only no addition symbol with + then name \meta{name} doesn't exist. + \command{RenewChemAdditionSymbol}[\marg{name}\marg{input}\marg{output}] + Redefines\sinceversion{4.11} the addition symbol \meta{name} with input + symbol \meta{input} and output \meta{output}. + \command{DeclareChemAdditionSymbol}[\marg{name}\marg{input}\marg{output}] + (Re-)Defines\sinceversion{4.11} the addition symbol \meta{name} with input + symbol \meta{input} and output \meta{output} without checking if the + symbol exists or not. +\end{commands} + +The space left and right of the plus and the minus sign and the signs +themselves can be set with the following options: +\begin{options} + \keyval{plus-space}{skip}\Default{.3em plus .1em minus .1em} + A rubber length. + \keyval{plus-penalty}{num}\Default{700} + \sinceversion{4.0a}The penalty that is inserted after the plus sign for + (dis-)allowing line breaks. + \keyval{plus-output-symbol}{code}\Default{+} + \sinceversion{4.9}The \meta{code} that is used for the plus sign. + \keyval{minus-space}{skip}\Default{.3em plus .1em minus .1em} + \sinceversion{4.9}A rubber length. + \keyval{minus-penalty}{num}\Default{700} + \sinceversion{4.9}The penalty that is inserted after the minus sign for + (dis-)allowing line breaks. + \keyval{minus-output-symbol}{code}\Default{\$-\$} + \sinceversion{4.9}The \meta{code} that is used for the minus sign. +\end{options} +The corresponding three options are defined when \cs{NewChemAdditionSymbol} +or one of the variants is used, \code{\meta{name}-space} and +\code{\meta{name}-penalty} both with the same defaults as above, and +\code{\meta{name}-output-symbol}. + +\begin{example}[side-by-side] + \ch{A + B}\par + \ch[plus-space=4pt]{A + B} +\end{example} + +\subsubsection{Symbols}\label{sec:symbols} +\begin{commands} + \command{ch}[\Marg{ v } \ch{ v }] + Sign for precipitate: \cs{ch}\Marg{BaSO4 v} \ch{BaSO4 v} + \command{ch}[\Marg{ \textasciicircum\ } \ch{ ^ }] + Sign for escaping gas\footnotemark: \cs{ch}\Marg{H2 \textasciicircum} + \ch{H2 ^} +\end{commands} +\footnotetext{Is this the correct English term? Please correct me if it isn't.} + +You can define/redefine your own symbols: +\begin{commands} + \command{NewChemSymbol}[\marg{input}\marg{output}] + Defines\sinceversion{4.11} the addition symbol with input \meta{input} and + output \meta{output}. + \command{ProvideChemSymbol}[\marg{input}\marg{output}] + Defines\sinceversion{4.12a} the addition symbol with input \meta{input} and + output \meta{output} only if no symbol with input \meta{input} exists. + \command{RenewChemSymbol}[\marg{input}\marg{output}] + Redefines\sinceversion{4.11} the addition symbol with input \meta{input} + and output \meta{output}. + \command{DeclareChemSymbol}[\marg{input}\marg{output}] + (Re-)Defines\sinceversion{4.11} the addition symbol with input + \meta{input} and output \meta{output} without checking if the symbol + exists or not. +\end{commands} + +\subsection{Option Input} +Sometimes you might want to apply an option only to a part of a, say, +reaction. Of course you have the possibility to use \cs{ch} several times. +\begin{example} + \ch{H2O +}\textcolor{red}{\ch{H2SO4}}\ch{-> H3O+ + HSO4-} \par + \ch{H2O +}\ch[subscript-vshift=2pt]{H2SO4}\ch{-> H3O+ + HSO4-} +\end{example} +This, however, interrupts the input in your source and \emph{may} mess with +the spacing. That's why there is an alternative: +\begin{commands} + \command{ch}[\Marg{ @\marg{options} }] + The options specified this way will be valid \emph{only} until the next + compound is set. +\end{commands} +\begin{example} + \ch{H2O +}\textcolor{red}{\ch{H2SO4}}\ch{-> H3O+ + HSO4-} \par + \ch{H2O + @{format=\color{red}} H2SO4 -> H3O+ + HSO4-} \par + or of course:\par + \ch{H2O + \textcolor{red}{H2SO4} -> H3O+ + HSO4-}\par\bigskip + \ch{H2O +}\ch[subscript-vshift=2pt]{H2SO4}\ch{-> H3O+ + HSO4-} \par + \ch{H2O + @{subscript-vshift=2pt} H2SO4 -> H3O+ + HSO4-} +\end{example} + +\section{Escaped Input} +In some cases it may be desirable to prevent \chemformula\ from parsing the +input. This can be done in two ways. + +\subsection{Text}\label{ssec:text} +If you put something between \verbcode+" "+ or \verbcode+' '+ then the input +will be treated as normal text, except that spaces are not allowed and have to +be input with \verbcode+~+. +\begin{commands} + \command{ch}[\Marg{ "\meta{escaped text}" }] + One of two possibilities to \emph{escape} \chemformula's parsing. + \command{ch}[\Marg{ \textquotesingle\meta{escaped text}\textquotesingle\ }] + The second of two possibilities to \emph{escape} \chemformula's parsing. +\end{commands} +\begin{example}[add-sourcecode-options={literate=}] + \ch{"\ox{2,Ca}" O} \par + \ch{"\ldots\," Na + "\ldots\," Cl2 -> "\ldots\," NaCl} \par + \ch{'A~->~B'} +\end{example} +In many cases you won't need to escape the input. But when you get into +trouble when using a command inside \cs{ch} try hiding it. + +\subsection{Math} +If you especially want to input math you just enclose it with \verbcode+$ $+. +This output is different from the escaped text as it is followed by a space. +The reasoning behind this is that I assume math will mostly be used to replace +stoichiometric factors. +\begin{commands} + \command{ch}[\Marg{ \string$\meta{escaped math}\string$ }] + One of two possibilities to \emph{escape} \chemformula's parsing into math + mode. + \command{ch}[\Marg{ \string\(\meta{escaped math}\string\) }] + The second of two possibilities to \emph{escape} \chemformula's parsing + into math mode. +\end{commands} +\begin{example}[side-by-side] + escaped text: \ch{"$x$" H2O} \par + escaped math: \ch{$x$ H2O} \par + also escaped math: \ch{\(x\) H2O} \par + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} +\end{example} + +The space that is inserted after a math group can be edited: +\begin{options} + \keyval{math-space}{skip}\Default{.1667em plus .0333em minus .0117em} + A rubber length. +\end{options} +\begin{example} + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} \par + \setchemformula{math-space=.25em} + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} \par + \ch{$A->B$} +\end{example} + +\section{Arrows}\label{sec:arrows} +\subsection{Arrow types} +Arrows are input in the same intuitive way they are with \pkg{mhchem}. +There are various different types: +\begin{arrows} + \arrow{->}[ \charrow{->}] + standard right arrow + \arrow{<-}[ \charrow{<-}] + standard left arrow + \arrow{-/>}[ \charrow{-/>}] + does not react (right) + \arrow{</-}[ \charrow{</-}] + does not react (left) + \arrow{<->}[ \charrow{<->}] + resonance arrow + \arrow{<>}[ \charrow{<>}] + reaction in both directions + \arrow{==}[ \charrow{==}] + stoichiometric equation + \arrow{<=>}[ \charrow{<=>}] + equilibrium arrow + \arrow{>=<}[ \charrow{>=<}] + \sinceversion{4.5}reversed equilibrium arrow + \arrow{<=>{}>}[ \charrow{<=>>}] + unbalanced equilibrium arrow to the right + \arrow{>=<{}<}[ \charrow{>=<<}] + \sinceversion{4.5}reversed unbalanced equilibrium arrow to the right + \arrow{<{}<=>}[ \charrow{<<=>}] + unbalanced equilibrium arrow to the left + \arrow{>{}>=<}[ \charrow{>>=<}] + \sinceversion{4.5}reversed unbalanced equilibrium arrow to the left + \arrow{<=o>}[ \charrow{<=o>}] + \sinceversion{4.15}quasi equilibrium arrow + \arrow{<=o>{}>}[ \charrow{<=o>>}] + \sinceversion{4.15}unbalanced quasi equilibrium arrow to the right + \arrow{<{}<=o>}[ \charrow{<<=o>}] + \sinceversion{4.15}unbalanced quasi equilibrium arrow to the left + \arrow{<o>}[ \charrow{<o>}] + isolobal arrow + \arrow{<==>}[ \charrow{<==>}] + \sinceversion{4.5}I've seen this one used. I'm not sure it actually has a + meaning in chemical equations. If you have some official reference for + this arrow type please feel free to contact me. +\end{arrows} +All these arrows are drawn with \TikZ. +\begin{example} + \ch{H2 + Cl2 -> 2 HCl} \par + \ch{H2O + CO3^2- <=> OH- + HCO3-} \par + \ch{A <- B} \par + \ch{\{[CH2=CH-CH2]- <-> {}[CH2-CH=CH2]- \}} \par + \ch{A <> B} \par + \ch{H+ + OH- <=>> H2O} \par + \ch{2 NO2 <<=> N2O4} +\end{example} + +\subsection{Labels} +The arrows take two optional arguments to label them. +\begin{arrows} + \arrow*{->\oarg{above}\oarg{below}} + Add text above or under an arrow. +\end{arrows} +\begin{example}[side-by-side] + \ch{A ->[a] B} \par + \ch{A ->[a][b] B} \par + \ch{A ->[\SI{100}{\celsius}] B} +\end{example} +The label text can be parsed seperately from the arrow. The recipe is easy: +leave blanks. +\begin{example}[side-by-side] + \ch{A ->[H2O] B} \par + \ch{A ->[ H2O ] B} \par + \ch{A ->[ "\ox{2,Ca}" F2 ] B} \par + \ch{A ->[ $\Delta$,~ [ H+ ]] B} +\end{example} + +If you leave the blanks \chemformula\ treats the groups inside the square +brackets as seperated input types. The arrow reads its arguments +\emph{afterwards}. As you can see the arrows \enquote{grow} with the length +of the labels. What stays constant is the part that protrudes the labels. +\begin{example} + \ch{A ->[a] B} \par + \ch{A ->[ab] B} \par + \ch{A ->[abc] B} \par + \ch{A ->[abc~abc] B} \par + % needs the `chemfig' package: + \setatomsep{15pt} + \ch{A ->[ "\chemfig{-[:30]-[:-30]OH}" ] B} \par +\end{example} + +\subsection{Customization} +These are the options which enable you to customize the arrows: +\begin{options} + \keyval{arrow-offset}{dim}\Default{.75em} + This is the length that an arrow protrudes a label on both sides. This + means an empty arrow's length is two times \code{arrow-offset}. + \keyval{arrow-min-length}{dim}\Default{0pt} + \sinceversion{3.6b}The minimal length an error must have unless two times + \option{arrow-offset} plus the width of the label is larger. + \keyval{arrow-yshift}{dim}\Default{0pt} + Shifts an arrow up (positive value) or down (negative value). + \keyval{arrow-ratio}{<factor>}\Default{.6} + The ratio of the arrow lengths of the unbalanced equilibrium. \code{.4} + would mean that the length of the shorter arrow is $0.4\times$ the length + of the longer arrow. + \keyval{compound-sep}{dim}\Default{.5em} + The space between compounds and the arrows. + \keyval{label-offset}{dim}\Default{2pt} + The space between the labels and the arrows. + \keyval{label-style}{font command}\Default{\cs*{footnotesize}} + The relative font size of the labels. + \keyval{arrow-penalty}{num}\Default{0} + \sinceversion{4.0a}The penalty that is inserted after an arrow for + (dis-)allowing line breaks. + \keyval{arrow-style}{\TikZ}\Default + \sinceversion{4.1a}Additonal \TikZ\ keys for formatting the arrows. +\end{options} + +The following code shows the effect of the different options on the \verbcode+<=>>+ +arrow: +\begin{example} + standard: \ch{A <=>>[x][y] B} \par + longer: \ch[arrow-offset=12pt]{A <=>>[x][y] B} \par + higher: \ch[arrow-yshift=2pt]{A <=>>[x][y] B} \par + more balanced: \ch[arrow-ratio=.8]{A <=>>[x][y] B} \par + labels further away: \ch[label-offset=4pt]{A <=>>[x][y] B} \par + larger distance to compounds: \ch[compound-sep=2ex]{A <=>>[x][y] B} \par + smaller labels: \ch[label-style=\tiny]{A <=>[x][y] B} +\end{example} + +If you want to have different arrow tips\sinceversion{4.7} there is an easy +way to use existing arrow tips (as defined by \TikZ). \chemformula\ uses +three different arrow tips: \code{cf}, \code{left cf} and \code{right cf}. If +you want them to match those of \pkg{chemfig}~\cite{pkg:chemfig} for example +you could do: +\begin{sourcecode} + \pgfkeys{ + cf /.tip = {CF@full} , + left cf /.tip = {CF@half} + } +\end{sourcecode} +\pkg{chemfig} has no equivalent of \code{right cf}. This mechanism relies on +\TikZ\ version~3.0.0 and the new \code{arrows.meta} library. + +\subsection{Modify Arrow Types}\label{sec:arrows_modify} +The arrows are defined with the commands +\begin{commands} + \command{NewChemArrow}[\marg{type}\marg{\TikZ}] + Define the new arrow type \meta{type}. Issue an error if an arrow type + \meta{type} already exists. + \command{ProvideChemArrow}[\marg{type}\marg{\TikZ}] + Define\sinceversion{4.12a} the new arrow type \meta{type} only if it + doesn't exist, yet. + \command{DeclareChemArrow}[\marg{type}\marg{\TikZ}] + Define the new arrow type \meta{type} or overwrite it if it already + exists. + \command{RenewChemArrow}[\marg{type}\marg{\TikZ}] + Redefine the arrow type \meta{type}. Issue an error if an arrow type + \meta{type} doesn't exist. + \command{ShowChemArrow}[\marg{type}] + Print out the current definition of the arrow type \meta{type}. +\end{commands} +\meta{type} is the sequence of tokens that is replaced with the actual arrow +code. For example the basic arrow is defined via +\begin{sourcecode} + \NewChemArrow{->}{ + \draw[chemarrow,-cf] (cf_arrow_start) -- (cf_arrow_end) ; + } +\end{sourcecode} +In order to define arrows yourself you need to know the basics of +\TikZ\footnote{Please see the \manual{pgfmanual} for details.}. The +predefined arrows use the arrow tips \code{cf}, \code{left cf} and \code{right + cf}. They also all except the net reaction arrow \code{==} use the +\TikZ-style \code{chemarrow} that you should use, too, if you want the option +\option{arrow-style} to have an effect. + +There are some predefined coordinates you can and should use. For +completeness' sake the arrow tips and the \TikZ-style are also listed: +\begin{codedesc} + \Code{(cf\_arrow\_start)} + The beginning of the arrow. + \Code{(cf\_arrow\_end)} + The end of the arrow. + \Code{(cf\_arrow\_mid)} + The mid of the arrow. + \Code{(cf\_arrow\_mid\_start)} + The beginning of the shorter arrow in types like \verbcode+<=>>+. + \Code{(cf\_arrow\_mid\_end)} + The end of the shorter arrow in types like \verbcode+<=>>+. + \Code{cf} + A double-sided arrow tip. + \Code{left cf} + A left-sided arrow tip. + \Code{right cf} + A right-sided arrow tip. + \Code{chemarrow} + \chemformula's \TikZ-style that is applied to the arrows and set with + \option{arrow-style} +\end{codedesc} +\begin{example} + \NewChemArrow{.>}{ + \draw[chemarrow,-cf,dotted,red] (cf_arrow_start) -- (cf_arrow_end); + } + \NewChemArrow{n>}{ + \draw[chemarrow,-cf] + (cf_arrow_start) + .. controls ([yshift=3ex]cf_arrow_mid) .. + (cf_arrow_end); + } + \ch{A .> B} \ch{A .>[a][b] B} \ch{A n> B} +\end{example} + +\begin{example} + \texttt{\ShowChemArrow{->}} \par + \RenewChemArrow{->}{\draw[chemarrow,->,red] (cf_arrow_start) -- (cf_arrow_end) ;} + \texttt{\ShowChemArrow{->}} \par + \ch{A -> B} +\end{example} + +\subsection{Standalone Arrows} +\chemformula\ offers\sinceversion{4.0} a command that \emph{only accepts} the +\enquote{arrow} input type: +\begin{commands} + \command{charrow}[\marg{type}\oarg{above}\oarg{below}] + Print the arrow type \meta{type}. +\end{commands} +This command is internally used for the arrows, too, when \cs{ch} is parsed. + +\section{Names} +\subsection{Syntax} +\chemformula\ has a built-in syntax to write text under a compound. In a way +it works very similar to the arrows. +\begin{commands} + \command{ch}[\Marg{ !(\meta{text})( \meta{formula} ) }] + Writes \meta{text} below \meta{formula}. +\end{commands} +If an exclamation mark is followed by a pair of parentheses \chemformula\ will +parse it this way: +\begin{example} + \ch{!(ethanol)( CH3CH2OH )} +\end{example} +The same what's true for the arrows arguments holds for these arguments: if +you leave blanks the different parts will be treated according to their input +type before the text is set below the formula. +\begin{example} + \ch{!(water)(H2O)} \quad + \ch{!( "\textcolor{blue}{water}" )( H2O )} \quad + \ch{!( $2n-1$ )( H2O )} \quad + \ch{!( H2O )( H2O )} \quad + \ch{!(oxonium)( H3O+ )} +\end{example} +If for some reason you want to insert an exclamation mark \emph{without} it +creating a name you only have to make sure it isn't followed by parentheses. +\begin{example}[side-by-side] + \ch{H2O~(!)} \par + \ch{A!{}()} +\end{example} + +\subsection{Customization} +\chemformula\ provides two options to customize the output of the names: +\begin{options} + \keyval{name-format}{commands}\Default{\cs*{scriptsize}\cs*{centering}} + The format of the name. This can be arbitrary input. + \keychoice{name-width}{\meta{dim},auto}\Default{auto} + The width of the box where the label is put into. \code{auto} will detect + the width of the name and set the box to this width. +\end{options} +\begin{example} + \ch{!(acid)( H2SO4 ) -> B} \par + \ch[name-format=\sffamily\small]{!(acid)( H2SO4 ) -> B} \par + \ch[name-format=\scriptsize N:~]{!(acid)( H2SO4 ) -> B} \par + \ch[name-width=3em,name-format=\scriptsize\raggedright]{!(acid)( H2SO4 ) -> B} +\end{example} + +\subsection{Standalone Names} +\chemformula\ offers a command\sinceversion{4.0} that allows the usage of the +\enquote{name} syntax in normal text. This is the command that a bang is +replaced with in \chemformula's formulas, actually. Both arguments are +mandatory. +\begin{commands} + \command{chname}[\darg{text~1}\darg{text~2}] + The command that is useed internally for placing \meta{text~1} below of + \meta{text~2}. +\end{commands} + +\section{Format and Font}\label{sec:format} +In the standard setting \chemformula\ doesn't make any default changes to the +font of the formula output. Let's take a look at a nonsense input which shows +all features: +\begin{example}[pre-output={\biolinumLF\libertineLF\setchemformula{format=}}] + \newcommand*\sample{% + \ch{H2C-C+C-CH=CH+ + CrO4^2- + <=>[x][y] + 2.5 Cl^{-.} + 3_1/2 Na*OH_{(aq)} + !(name)( A^n ) "\LaTeXe"} + } + \sample +\end{example} +\newcommand*\sample{% + \ch{H2C-C+C-CH=CH+ + CrO4^2- + <=>[x][y] + 2.5 Cl^{-.} + 3_1/2 Na*OH_{(aq)} + !(name)( A^n ) "\LaTeXe"} +} + +Now we're going to change different aspects of the font a look what happens: +\begin{example}[pre-output={\biolinumLF\libertineLF\setchemformula{format=}}] + \sffamily Hallo \sample \\ + \ttfamily Hallo \sample \normalfont \\ + \bfseries Hallo \sample \normalfont \\ + \itshape Hallo \sample +\end{example} +As you can see most features adapt to the surrounding font. + +If you want to change the default format you need to use this option: +\begin{options} + \keyval{format}{code}\Default + Adds \meta{code} before the output of \cs{ch}. + \keyval{atom-format}{code}\Default + This\sinceversion{4.13} adds \meta{code} before each formula. This + allows to specify a format for the chemical formulas only and have a + different format for the rest of the chemical equation. +\end{options} +\begin{example}[pre-output={\biolinumLF\libertineLF\setchemformula{format=}}] + \definecolor{newblue}{rgb}{.1,.1,.5} + \setchemformula{format=\color{newblue}\sffamily} + \sffamily Hallo \sample \\ + \ttfamily Hallo \sample \normalfont \\ + \bfseries Hallo \sample \normalfont \\ + \itshape Hallo \sample +\end{example} + +You can also specifically change the fontfamily, fontseries and fontshape of +the output. +\begin{options} + \keyval{font-family}{family}\Default + Changes the fontfamily of the output with \cs*{fontfamily}\marg{family}. + \keyval{font-series}{series}\Default + Changes the fontseries of the output with \cs*{fontseries}\marg{series}. + \keyval{font-shape}{shape}\Default + Changes the fontshape of the output with \cs*{fontshape}\marg{shape}. +\end{options} +\begin{example}[pre-output={\biolinumLF\libertineLF\setchemformula{format=}}] + \setchemformula{font-series=bx} + Hallo \sample \par + \sffamily Hallo \sample \normalfont \par + \setchemformula{font-family=lmss,font-series=m} Hallo \sample + \normalfont \par + \itshape Hallo \sample +\end{example} + +If you're using \XeLaTeX\ or \LuaLaTeX\ and have loaded \pkg{fontspec} you +have the possibilty to set the font with it: +\begin{options} + \keyval{font-spec}{font}\Default + Use font \meta{font} for \chemformula's formulas. +\end{options} +or with options +\begin{options} + \keychoice{font-spec}{\Marg{[\meta{options}]\meta{font}}} + Use font \meta{font} with options \meta{options} for \chemformula's + formulas. +\end{options} +Since this document is typeset with \pdfLaTeX\ the option cannot be +demonstrated here. + +\section{Usage In Math Equations} +The \cs{ch} command can be used inside math equations. It recognizes +\verbcode+\\+ and \verbcode+&+ and passes them on. However, you can't use the +optional arguments of \verbcode+\\+ inside \cs{ch}. +\begin{example} + \begin{align} + \ch{ + H2O & ->[a] H2SO4 \\ + Cl2 & ->[x][y] CH4 + } + \end{align} + \begin{align*} + \ch{ + RNO2 &<=>[ + e- ] RNO2^{-.} \\ + RNO2^{-.} &<=>[ + e- ] RNO2^2- + } + \end{align*} +\end{example} + +\section{Usage with \TikZ\ or \pkg*{pgfplots} and externalization} +Since \chemformula\ uses\sinceversion{4.1} \TikZ\ to draw reaction arrows +and bonds they would be externalized, too, if you use that facility with +\TikZ\ or \needpackage{pgfplots}~\cite{pkg:pgfplots}. This may not be +desirable since they are very small pictures maybe containing of a single +line. This is why \chemformula's default behaviour is to disable +externalization for it's bonds and arrows. This can be turned on and off +through the following option: +\begin{options} + \keybool{tikz-external-disable}\Default{true} + dis- or enable \TikZ' externalization mechanism for \chemformula's arrows + and bonds. +\end{options} + +If you should be using a formula that contains bonds or arrows inside of a +\code{tikzpicture} that is externalized you should locally enable it for +\chemformula, too: + +\begin{sourcecode} + \begin{tikzpicture} + \setchemformula{tikz-external-disable=false} + \begin{axis}[xlabel={\ch{2 H+ + 2 e- -> H2}}] + \addplot ... ; + \end{axis} + \end{tikzpicture} +\end{sourcecode} + +\section{Lewis Formulae}\label{sec:lewis-formulae} +\chemformula\ offers\sinceversion{4.2} a command to typeset Lewis formulae. +This does not mean Lewis structures! Those can be achieved using the +\pkg{chemfig} package~\cite{pkg:chemfig}. \chemformula\ provides the +possibility to draw electrons as dots and pairs of dots or a line around an +atom. + +\begin{commands} + \command{chlewis}[\oarg{options}\marg{electron spec}\marg{atom}] + Draws electrons around the \meta{atom} according to \meta{electron spec}. +\end{commands} + +Electrons are specified by the angle to the horizontal in the couter-clockwise +direction. The default appearance is a pair of electrons drawn as a pair of +dots. Other specifications can be chosen. The specification follows the +pattern \meta{angle}\meta{separator}. \meta{angle} is a positiv or negativ +integer denoting the angle counter clockwise to the horizontal where the +electrons should be drawn. \meta{separator} is either a dot (\code{.}, single +electron), a colon (\code{:}, electron pair), a vertical line (\code{|}, +electron pair), an o (\code{o}, empty pair), or a comma (\code{,} default +spec). + +\begin{commands} + \command{chlewis}[\Marg{\meta{angle1}\meta{type1}\meta{angle2}\meta{type2}}% + \marg{atom}] + For example: \cs{chlewis}\Marg{0,180}\Marg{O} gives \chlewis{0,180}{O} and + \cs{chlewis}\Marg{0.90.180.270.}\Marg{C} gives + \chlewis{0.90.180.270.}{C}. +\end{commands} + +The appearance can be influenced by a number of options: +\begin{options} + \keychoice{lewis-default}{.,:,|,o,single,pair,pair (dotted),pair + (line),empty}\Default{pair} + Sets the default type that is used when no type is given in \meta{electron + spec}. + \keyval{lewis-distance}{dim}\Default{1ex} + The distance of two electrons in a pair. + \keyval{lewis-line-length}{dim}\Default{1.5ex} + The length of the line representing an electron pair. + \keyval{lewis-line-width}{dim}\Default{1pt} + The thickness of a line representing an electron pair. + \keyval{lewis-offset}{dim}\Default{.5ex} + The distance of the symbols from the atom. +\end{options} +The dots are drawn according to the \option{radical-radius} option mentioned +in section~\ref{ssec:compounds:customization}. + +The basic usage should be more or less self-explaining: +\begin{example}[side-by-side] + \chlewis{0:90|180.270}{O} + \quad + \chlewis{45,135}{O} + \quad + \chlewis{0o}{Na} +\end{example} + +The next example shows the effect of some of the options: +\begin{example} + \chlewis[lewis-default=.]{23,68,113,158,203,248,293,338}{X} + \quad + \chlewis{0,90,180,270}{X} + \quad + \chlewis[lewis-distance=1.25ex]{0,90,180,270}{X} + \quad + \chlewis[lewis-distance=.75ex,radical-radius=.5pt]{0,90,180,270}{X} + \quad + \chlewis[ + radical-radius=.5pt, + lewis-default=. + ]{23,68,113,158,203,248,293,338}{X} +\end{example} + +\begin{example} + \ch{ + !($1s^22s^1$)( "\chlewis{180.}{Li}" ) + + !($1s^22s^22p^5$)( "\chlewis{0.90,180,270}{F}" ) + -> + !($1s^2$)( Li+ ) + !($1s^22s^22p^6$)( "\chlewis{0,90,180,270}{F}" {}- ) + } +\end{example} + +\section{Kröger-Vink Notation}\label{sec:kroger-vink-notation} + +\chemformula\ also supports the Kröger-Vink notation\sinceversion{4.5}. +\begin{options} + \keybool{kroeger-vink}\Default{false} + Enable the Kröger-Vink notation. As most options this can be enabled + globally via the setup command or locally as option to \cs{ch}. +\end{options} + +With this option enabled several changes come into effect: \verbcode|'| +produces a prime, a \code{x} in a superscript produces $\times$, and both a +\code{.} and a \code{*} produce a little filled circle. In the Kröger-Vink +notation a prime denotes a negative relative charge, the circle a positive +relative charge, and the cross denotes a neutral relative charge. + +\begin{example}[side-by-side,add-sourcecode-options={literate=}] + \setchemformula{kroeger-vink=true} + \ch{Al_{Al}^'} + \ch{Al_{Al}'}\par + \ch{Ni_{Cu}^{x}}\par + \ch{V_{Cl}^.} + \ch{V_{Cl}^*}\par + \ch{Ca_i^{..}}\par + \ch{e^'}\par + \ch{Cl_i^'} + \ch{Cl_i'}\par + \ch{O_i^{''}} + \ch{O_i''} +\end{example} + +There are a number of options for customizations: +\begin{options} + \keyval{kv-positive-style}{\TikZ}\Default + \TikZ\ code for positive charge dot. + \keyval{kv-positive-radius}{dim}\Default{.3ex} + Radius of positive charge dot + \keyval{kv-positive-hshift}{dim}\Default{.15em} + Horizontal shift of positive charge dot + \keyval{kv-positive-vshift}{dim}\Default{.5ex} + Vertical shift positive charge dot + \keyval{kv-positive-offset}{dim}\Default{.4em} + The offset of two consecutive positive charge dots + \keyval{kv-neutral-symbol}{\TeX\ code}\Default{\$\cs*{times}\$} + Symbol for neutral particles. +\end{options} + + + +% \section{Further Examples} +% This section presents some examples of a possible usage. + +% \begin{example} +% \begin{reaction}[Synthese von Alkanen] +% !(Synthesegas)( $n$ CO + $(2n+1)$ H2 ) +% ->[\SI{200}{\celsius}][[CoNi]] +% C_{$n$}H_{$2n+2$} + $n$ H2O +% \end{reaction} +% \end{example} + +% \begin{example} +% \begin{reactions*} +% "a)" && CH4 + Cl2 &-> CH3Cl + HCl && "{\small Chlormethan/Methylchlorid}" \\ +% "b)" && CH3Cl + Cl2 &-> CH2Cl2 + HCl && "{\small Dichlormethan/Methylenchlorid}" \\ +% "c)" && CH2Cl2 + Cl2 &-> CHCl3 + HCl && "{\small Trichlormethan/Chloroform}" \\ +% "d)" && CHCl3 + Cl2 &-> CCl4 + HCl && "{\small Tetrachlormethan/Tetrachlorkohlenstoff}" +% \end{reactions*} +% \end{example} + +% \begin{example} +% \chemsetup[ox]{parse=false} +% \ch{ +% "\ox{\delm,C}" -{} "\ox{\delp,M}" \qquad +% ( <-> "\ox{\delp,C}" -{} "\ox{\delm,Br}" ) +% } \\ +% \ch[adduct-space=0pt]{X. + .Y <=> X-Y + Bindungsenergie} \\ +% \ch[name-format=\normalsize]{ +% !(\State{H}{f}\qquad)() !(\textcolor{red}{??})( CH4\gas{} ) + +% !(\num{0})( 2 O2\gas{} ) +% -> +% !(\num{-94.3})( CO2\gas{} ) + +% !(\num{-57.9})( H2O\lqd{} ) + +% !(\num{-192.1})( "\State{H}" ) +% } +% \end{example} + +% \begin{example} +% \newcommand\cstack[1]{% +% \clap{% +% \begin{tabular}{c} +% #1 +% \end{tabular} +% }% +% } +% \begin{reactions*} +% CH3MgBr + "\ox*{1,Cu}" X & +% -> "\glqq" CH3 "\ox*{1,Cu}\grqq" + MgBrX "\qquad X~$=$~Br,I,CN" \\ +% 2 MeLi + CuI & +% -> !(\cstack{Dimethylcuprat\\(Gilmann-Cuprat)})( Me2CuLi ) + Li +% \end{reactions*} +% \end{example} + +% \begin{example} +% % needs `chemfig' +% \begin{reactions*} +% H3C-CH3 + Cl2 & +% ->[$\Delta$][$h\nu$] H3CCH2Cl + HCl & & +% "\Enthalpy{-27.1}" \\ +% H3C-CH3 + "\Lewis{0.,Cl}" & +% -> H3CCH2 "\Lewis{0.,\vphantom{H}}" + HCl & & +% "\Enthalpy{-5.0}" \\ +% H3C-CH2 "\Lewis{0.,\vphantom{H}}" + Cl2 & +% -> H3CCH2Cl + "\Lewis{0.,Cl}" & & +% "\Enthalpy{-23.0}" +% \end{reactions*} +% \end{example} + +% The following example shows how the cancelling of compounds could be +% done\footnote{Inspired by a question on TeX.SE: +% \url{http://tex.stackexchange.com/q/30118/5049}}. +% \begin{example} +% % needs `cancel' +% \begin{align*} +% \ch{\cancel{HCOOH\aq} + H2O\lqd{} &<=> H3O^+\aq{} + \cancel{HCOO^-\aq}} \\ +% \ch{\cancel{HCOO^-\aq} + H2O\lqd{} &<=> \cancel{HCOOH\aq} + OH^-\aq}\\[-1ex] +% \cline{1-2} +% \ch{H2O\lqd{} + H2O\lqd{} &<=> H3O^+\aq{} + OH^-\aq} +% \end{align*} +% \end{example} + +\appendix +\newenvironment{changes}[2][]{% + \subsection*{Version #2\ifblank{#1}{}{ (#1)}} + \itemize\let\change\item +}{\enditemize} + +\section{History Since Version~4.0} + +\begin{changes}{4.0} + \change Since version 4.0\sinceversion{4.0}, the \chemformula\ package is + distributed independently from \chemmacros. +\end{changes} + +\begin{changes}{4.1} + \change New option \option{tikz-external-disable}. + \change New option \option{frac-math-cmd}. +\end{changes} + +\begin{changes}{4.2} + \change New option \option{arrow-style}. + \change New command \cs{chlewis} that allows to add Lewis electrons to an + atom, see section~\ref{sec:lewis-formulae}. +\end{changes} + +\begin{changes}{4.3} + \change New option \option{stoich-print}. + \change New command \cs{chstoich}. + \change The commands \cs*{DeclareChem\meta{...}} now don't give an error any + more if the command already exists. This is more consistent with \LaTeX's + \cs*{DeclareRobustCommand}. For all those commands a version + \cs*{NewChem\meta{...}} is introduced that \emph{does} give an error if + the new command is already defined. +\end{changes} + +\begin{changes}{4.4} + \change A single dash \code{-} in \cs{ch} is now treated as a minus sign. + This is consistent with the behaviour of a \code{+}. +\end{changes} + +\begin{changes}{4.5} + \change New arrow types \arrowtype{>=<}, \arrowtype{>=<{}<}, \arrowtype{>{}>=<} + and \arrowtype{<==>}. + \change Internal changes to \cs{ch} allow usage of optional arguments of + \cs*{\textbackslash} and \cs*{label} in \chemmacros' \env*{reactions} + environment. +\end{changes} + +\begin{changes}{4.6} + \change New options \option{circled} and \option{circletype}. this allows to + set the behaviour as described on \chemmacros' manual for a specific usage + of \cs{ch}. +\end{changes} + +\begin{changes}{4.7} + \change Dependency change: \chemformula\ now requires the \TikZ\ library + \code{arrows.meta} instead of the library \code{arrows}. This requires + \TikZ\ version~3.0.0. +\end{changes} + +\begin{changes}{4.8} + \change The \chemformula\ package now is no longer part of the \chemmacros\ + bundle but is distributed as a package of it's own. +\end{changes} + +\begin{changes}{4.9} + \change New options \option{minus-space} and \option{minus-penalty} equivalent + to the existing \option{plus-space} and \option{plus-penalty} + \change New options \option{plus-output-symbol} and + \option{minus-output-symbol} for customizing the plus and minus signs in + the output. +\end{changes} + +\begin{changes}{4.10} + \change New macro set \cs{NewChemCompoundProperty}, see + section~\ref{sec:extend-comp-prop} for a description. +\end{changes} + +\begin{changes}{4.11} + \change New macro set \cs{NewChemAdditionSymbol}, see + section~\ref{sec:addition-symbols}. + \change New macro set \cs{NewChemSymbol}, see section~\ref{sec:symbols}. +\end{changes} + +\begin{changes}{4.12} + \change Change package requirement: \chemformula\ now not loads complete + \pkg{amsmath} but only \pkg{amstext}. +\end{changes} + +\begin{changes}{4.13} + \change Check for blank input parts and don't process them. + \change Drop support for \cs*{[} and \cs*{]} as replacement for \code{[} and + \code{]} inside arrow captions. + \change New option \option{atom-format}. +\end{changes} + +\begin{changes}{4.14} + \change New option \option{adduct-penalty}. +\end{changes} + +\end{document} |