From 26eb39fbd617435c57bfba89e3c0af3e9b3d0d5c Mon Sep 17 00:00:00 2001
From: David <forenkram@gmx.de>
Date: Thu, 18 Feb 2021 16:31:05 +0100
Subject: [PATCH] explain orphaned section problem

---
 manual/moderncv_userguide.tex | 71 +++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/manual/moderncv_userguide.tex b/manual/moderncv_userguide.tex
index 48cfd67..cb487b1 100644
--- a/manual/moderncv_userguide.tex
+++ b/manual/moderncv_userguide.tex
@@ -716,6 +716,77 @@ The labels used in \Code{itemize} environments or the \Moderncv macros \code{cvl
 This will leave the definitions of \Code{itemize} environments untouched.
 \end{itemize}
 
+\subsection{Pagebreaks and orphaned section headers}
+If \latex\ breaks pages just after \code{\\section} or \code{\\subsection} commands, try adjusting
+the the stretchability of the page
+\begin{lstlisting}
+  \setlength{\cvsectionstretchability}{<length>} %
+  \setlength{\cvsubsectionstretchability}{<length>},
+\end{lstlisting}
+for example
+\begin{lstlisting}
+  \setlength{\cvsectionstretchability}{\baselineskip} % or
+  % \setlength{\cvsubsectionstretchability}{100pt},
+\end{lstlisting}
+in the document. It tells \latex\ that it needs approximately \Code{<length>} extra length after 
+section and subsection commands. 
+
+By default,
+\begin{lstlisting}
+  \setlength{\cvsectionstretchability}{.9\baselineskip}
+  \setlength{\cvsubsectionstretchability}{.9\baselineskip}
+\end{lstlisting}
+
+is set in the package. 
+This should solve orphaned \Code{\\section} and \Code{\\subsection} commands that are used alone for most people. 
+However \latex\ does not check for content. So in case of using
+\begin{lstlisting}
+  \section{blub}
+  \subsection{blubblub}
+\end{lstlisting}
+directly one after the other the subsection might be unorphaned leaving enough space on the previous page for \latex\ not to also break \Code{\\section\{blub\}} to the new page. 
+One way of solving this is to increase \Code{\\cvsectionstretchability} to an artificially high value to force the break of the section header.
+However, this will change the behaviour for all \Code{\\section} commands in your CV and might cause a page break in a situation where it would not have been necessary (down the line on another page), e.g. in a case like
+\begin{lstlisting}
+  \section{blub}
+  \cvitem{blubblub}
+\end{lstlisting}
+
+in which the item previously would have fit on the page. 
+It is therefore recommended to force the page break manually by a \newpage command in this special case.
+
+\paragraph{Experts only:}
+Internally a custom needspace command is being used: 
+
+\begin{lstlisting}
+  \NewDocumentCommand\@cvneedspace{m}{%
+    \begingroup
+      \setlength{\dimen@}{#1}%
+      \vskip\z@\@plus\dimen@
+      \penalty \withinstretchpenalty\vskip\z@\@plus -\dimen@
+      \vskip\dimen@
+      \penalty \poststretchpenalty%
+      \vskip -\dimen@
+      \vskip\z@skip % hide the previous |\vskip| from |\addvspace|
+    \endgroup
+  }
+\end{lstlisting}
+This means that alternatively to setting \Code{\\cvsectionstretchability} and/or \code{\\cvsubsectionstretchability} , penalties for pagebreaks can be influenced by redefining the internal penalties:
+\begin{lstlisting}
+ % must be between -100 and 9999. The higher the less likely a page break will occur.
+% This is where the page break should occur, so this number should not bee too high
+ \renewcommand{\withinstretchpenalty}{<-100...9999>}
+% must be between -100 and 9999. The higher the less likely a page break will occur.
+ \renewcommand{\poststretchpenalty}{<-100...9999>}.
+\end{lstlisting}
+The defaults are \Code{\\poststretchpenalty = 9999} and \Code{\\withinstretchpenalty = 0}. 
+The penalties must be between -100 and 9999. The higher the value the less likely a page break will occur. A good explanation of this can be found under 
+\begin{center}
+  \url{https://tex.stackexchange.com/questions/348994/understanding-needspace}
+\end{center}
+
+
+
 \subsection{Tips and Tricks}
 \subsubsection{Legal disclaimer at the end of CV}
 Some countries (e.g. Italy) require to add the permission to treat the personal data contained in the CV. This can be achieved by the command \code{\\vfill}. At the end of the last entry to your