chemnum (8nov11)

git-svn-id: svn://tug.org/texlive/trunk@24547 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 94 insertions, 57 deletions

diff --git a/Master/texmf-dist/doc/latex/chemnum/chemnum_doc_en.tex b/Master/texmf-dist/doc/latex/chemnum/chemnum_doc_en.tex
index 1357f246d0a..192d5bf33cc 100644
--- a/Master/texmf-dist/doc/latex/chemnum/chemnum_doc_en.tex
+++ b/Master/texmf-dist/doc/latex/chemnum/chemnum_doc_en.tex
@@ -3,7 +3,7 @@
 % - a comprehensive numbering method for chemical compounds                           - %
 % ------------------------------------------------------------------------------------- %
 % - Clemens NIEDERBERGER                                                              - %
-% - 2011/11/01                                                                        - %
+% - 2011/11/08                                                                        - %
 % ------------------------------------------------------------------------------------- %
 % - http://www.mychemistry.eu/                                                        - %
 % - contact@mychemistry.eu                                                            - %
@@ -30,9 +30,10 @@
 % - derived files chemnum_doc_de.pdf and chemnum_doc_en.pdf                           - %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \documentclass[DIV11]{scrartcl}
-\usepackage[english]{babel}
+\usepackage[ngerman,german,naustrian,austrian,english,british,american,canadian,french,canadien,spanish,italian]{babel}
+
 \usepackage[utf8]{inputenx}
-\usepackage{chemnum,textcomp,lmodern,microtype,url,xspace,booktabs,array,chemscheme}
+\usepackage{chemnum,textcomp,lmodern,microtype,url,xspace,booktabs,longtable,tabu,chemscheme}
 \usepackage[version=3]{mhchem}
 \usepackage[normalem]{ulem}
 \usepackage[dvipsnames]{xcolor}
@@ -118,8 +119,8 @@
 \ExplSyntaxOff
 
 \newcommand*\chemnum{\textsf{chemnum}\xspace}
