From 3a29216caca37803e25b84a50fd5f7f91ebc04d3 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Sat, 1 Jul 2023 03:01:25 +0000
Subject: CTAN sync 202307010301

---
 macros/generic/chemfig/chemfig-en.tex | 42 ++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 6 deletions(-)

(limited to 'macros/generic/chemfig/chemfig-en.tex')

diff --git a/macros/generic/chemfig/chemfig-en.tex b/macros/generic/chemfig/chemfig-en.tex
index a5c68c4b6f..a6a640256f 100644
--- a/macros/generic/chemfig/chemfig-en.tex
+++ b/macros/generic/chemfig/chemfig-en.tex
@@ -240,6 +240,9 @@ The values (empty by default) contained in these two keys are executed at the ve
 
 For example, we can write \verb|schemestart code=\chemnameint{}| to reset the name depth at the beginning of each reaction scheme.
 
+\subsection{Key "baseline"}
+The value passed to this key sets the vertical position of the molecule. See page~\pageref{baseline}.
+
 \section{Presenting \protect\CF}
 To use this package, start by adding the following code to the preamble:
 \begin{itemize}
@@ -294,6 +297,7 @@ Here is the complete list of parameters as well as their default values\label{li
 		\CFparam{angle increment}
 		\CFparam{node style}
 		\CFparam{bond style}
+		\CFparam{baseline}
 		\CFparam{debug}
 		\CFparam{cycle radius coeff}
 		\CFparam{stack sep}
@@ -355,6 +359,8 @@ It is important to understand that the placement of the entire molecule depends
 \chemfig{-B}\qquad
 \chemfig{A^1-B}/
 
+To set an arbitrary vertical offset or place a group of atoms on the baseline, use the \chevrons{baseline} key (see page~\pageref{baseline}).
+
 \section{Different types of bonds}
 For \CF, bonds between two atoms are one of nine types, represented by the characters \boxedfalseverb-, \boxedfalseverb=, \boxedfalseverb~, \boxedfalseverb>, \boxedfalseverb<, \boxedfalseverb{>:}, \boxedfalseverb{<:}, \boxedfalseverb{>|} and \boxedfalseverb{<|} :\label{types.liaisons}
 \begin{center}
@@ -1142,12 +1148,6 @@ Except in cases where the character "\verb|#|" is followed by a number between 1
 In this example, only \verb|#1| and \verb|#2| are understood as the arguments of the sub molecule \verb|\X|. The other "\verb|#|" are displayed as they are in the molecule (case of \verb|#3| and \verb|#4|) or understood as the character specifying the fine adjustment of the offset of the bonds.
 
 \section{Placement of Atoms}
-\subsection{First Atom}\label{premieratome}
-As explained on page~\pageref{first atom}, the first atom encountered (whether empty or not) is the one that is placed on the baseline, represented in gray on the examples of this manual. The choice of this first atom thus conditions the placement of all the others and often influences the placement of the whole molecule.
-
-\exemple{First atom}/\chemfig{H-[7]C(-[5]H)=C(-[1]H)-[7]H}\qquad
-\chemfig{C(-[3]H)(-[5]H)=C(-[1]H)-[7]H}/
-
 \subsection{Groups of atoms}\label{placementatomes}
 In a group of atoms, the atoms are placed one after the other in a well-established order:
 \begin{itemize}
@@ -1171,6 +1171,35 @@ In the example below whose code would be "\verb|\chemfig{A[:-60,,,3]BCDEF}|" the
 	\chemfig{A-[:-60,,,3]\0{B}{5}|\0{C}{4}|\0{D}{1}|\0{E}{2}|\0{F}{3}}
 \end{center}
 
+\subsection{Vertical alignment}\label{baseline}
+The \CFkey{baseline} is used to finely control the vertical placement of the molecule in relation to the baseline of the current paragraph.
+
+It is set to \CFval{0pt} by default, and in this case, the first atom encountered (whether empty or not) is the one placed on the baseline of the current paragraph, shown in gray on the examples in this manual. The choice of this first atom therefore conditions the placement of all the others, and often influences the placement of the entire molecule.
+
+\exemple{First atom}/\chemfig{H-[7]C(-[5]H)=C(-[1]H)-[7]H}\qquad
+\chemfig{C(-[3]H)(-[5]H)=C(-[1]H)-[7]H}/
+
+An arbitrary dimension can be specified to vertically shift the molecule by this value with the syntax \CFkv{baseline}{dimension}:
+
+\exemple{Vertical shift}/\chemfig{A(-[:-60]-[:30]C)-[:45]B}\qquad
+\chemfig[baseline=5pt]{A(-[:-60]-[:30]C)-[:45]B}\qquad
+\chemfig[baseline=-5pt]{A(-[:-60]-[:30]C)-[:45]B}/
+
+With the syntax \CFkv{baseline}{(name)} (the name must be in parentheses), we specify that the baseline of the molecule is at the node named \chevrons{name}. The name of the atom can be the one assigned automatically by \CF (of the form \Verb|n<a>-<b>|) or a name given by the user using the syntax \Verb|@{<name >}| (see page~\pageref{mecanismes-reactionnels}).
+
+\exemple*{Alignment on atoms}/Default alignment :      \chemfig{A(-[:-60]-[:30]C)-[:45]B}\medbreak
+Alignment on B:          \chemfig[baseline=(b.base)]{A(-[:-60]-[:30]C)-[:45]@{b}B}\medbreak
+Alignment on empty atom: \chemfig[baseline=(vide)]{A(-[:-60]@{vide}-[:30]C)-[:45]B}\medbreak
+Alignment on C:          \chemfig[baseline=(c.base)]{A(-[:-60]-[:30]@{c}C)-[:45]B}/
+
+It is possible to name \TIKZ nodes. Thus, if we want to vertically center several molecules on the current baseline, we set \CFkey{baseline} to \CFval{(current bounding box.center)}.
+
+\exemple*{Centered Alignment}/1) \chemfig{A-[:-45]B} et 2) \chemfig{B-[:45]C}\bigbreak
+
+\setchemfig{baseline=(current bounding box.center)}% vertical centering of the following molecules
+1) \chemfig{A-[:-45]B} et 2) \chemfig{B-[:45]C}
+\setchemfig{baseline=0pt}% back to default value/
+
 \subsection{Bonds between atoms}\label{liaisonentreatomes}
 A bond starting from an atom would, if extended, pass through the centre of its bounding box. The atom placed at the end of the bond has its center of its bounding box is in the extension of the bond. Therefore, a bond between two atoms extends through the centers of their bounding boxes, as shown in this example:
 \begin{center}
@@ -2446,6 +2475,7 @@ The commands created by \CF are:
 	\item \CFkv{cycle radius coeff}  {0.75}: shrinkage ratio of the circle or arc inside cycles
 	\item \CFkv{stack sep}           {1.5pt}: vertical gap between arguments of \verb-\chemabove- and \verb-\chembelow- macros
 	\item \CFkv{show cntcycle}       {false}: show rings numbers
+	\item \CFkv{baseline}            {0pt}: dimension or name of node to set the vertical position
 	\item \CFkv{debug}               {false}: show atoms ans groups of atoms
 	\item \CFkv{autoreset cntcycle}  {true}: reset ring counter at \verb|\chemfig| execution
 	\item \CFkv{compound style}      {{}}: style of compounds
-- 
cgit v1.2.3

