fix orphaned section headers (needs testing). Closes #10.

CHANGELOG

@@ -1,4 +1,5 @@
 Release: next
+- fix orphaned section headers (needs testing). Probably closes #10. 
 - Systematize colors and make them user adjustable. See documentation for details. 
   this requires the \moderncvcolor to be issued BEFORE \moderncvstyle.
 - all styles: make the head options 'details' and 'nodetails' available to the user. (previously they were hidden). Olystyle does not respond too well to nodetails.

manual/moderncv_userguide.tex

@@ -88,13 +88,13 @@
 %   frame=L,
   emph={cvitem,cventry,cvdoubleentry,cvdoubleitem,moderncvstyle,moderncvcolor,%
   cvskill,cvskilllegend,cvskillplainlegend,cvskillhead,cvskillentry,nopagenumbers,%
-  name,address,email,link,social,phone,homepage,extrainfo,photo,quote},%
+  name,address,email,link,social,phone,homepage,extrainfo,photo,quote,section,subsection,setlength,NewDocumentCommand},%
   emphstyle={\color{cvblue}},%
   emph={[2]familydefault,sfdefault,rmdefault,inputenc,moderncv,document,bibliographyitemlabel,%
   addresssymbol,mobilephonesymbol,fixedphonesymbol,faxphonesymbol,emailsymbol,homepagesymbol,linkedinsocialsymbol,%
   xingsocialsymbol,twittersocialsymbol,githubsocialsymbol,gitlabsocialsymbol,%
   stackoverflowsocialsymbol,bitbucketsocialsymbol,skypesocialsymbol,orcidsocialsymbol,researchgatesocialsymbol,%
-  researcheridsocialsymbol,telegramsocialsymbol,googlescholarsocialsymbol},%
+  researcheridsocialsymbol,telegramsocialsymbol,googlescholarsocialsymbol,cvstretchability},%
   emphstyle={[2]\color{cvblue!60!cvgrey}\bfseries},
 }
 
@@ -721,6 +721,52 @@ CV, add the following:%
   \end{center}
 \end{lstlisting}
 
+\subsubsection{Orphaned sections}
+If \latex~ breaks pages just after \code{\\section} or \code{\\subsection} commands, try adjusting
+the the stretchability of the page
+\begin{lstlisting}
+  \setlength{\cvstretchability}{<length>},
+\end{lstlisting}
+for example
+\begin{lstlisting}
+  \setlength{\cvstretchability}{\baselineskip} % or
+  % \setlength{\cvstretchability}{100pt},
+\end{lstlisting}
+in the document. It tells \latex that it needs approximately \Code{<length>} extra length after 
+section and subsection commands. 
+
+\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{\\cvstretchability}, 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}
+
+
+
 \section{Implementation details}
 \label{section:implementationDetails}
 

moderncv.cls