-\newcommand*\CNversion{v0.3b\xspace}
-\newcommand*\CNdate{2011/11/03\xspace}
+\newcommand*\CNversion{v0.3c\xspace}
+\newcommand*\CNdate{2011/11/08\xspace}
 
 \newcommand*\paket[1]{\textsf{#1}\footnote{\url{http://www.ctan.org/pkg/#1}}}
 \newcommand*\eg{\mbox{e.\,g.}\xspace}
@@ -128,7 +129,7 @@
 
 \cmpdinit*{a,aa,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,benzol}
 \begin{document}
-
+\selectlanguage{english}
 \begin{titlepage}
  \centering
  \Huge chemnum \CNversion
@@ -173,19 +174,6 @@
 
 \chemnum also needs the packages \paket{etoolbox}, \paket{psfrag} and (sometimes) \paket{textgreek}, see section \ref{sec:package_options}.
 
-\section{New in \chemnum \CNversion}
-Since \CNversion the following is new:\cmpd*{a.one,a.two,a.three,a.four,a.five}
-\begin{itemize}
- \item the key \lstinline=sub-cmpd-sep= now is \lstinline=sub-marker=, see page \pageref{ssec:sub_label_marker}
- \item the key \lstinline=cmpd-sub-counter= now is \lstinline=sub-counter=, see page \pageref{key:sub-counter}
-\end{itemize}
-The renaming follows the wish, to distinguish different classes of keys indicating the scope they're used for, see page \pageref{key_classes}.
-\begin{itemize}
- \item several keys to create labels like \cmpd[sub-list={one..three,five}]{a}, see section \ref{ssec:lists_ranges} on page \pageref{ssec:lists_ranges}.
- \item the command \lstinline=\cmpdref=, which replaces strings in \lstinline=eps= files, see section \ref{ssec:cmpdref}.
- \item the key \lstinline=ref-tag=, see page \pageref{key:key-tag}.
-\end{itemize}
-
 \section{Package Options}\label{sec:package_options}
 \chemnum has one package option.
 \begin{framed}
@@ -222,6 +210,7 @@ Then there is \paket{bpchem}, which provides commands similar to \lstinline=\lab
 
 If you notice any feature missing, please let me know by sending me an email.
 
+\newpage
 \section{Numbering compounds}\label{sec:nummerieren}
 \subsection{Basic command}
 The main command of this package is
@@ -287,8 +276,7 @@ The right description would be something like:
 \begin{beispiel}
  More than one label can be put inside \verb=\cmpd=, separated by commas. Then a list like \cmpd{a, b, c, e, g.two} is printed.
 \end{beispiel}
-
-The -- in the eyes of non-US Americans odd looking -- \verb=, and= between \cmpd{e} and \cmpd{g.two} suggests that there are options to customize the list, see section \ref{ssec:trenner} (page \pageref{ssec:trenner}).
+The Harvard comma (see \ref{ssec:harvard-comma}) in \verb=, and= between \cmpd{e} and \cmpd{g.two} suggests that there are options to customize the list, see sections \ref{ssec:trenner} and \ref{sec:language_support}.
 
 \section{Initialize labels at once}\label{sec:cmpdinit}
 The commands described in this section are not essential for the usage of \chemnum, but provide additional functionality that some users might find useful.
@@ -383,7 +371,6 @@ As mentioned in the beginning of this section the initiation of labels is not re
  \item The use of \lstinline=\cmpdinit= does the same thing as \lstinline=\cmpdinit*= \emph{and} declares all the labels in the given order. So if you use it, you won't have to use \lstinline=\cmpd*= (section \ref{cmd:unsichtbares_label}) and \lstinline=\cmpd+= (section \ref{cmd:cmpd_plus}). This gives you direct control, which number is given to which compound. 
 \end{enumerate}
 
-\newpage
 \section{Resetting the counter}\label{sec:cmpdreset}
 With the command
 \begin{framed}
@@ -660,6 +647,18 @@ An example for the list attributes:
  \cmpd{a}             % NOT a list!
 \end{beispiel}
 
+Between prefix, label and suffix there is a space inserted as default behaviour:
+\begin{beispiel}
+ \cmpd[cmpd-suffix=sx,cmpd-prefix=px]{k}
+\end{beispiel}
+It can be changed with
+\begin{framed}
+\noindent\lstinline+cmpd-space = <space>+ \hfill Typ: \lstinline=literal=
+\end{framed}
+\begin{beispiel}
+ \cmpd[cmpd-suffix=sx,cmpd-prefix=px,cmpd-space={}]{k}
+\end{beispiel}
+
 \subsection{Separators}\label{ssec:trenner}
 \subsubsection{In case of labels}
 If you have labels with sublabels, you can use a separator symbol:
@@ -687,13 +686,13 @@ In case of lists you also can set a separator symbol, which determines how the l
  \cmpd{a, b, f.two, k}
 \end{beispiel}
 
-\subsubsection{In case of lists -- last separator}
+\subsubsection{In case of lists -- last separator}\label{sssec:last-sep}
 The last separator in a list is a special case. \chemnum provides two keys with which it can be customized.
 \begin{framed}
 \noindent\lstinline+list-last-sep = <separator>+ \hfill type: \lstinline=literal=\\
 \lstinline+list-lang = <lang>+ \hfill type: \lstinline=choice=
 \end{framed}
-There is the \lstinline=choice= key \lstinline=list-lang=, which changes language dependent settings. You can choose between \lstinline=US= (default), \lstinline=GB=, \lstinline=DE=, \lstinline=FR=, \lstinline=ES= and \lstinline=IT=\footnote{If you're missing a language or have caught me with an error please send me an e-mail.}.
+There is the \lstinline=choice= key \lstinline=list-lang=, which changes language dependent settings. You can choose between \lstinline=US= (default), \lstinline=GB=, \lstinline=DE=, \lstinline=FR=, \lstinline=ES= and \lstinline=IT=.
 \begin{beispiel}
  \cmpd[list-lang = US]{a, b, f.two, k} \cmpd[list-lang = US]{a, b}\\
  \cmpd[list-lang = GB]{a, b, f.two, k} \cmpd[list-lang = GB]{a, b}\\
@@ -702,6 +701,7 @@ There is the \lstinline=choice= key \lstinline=list-lang=, which changes languag
  \cmpd[list-lang = ES]{a, b, f.two, k} \cmpd[list-lang = ES]{a, b}\\
  \cmpd[list-lang = IT]{a, b, f.two, k} \cmpd[list-lang = IT]{a, b}
 \end{beispiel}
+As you can see the language \lstinline=US= uses the Harvard comma, all other languages don't. You'll find more on language support and the Harvard comma in section \ref{sec:language_support}.
 
 With the key \lstinline=list-last-sep= you also can set the last separator individually.
 \begin{beispiel}
@@ -794,53 +794,90 @@ For the time being the \lstinline=sub-list= key requires a little caution. Unfor
  \cmpd[sub-list={five..three}]{q} or \cmpd[sub-list={three,one,four}]{q}.
 \end{beispiel}
 
-\newpage
 \subsection{Overview}\label{ssec:uebersicht}
 In this section all keys are listed. Please be aware that the default values of \lstinline=cmpd-delim= and \lstinline=list-delim= and the default setting of \chemnum are \emph{not} the same. By default \chemnum doesn't use delimiters.
 \begin{center}
  \label{tab:keys}
- \begin{tabular}{>{\ttfamily}l>{\ttfamily}l>{\ttfamily}l}\toprule
+ \begin{longtabu*}{>{\ttfamily}l>{\ttfamily}l>{\ttfamily}l}\toprule
   \normalfont\bfseries key & \normalfont\bfseries default & \normalfont\bfseries type \\\midrule
-  cmpd-style               & \lstinline=\textbf= & macro \\
-  cmpd-label               &                     & literal \\
-  cmpd-delim$^\mathrm{a}$  & ()                  & literal \\
-  cmpd-odelim              &                     & literal \\
-  cmpd-cdelim              &                     & literal \\
-  cmpd-prefix              &                     & literal \\
-  cmpd-suffix              &                     & literal \\
-  cmpd-sep                 &                     & literal \\
-  cmpd-counter             & arabic              & choice \\
-  cmpd-all                 & true                & boolean \\\midrule
-  sub-marker               & .                   & literal \\
-  sub-counter              & alph                & choice \\
-  sub-list                 &                     & other$^\mathrm{b}$ \\
-  sub-range-sep            & -                   & literal \\
-  sub-range-marker         & ..                  & literal \\
-  sub-only                 &                     & boolean \\\midrule
-  list-delim$^\mathrm{a}$  & ()                  & literal \\
-  list-odelim              &                     & literal \\
-  list-cdelim              &                     & literal \\
-  list-prefix              &                     & literal \\
-  list-suffix              &                     & literal \\
-  list-sep                 & ,                   & literal \\
-  list-lang                & US                  & choice \\
-  list-last-sep            & and$^\mathrm{c}$    & literal \\\midrule
-  ref-tag                  & TMP                 & literal \\\bottomrule
- \end{tabular}
- \hspace*{1em}
+  cmpd-style               & \lstinline=\textbf=          & macro \\
+  cmpd-label               &                              & literal \\
+  cmpd-delim$^\mathrm{a}$  & ()                           & literal \\
+  cmpd-odelim              &                              & literal \\
+  cmpd-cdelim              &                              & literal \\
+  cmpd-prefix              &                              & literal \\
+  cmpd-suffix              &                              & literal \\
+  cmpd-space               & \lstinline=\penalty\@m\ =    & literal \\
+  cmpd-sep                 &                              & literal \\
+  cmpd-counter             & arabic                       & choice \\
+  cmpd-all                 & true                         & boolean \\\midrule
+  sub-marker               & .                            & literal \\
+  sub-counter              & alph                         & choice \\
+  sub-list                 &                              & other$^\mathrm{b}$ \\
+  sub-range-sep            & -                            & literal \\
+  sub-range-marker         & ..                           & literal \\
+  sub-only                 &                              & boolean \\\midrule
+  list-delim$^\mathrm{a}$  & ()                           & literal \\
+  list-odelim              &                              & literal \\
+  list-cdelim              &                              & literal \\
+  list-prefix              &                              & literal \\
+  list-suffix              &                              & literal \\
+  list-sep                 & ,                            & literal \\
+  list-lang                & US                           & choice \\
+  list-last-sep            & and$^\mathrm{c}$             & literal \\
+  list-serial-comma        &                              & boolean \\\midrule
+  ref-tag                  & TMP                          & literal \\\bottomrule
+ \end{longtabu*}
  \begin{tabular}{>{\footnotesize}r>{\footnotesize\raggedright}p{.3\linewidth}}
   a & value needs \emph{two} tokens. \tabularnewline
   b & input is a comma separated list, see p.\,\pageref{key:sub-list}. \tabularnewline
-  c & depends on the value of \lstinline=list-lang=.
+  c & depends on the value of \lstinline=list-lang= and the usage of \textsf{babel}.
  \end{tabular}
 \end{center}
 
-\newpage
+\section{Language Support}\label{sec:language_support}
+\subsection{Cooperation with \textsf{babel}}
+\chemnum supports the language choice made with the \paket{babel} package for a number of languages. This is done with the \lstinline=\translate= command of the \textsf{translator} package, if it is available. If \textsf{translator} cannot be loaded, language support must be done manually, see section \ref{sssec:last-sep}. Manual language settings can of course still be done, if \textsf{translator} has been loaded.
+\begin{beispiel}
+ \selectlanguage{ngerman}DE: \cmpd{r,s,t} \selectlanguage{german}\cmpd{r,s,t}\\
+ \selectlanguage{naustrian}AU: \cmpd{r,s,t} \selectlanguage{austrian}\cmpd{r,s,t}\\
+ \selectlanguage{english}EN: \cmpd{r,s,t}\\
+ \selectlanguage{british}GB: \cmpd{r,s,t}\\
+ \selectlanguage{american}US: \cmpd{r,s,t}\\
+ \selectlanguage{canadian}CDN-EN: \cmpd{r,s,t}\\
+ \selectlanguage{canadien}CDN-FR: \cmpd{r,s,t}\\
+ \selectlanguage{french}FR: \cmpd{r,s,t}\\
+ \selectlanguage{spanish}ES: \cmpd{r,s,t}\\
+ \selectlanguage{italian}IT: \cmpd{r,s,t}
+\end{beispiel}
+If you find a language missing, please send me an email\footnote{\href{mailto:contact@mychemistry.eu}{contatc@mychemistry.eu}} with the corresponding \textsf{babel} option and the right translation, and I will gladly add it.
+
+\subsection{Harvard Comma}\label{ssec:harvard-comma}
+In American English the so-called Harvard comma is quite commonly used. In British English and other European languages it is rather uncommon.
+\begin{myquote}{\href{http://en.wikipedia.org/wiki/Serial_comma}{Wikipedia}, 2011/11/07}
+ The serial comma (also known as the Oxford comma or Harvard comma, and sometimes referred to as the series comma) is the comma used immediately before a coordinating conjunction (usually and or or, and sometimes nor) preceding the final item in a list of three or more items. For example, a list of three countries can be punctuated as either "Portugal, Spain, and France" (with the serial comma) or as "Portugal, Spain and France" (without the serial comma).
+
+ Opinions vary among writers and editors on the usage or avoidance of the serial comma. In American English, the serial comma is standard usage in non-journalistic writing that follows the \textsc{Chicago Manual of Style}. Journalists, however, usually follow the AP Stylebook, which advises against it. It is used less often in British English, where it is standard usage to leave it out, with some notable exceptions such as \textsc{Fowler's Modern English Usage}. In many languages (e.g., French, German, Italian, Polish, Spanish), the serial comma is not the norm and may even go against punctuation rules. It may be recommended in many cases, however, to avoid ambiguity or to aid prosody.
+\end{myquote}
+\chemnum uses the Harvard comma when American English is used and doesn't, when other languages are used. However, you have the possibility to disable or enable the Harvard comma as you wish:
+\begin{framed}
+\noindent\lstinline+list-serial-comma = <bool>+ \hfill Typ: \lstinline=boolean=\label{key:list-serial-comma}
+\end{framed}
+\begin{beispiel}
+ \selectlanguage{ngerman}DE: \cmpd[list-serial-comma]{r,s,t} vs. \cmpd{r,s,t}\\
+ \selectlanguage{american}US: \cmpd[list-serial-comma=false]{r,s,t} vs. \cmpd{r,s,t}
+\end{beispiel}
+If you choose the language manually, please note that this resets the default behaviour for that language. This means you have to use \lstinline=list-serial-comma= \emph{after} \lstinline=list-lang=.
+\begin{beispiel}
+ wrong: \cmpdsetup{list-serial-comma=false, list-lang=US}\cmpd{r,s,t}\\
+ right: \cmpdsetup{list-lang=US, list-serial-comma=false}\cmpd{r,s,t}
+\end{beispiel}
+
 \section{List of commands}
 In this section all commands provided by \chemnum as well as their variants are listed.
 \begin{center}
  \label{tab:commands}
- \begin{tabular}{l|>{\raggedright}p{.5\linewidth}}\toprule
+ \begin{tabu*}{l>{\raggedright}p{.5\linewidth}}\toprule
   \bfseries command           & \bfseries description \tabularnewline\midrule
   \lstinline=\cmpd[]{}=       & basic command, declares and prints labels or lists of labels, see pages \pageref{sec:nummerieren}ff. \tabularnewline
   \lstinline=\cmpd*{}=        & invisible, declares label, see page \pageref{cmd:unsichtbares_label} \tabularnewline
@@ -852,7 +889,7 @@ In this section all commands provided by \chemnum as well as their variants are
   \lstinline=\cmpdref-[][]{}= & replace temporary markers in \texttt{eps} files by labels without delimiters, see page \pageref{cmd:ohne_begrenzer} \tabularnewline\midrule
   \lstinline=\cmpdreset[]=    & reset counter, siehe page \pageref{sec:cmpdreset} \tabularnewline\midrule
   \lstinline=\cmpdsetup{}=    & setup \chemnum, siehe pages \pageref{sec:cmpdsetup}ff. \tabularnewline\bottomrule
-  \end{tabular}
+  \end{tabu*}
 \end{center}
 
 \section{Credits}