Merge branch 'orphaned_section_fix' into update_documentation

partially fix orphaned section problem by introducing stretchability for
both \section and \subsection commands individually.
Does not solve orphaned \section if \section{}\subsection{} are used
immedialtelly one after the other. This situation is better solved by
a \newpage command in my opinion instead of increasing the
stretchability for all \section commands by default, leading to possible
waste of space (and odd looking large spaces at end of pages).

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},
 }
 
@@ -709,6 +709,54 @@ 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}
+\todox{explain things properly}
+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. 
+
+\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 
@@ -721,6 +769,8 @@ CV, add the following:%
   \end{center}
 \end{lstlisting}
 
+
+
 \section{Implementation details}
 \label{section:implementationDetails}
 

moderncv.cls

@@ -429,6 +429,36 @@
 \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
+% the stretchabilities are zero by default and are only there to be changed 
+% by the user if needed.
+\@initializelength{\cvsectionstretchability}
+\@initializelength{\cvsubsectionstretchability}
+% set the default stretchability.
+\setlength{\cvsectionstretchability}{.9\baselineskip}
+\setlength{\cvsubsectionstretchability}{.9\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
+\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}
+
+% leave the stretchability zero by default
+% \setlength{\cvsectionstretchability}{0.0pt}
+% \setlength{\cvsubsectionstretchability}{0.0pt}
+% 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{\cvsectionstretchability}% avoid 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{\cvsubsectionstretchability}% avoid orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyiii.sty

@@ -102,7 +102,16 @@
   % regular lengths
   \setlength{\parskip}{0\p@}}
 
+% leave the stretchability zero by default
+% \setlength{\cvsectionstretchability}{0.0pt}
+% \setlength{\cvsubsectionstretchability}{0.0pt}
+% 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{\cvsectionstretchability}% avoid orphaned sections
   \par\addvspace{2.5ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{section}{#2}%
@@ -118,6 +127,7 @@
   \par\nobreak\addvspace{1ex}\@afterheading}
 
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvsubsectionstretchability}% avoid orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}%
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyiv.sty

@@ -63,7 +63,16 @@
   % regular lengths
   \setlength{\parskip}{0\p@}}
 
+% leave the stretchability zero by default
+% \setlength{\cvsectionstretchability}{0.0pt}
+% \setlength{\cvsubsectionstretchability}{0.0pt}
+% 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{\cvsectionstretchability}% avoid orphaned sections
   \par\addvspace{2.5ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{section}{#2}%
@@ -71,6 +80,7 @@
   \par\nobreak\addvspace{1ex}\@afterheading}
 
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvsubsectionstretchability}% avoid orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}%
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyv.sty

@@ -67,8 +67,18 @@
   % regular lengths
   \setlength{\parskip}{0\p@}}
 
+% leave the stretchability zero by default
+% \setlength{\cvsectionstretchability}{0.0pt}
+% \setlength{\cvsubsectionstretchability}{0.0pt}
+% 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}
+
 \@initializeif{\if@aftersection}\@aftersectionfalse%
 \RenewDocumentCommand{\section}{sm}{%
+  \@cvneedspace{\cvsectionstretchability}% avoid orphaned sections
   \addvspace{2.5ex}%
   \phantomsection{}% reset the anchor for hyperrefs
   \addcontentsline{toc}{section}{#2}%
@@ -77,6 +87,7 @@
 
 %\@initializeif{\if@aftersubsection}\@aftersubsectionfalse%
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvsubsectionstretchability}% avoid 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%