@@ -429,6 +429,30 @@
 \newcommand*{\@moderncvstrut}[2]{%
   \rule[-#1]{0pt}{#2}}
 
+% custom needspace command to avoid orphaned sections
+% adapted from the explanations given on 
+% https://tex.stackexchange.com/questions/348994/understanding-needspace
+\@initializelength{\cvstretchability}
+% 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
+\NewDocumentCommand\withinstretchpenalty{}{0}
+% must be between -100 and 9999. The higher the less likely a page break will occur.
+\NewDocumentCommand\poststretchpenalty{}{9999}
+% command intended to use with section definitions to avoid orphaned sections. (Pagebreak bewteen 
+% \section{} and cv content e.g. \cvitem{}. 
+% usage \@cvneedspace{<length>} preferably \cvneedspace{\cvstretchability} to allow the user 
+% to adapt as needed.
+\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
+}
 
 %-------------------------------------------------------------------------------
 %                resume design commands definitions

moderncvbodyi.sty

@@ -69,7 +69,17 @@
 \@initializelength{\baseletterheight}
 \settoheight{\baseletterheight}{\sectionstyle{o}}
 \setlength{\baseletterheight}{\baseletterheight-0.95ex}
+
+% Set \cvstretchability to the height of E for Experience
+% \settoheight{\cvstretchability}{\sectionstyle{IT}+10ex}
+\setlength{\cvstretchability}{.9\baselineskip}%3\baselineskip
+% 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
+\RenewDocumentCommand\withinstretchpenalty{}{0}
+% must be between -100 and 9999. The higher the less likely a page break will occur.
+% \RenewDocumentCommand\poststretchpenalty{}{9999}
 \RenewDocumentCommand{\section}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   \par\addvspace{2.5ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{section}{#2}%
@@ -77,6 +87,7 @@
   \par\nobreak\addvspace{1ex}\@afterheading}% to avoid a pagebreak after the heading
 
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyiii.sty

@@ -102,7 +102,19 @@
   % regular lengths
   \setlength{\parskip}{0\p@}}
 
+\@initializelength{\baseletterheight}
+\settoheight{\baseletterheight}{\sectionstyle{o}}
+\setlength{\baseletterheight}{\baseletterheight-0.95ex}
+% Set \cvstretchability to the height of E for Experience
+% \settoheight{\cvstretchability}{\sectionstyle{E}}
+\setlength{\cvstretchability}{\baseletterheight}%3\baselineskip
+% 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
+\RenewDocumentCommand\withinstretchpenalty{}{40}
+% must be between -100 and 9999. The higher the less likely a page break will occur.
+% \RenewDocumentCommand\poststretchpenalty{}{9999}
 \RenewDocumentCommand{\section}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   \par\addvspace{2.5ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{section}{#2}%
@@ -118,6 +130,7 @@
   \par\nobreak\addvspace{1ex}\@afterheading}
 
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}%
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyiv.sty

@@ -63,7 +63,19 @@
   % regular lengths
   \setlength{\parskip}{0\p@}}
 
+\@initializelength{\baseletterheight}
+\settoheight{\baseletterheight}{\sectionstyle{o}}
+\setlength{\baseletterheight}{\baseletterheight-0.95ex}
+% Set \cvstretchability to the height of E for Experience
+% \settoheight{\cvstretchability}{\sectionstyle{E}}
+\setlength{\cvstretchability}{\baseletterheight}%3\baselineskip
+% 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
+\RenewDocumentCommand\withinstretchpenalty{}{40}
+% must be between -100 and 9999. The higher the less likely a page break will occur.
+% \RenewDocumentCommand\poststretchpenalty{}{9999}
 \RenewDocumentCommand{\section}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   \par\addvspace{2.5ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{section}{#2}%
@@ -71,6 +83,7 @@
   \par\nobreak\addvspace{1ex}\@afterheading}
 
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}%
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyv.sty

@@ -67,8 +67,21 @@
   % regular lengths
   \setlength{\parskip}{0\p@}}
 
+\@initializelength{\baseletterheight}
+\settoheight{\baseletterheight}{\sectionstyle{o}}
+\setlength{\baseletterheight}{\baseletterheight-0.95ex}
+% Set \cvstretchability to the height of E for Experience
+% \settoheight{\cvstretchability}{\sectionstyle{E}}
+\setlength{\cvstretchability}{\baseletterheight}%3\baselineskip
+% 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
+\RenewDocumentCommand\withinstretchpenalty{}{40}
+% must be between -100 and 9999. The higher the less likely a page break will occur.
+% \RenewDocumentCommand\poststretchpenalty{}{9999}
+
 \@initializeif{\if@aftersection}\@aftersectionfalse%
 \RenewDocumentCommand{\section}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   \addvspace{2.5ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{section}{#2}%
@@ -77,6 +90,7 @@
 
 %\@initializeif{\if@aftersubsection}\@aftersubsectionfalse%
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvstretchability}% avoit orphaned sections
   %\addvspace{1ex}%
   \vspace*{-\arrayrulewidth}% HACK; I don't understand where the space is coming from, nor what it's exact value is :(
   \if@aftersection%