Tweakable orphaned sections - revive old PR (#231)

* introduce different first and lastname styles.

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

* introduce \cvsectionstretchability and \cvsubsectionstretchability

* set default stretchability to 0.9\baselineskip

* add fix orphaned section notice to changelog

---------

Co-authored-by: David <forenkram@gmx.de>

CHANGELOG

@@ -7,6 +7,13 @@ version next
 - Fix spacing between first and last name again (#220)
 - Make header details flush against sides for casual, classic, and contemporary
   styles (#229)
+- partially fix orphaned section headers for singualar use of \section and \subsection
+  commands and give users the new adjustable lengths \cvsectionstretchability
+  and \subsectionstretchability. In case \section and \subsection are used
+  directly one after the other, an orphaned section header might still occur. 
+  This is structural and should be solved by \newpage instead of increasing 
+  \cvsectionstretchability (#10/#226).
+
 
 version 2.4.1 (18 Jul 2024)
 - Fix commons/colors.tex not found in package (#194)

moderncv.cls

@@ -479,6 +479,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

@@ -74,7 +74,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}%
@@ -82,6 +92,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

@@ -107,7 +107,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}%
@@ -123,6 +132,7 @@
   \par\nobreak\addvspace{1ex}\@afterheading}
 
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvsubsectionstretchability}% avoid orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}%
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyiv.sty

@@ -69,7 +69,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}%
@@ -77,6 +86,7 @@
   \par\nobreak\addvspace{1ex}\@afterheading}
 
 \RenewDocumentCommand{\subsection}{sm}{%
+  \@cvneedspace{\cvsubsectionstretchability}% avoid orphaned sections
   \par\addvspace{1ex}%
   \phantomsection{}%
   \addcontentsline{toc}{subsection}{#2}%

moderncvbodyv.sty

@@ -72,8 +72,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}%
@@ -83,6 +93,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%