% arara: pdflatex
% arara: pdflatex
% --------------------------------------------------------------------------
% the BOHR package
% 
%   simple atom representation according to the Bohr model
% 
% --------------------------------------------------------------------------
% Clemens Niederberger
% Web:    https://bitbucket.org/cgnieder/bohr/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2012-2015 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.
% --------------------------------------------------------------------------
% If you have any ideas, questions, suggestions or bugs to report, please
% feel free to contact me.
% --------------------------------------------------------------------------
\documentclass[load-preamble+]{cnltx-doc}
\usepackage[utf8]{inputenc}
\usepackage{bohr}

\setcnltx{
  package = bohr ,
  authors = Clemens Niederberger ,
  email   = contact@mychemistry.eu ,
  url     = http://www.mychemistry.eu/forums/forum/bohr/ ,
  add-cmds = {
    atomicnumber,
    bohr,
    DeclareAtomName,
    DeclareAtomSymbol,
    DeclareElectronDistribution,
    elconf,
    elementname,
    elementsymbol,
    setatomname,setatomsymbol,
    setelectrondistribution,
    setbohr,
    writeelconf,
    Z
  } ,
  add-silent-cmds = ch ,
  abstract = {%
    This package provides means for the creation of simple
    Bohr models of atoms up to the atomic number 112.  Additionally commands
    are provided to convert atomic numbers to element symbols or element names
    and vice versa.\par
    The package is inspired by a question on
    \url{http://tex.stackexchange.com/}:
    \href{http://tex.stackexchange.com/questions/73410/draw-bohr-atomic-model-with-electron-shells-in-tex}%
    {Draw Bohr atomic model with electron shells in \TeX?}%
  } ,
  index-setup = {
     othercode = \footnotesize ,
     level = \addsec ,
     noclearpage
  } ,
  makeindex-setup = {
     columns = 3 ,
     columnsep = 1em
  }
}

% \microtypesetup{tracking=scshape}

\defbibheading{bibliography}{\addsec{References}}

\newpackagename\BOHR{bohr}

\usepackage{chemmacros}

\begin{document}

\section{Licence and Requirements}
\license

The \BOHR\ package loads and needs the packages
\needpackage[graphics]{pgf}~\cite{pkg:pgf},
\needpackage{pgfopts}~\cite{pkg:pgfopts},
\needpackage{elements}~\cite{pkg:elements} and
\pkg{cnltx-base}\footnote{\CTANurl{cnltx}}~\cite{bnd:cnltx}.

\section{News}
With version~1.0 all the parts not directly used for drawing the Bohr models
such as defining element names (\cs*{setatomname}) or element symbols
(\cs*{setatomsymbol}) or writing the electron configuration (\cs*{elconf})
have been extracted into a new package called \pkg{elements}.  This package
provides all the commands besides \cs{bohr} and \cs{setbohr} that you know
from earlier versions of \BOHR.  As a consequence the option
\option*{language} has been dropped.  Obviously said package is now needed by
\BOHR.

\section{Options}
Every option described in the manual can also be used as package option
although this is not really advertised.  The preferred version is to set
options via the setup command \cs{setbohr}.  Future versions of \cs{bohr} may
drop the possible package options completely.  Options are indicated as
\option*{option} and are all key/value like options.  Some options can be set
without value, too.  Then the \code{\default{underlined}} value is used.

\section{Usage}
\BOHR\ is used like any other \LaTeXe\ package:
\begin{sourcecode}
  \usepackage{bohr}
\end{sourcecode}

The main command, \cs{bohr}, creates the models:
\begin{commands}
 \command{bohr}[\oarg{num of shells}\marg{num of electrons}\marg{atom name}]
   The main command.  The mandatory arguments take the number of electrons to
   be printed and the atom symbol that is printed in the center.
\end{commands}

This is described best by an example:
\begin{example}[side-by-side]
  \bohr{3}{Li}
\end{example}
There is not much more to it.  Another example using the optional argument:
\begin{example}[side-by-side]
  \bohr[2]{2}{$\mathrm{Li^+}$}
\end{example}

\section{Customization}
\BOHR\ provides a handful of options to customize the appearance:
\begin{commands}
  \command{setbohr}[\marg{options}]
    Options are set in a key/value syntax using this command.
\end{commands}
\begin{options}
  \keybool{insert-symbol}\Default{false}
    If set to \code{true} \BOHR\ will insert the atomic symbol suiting to the
    given electron number if \emph{no} third argument is given.
  \keybool{insert-number}\Default{false}
    If set to \code{true} \BOHR\ will use the appropriate number of electrons
    for the given element symbol in the third argument if \emph{no} second
    argument is given.  This of course only works if the third argument is one
    of the 112 element symbols.
  \keybool{insert-missing}\Default{false}
    Sets both \option{insert-symbol} and \option{insert-number}.
  \keyval{atom-style}{code}\Default
    This code will be placed immediatly before the third argument of
    \cs{bohr}.  The last macro in it may need one argument.
  \keyval{name-options-set}{tikz option}\Default
    This value is passed to the options of the \cs*{node} the third argument
    of \cs{bohr} is placed in.
  \keyval{name-options-add}{tikz options}\Default
    This value will be added to options set with \option{name-options-set}.
  \keyval{nucleus-options-set}{tikz options}{}
  \Default{draw=black!80,fill=black!10,opacity=.25}
    This value is passed to the options of the \cs*{draw} command that draws
    the circle around the name-node.
  \keyval{nucleus-options-add}{tikz options}\Default
    This value will be added to options set with \option{nucleus-options-set}.
  \keyval{nucleus-radius}{dimension}\Default{1em}
    The radius of the circle around the name-node.
  \keyval{electron-options-set}{tikz options}\Default{blue!50!black!50}
    This value is passed to the options of the \cs*{fill} command that draws
    the electrons.
  \keyval{electron-options-add}{tikz options}\Default
    This value will be added to options set with \option{electron-options-set}.
  \keyval{electron-radius}{dimension}\Default{1.5pt}
    The radius of the circles that represent the electrons.
  \keyval{shell-options-set}{tikz options}\Default{draw=blue!75,thin}
    This value is passed to the options of the \cs*{draw} command that draws
    the circles that represent the shells.
  \keyval{shell-options-add}{tikz options}\Default
    This value will be added to options set with \option{shell-options-set}.
  \keyval{shell-dist}{dimension}\Default{1em}
    The distance between the nucleus and the first shell and between subsequent
    shells.
  \keychoice{distribution-method}{periodic,quantum}\Default{quantum}
    \sinceversion{0.3}Determines how the electrons are distributed on the
    shells.  \code{periodic} distributes the electrons 2-8-8-18-18-32-32, \ie,
    according to the place of the corresponding atom in the periodic table of
    elements.  \code{quantum} distributes the electrons according to the
    electron configuration of the corresponding atom where each shell
    represents the main quantum number.  \ch{Pd} for example has the
    configuration $1s^22s^22p^63s^23p^63d^{10}4s^24p^64d^{10}$ and would get
    two electrons on the first shell, 8~electrons on the second, and
    18~electrons each on the third and fourth.
\end{options}

\begin{example}
  \setbohr{name-options-set={font=\footnotesize\sffamily}}
  \bohr{2}{He} \bohr{7}{N}
\end{example}

\begin{example}
  % uses package `chemmacros'
  \setbohr{atom-style={\footnotesize\sffamily\ch}}
  \bohr{0}{H+} \bohr{10}{F-}
\end{example}

\begin{example}[side-by-side]
  \setbohr{
    shell-options-add = dashed,
    shell-dist        = .5em,
    insert-missing
  }
  \bohr{6}{} \bohr{}{K}
\end{example}

\begin{example}
  \setbohr{distribution-method=quantum,insert-missing}
  \elconf{Fe} \\ % provided by `elements'
  \bohr{}{Fe}
  \setbohr{distribution-method=periodic}
  \bohr{}{Fe}
\end{example}

\end{document}
