path: root/macros/latex/contrib/parskip/parskip.dtx

% \iffalse meta-comment
%
%% File: parskip.dtx
%%   (C) Copyright 1989 H.Partl, TU Wien
%%   (C) Copyright 2001 Robin Fairbairns
%%   (C) Copyright 2018-2021 Frank Mittelbach
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
%
% The development version of the bundle can be found below
%
%    https://github.com/FrankMittelbach/fmitex-parskip/
%
% for those people who are interested or want to report an issue.
%
%<*driver>
\documentclass{article}
\usepackage{doc,url}
\EnableCrossrefs
\CodelineIndex
\begin{document}
  \DocInput{parskip.dtx}
\end{document}
%</driver>
%
% \fi
%
%
% \newcommand\option[1]{\texttt{#1}}
% \newcommand\cs[1]{\texttt{\bslash#1}}
% \newcommand\pkg[1]{\textsf{#1}}
%
% \title{The \texttt{parskip} package\thanks{This is a
%    reimplementation of a package originally written by Hubert Partl
% in 1989 and later maintained by Robin Fairbairns.}}
% \author{Frank Mittelbach}
%
% \maketitle
%
% \begin{abstract}
%   The \pkg{parskip} package helps in implementing paragraph layouts
%   where the paragraphs are separated by a vertical space instead of
%   (or in addition to) indenting them.
%
%   The package can be used with any document class at any size.  By
%   default it produces the following paragraph layout: Zero
%   \cs{parindent} and non-zero \cs{parskip}. The stretchable glue in
%   \cs{parskip} helps \LaTeX{} in finding the best place for page
%   breaks.
%
% \end{abstract}
%
% \section{Introduction}
%
% Many \LaTeX{} constructs are internally built by using the paragraph
% mechanism even if technically there aren't text paragraphs. In most
% such cases the \LaTeX{} code handles indentation and suppressed it
% if necessary. But unfortunately this is normally not done for
% \cs{parskip} (as that is zero in the default layouts) and thus
% changing it will result in vertical spaces in unexpected places.
%
% This package attempts to fix the spacing in table of contents
% structures, list environments, and around display headings that would
% get screwed up by a positive \cs{parskip} value.
%
%   It is, however, is no more than quick fix; the `proper' way to
%   achieve effects as far-reaching as this is to create a new class.
%
% \subsection{History}
%
% This file was originally developed by Hubert Partl in 1989 (i.e.,
% for \LaTeX\,2.09) to provide a somewhat crude solution to an
% existing problem in case no proper document class (back then called
% document style) support was available.
%
% About ten years later Robin Fairbairns picked up the orphaned
% package and his version was then the one available for \LaTeXe{}
% during the next 15\textsuperscript{+} years.
%
% Finally, while working on the next edition of the \LaTeX{} Companion
% the current author did a reimplementation, that added support for TOC
% data and heading structures. Also a few additional key/value options
% were added to make the package more useful. It still is and will
% remain an inferior choice compared to a properly designed document
% class. But it offers a starting point if nothing is around.
%
%
%
% \section{The user interface}
%
% The \pkg{parskip} package doesn't offer any document user commands
% and just needs loading with \cs{usepackage}.
%
%
% \subsection{Options to customize the package}\label{sec:options}
%
% All of the package options are implemented as key/value options.
% \begin{description}
% \item[\option{skip}]
%    With the package option \texttt{skip} it is possible to explicitly
%    specify the vertical space between paragraphs. If the option is
%    not given (or given without a value) then \verb=.5\baselineskip=
%   plus \texttt{2pt} of stretch is assumed.
% \item[\option{tocskip}]
%    By default the \cs{parskip} is zero within \cs{tableofcontents}
%    and similar lists, regardless of its value elsewhere. With the
%    option \texttt{tocskip} it can be given a different value. If
%    used without an explicit value you get the same \cs{parskip} as elsewhere
%    within these lists.
% \item[\option{indent}]
%    With the package option \texttt{indent} it is possible to explicitly set
%    the paragraph indentation. Using this option without a value keeps the
%    document class indentation unchanged, if it is specified with a
%    value then that value is used. If the package is loaded without
%    this option
%    the indentation is set
%    to zero.
% \item[\option{parfill}]
%    With package option \texttt{parfill}, the package also adjusts
%    \cs{parfillskip} to impose a minimum space at the end of
%    the last line of a paragraph. If specified without a value then
%    \texttt{30pt} are assumed, if a value is given that forms the minimum.
% \end{description}
%
%
% \section{Differences to the original package}
%
% If the package is used without any options or just with the option
% \option{parfill} it behaves like the earlier version, except that now
% the spacing around headings is also adjusted (not adding extra
% \cs{parskip}).  If this is not desirable when processing an  old
% document it can be avoided by explicitly
% requesting version \texttt{v1} as follows:
% \begin{quote}
%   \verb/\usepackage{parskip}[=v1]/
% \end{quote}
% Of course, the new options, etc.\ are then also not available.
%
%
%
% \section{Sources, bugs and issues}
%
% The official production version is available from CTAN.
% The latest (development) sources are maintained at GitHub at:
% \begin{quote}
%   \url{https://github.com/FrankMittelbach/fmitex-parskip}
% \end{quote}
% In case of problems with the package you can report them at
% \begin{quote}
%   \url{https://github.com/FrankMittelbach/fmitex-parskip/issues}
% \end{quote}
% Please provide a minimal test example that can be run and doesn't
% use packages not in a standard \LaTeX{} distribution (and only those
% that are needed to show the issue).
%
% \StopEventually{}
%
%
%
%
% \section{The Implementation}
%
% \setcounter{StandardModuleDepth}{1}  ^^A everything is inside a module
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%  \subsection{The main implementation part}
%
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[2018-04-01]

\DeclareRelease       {v1}{2001-04-09}{parskip-2001-04-09.sty}
\DeclareCurrentRelease{v2}{2018-08-24}
%    \end{macrocode}
%
%    \begin{macrocode}
\ProvidesPackage{parskip}[2021-03-14 v2.0h non-zero parskip adjustments]
%    \end{macrocode}
%
%
%
% \subsubsection{Option handling}
%
% Here we define all option keys for use as package options:
%    \begin{macrocode}
\RequirePackage{kvoptions}
\SetupKeyvalOptions{family=parskip,prefix=parskip@}
%    \end{macrocode}
%
%   The key \option{indent} defines the amount of indentation for each
%   paragraph. If not given the indentation will be zero (default) and
%   if given without a value then the outer value from the document
%   class will get used, otherwise the given value is used.
%    \begin{macrocode}
\DeclareStringOption[0pt]{indent}[\parindent]
%    \end{macrocode}
%
%   The key \option{parfill} defines a minimum amount of white space
%   that should be left in the last line. By default the last line can
%   get completely fill up. If given without a value the default (as
%   before) is to require a minimum of \texttt{30pt}, otherwise the
%   given value is used.
%    \begin{macrocode}
\DeclareStringOption[0pt]{parfill}[30pt]
%    \end{macrocode}
%
%   The key \option{skip} defines the vertical separation between
%   paragraphs. If not given the default (as before) is to use half a
%   \cs{baselineskip} plus a stretch of \texttt{2pt} to add some
%   flexibility. If given, one need to provide an explicit value which
%   is then used as a separation (and it needs to contain any extra
%   stretch if that is wanted, i.e., there is no extra stretch added
%   in this case). 
% \changes{v2.0f}{2020/06/15}{Allow \texttt{skip} key without value
%          without a package error (gh/14)}
%    \begin{macrocode}
\DeclareStringOption{skip}[]
%    \end{macrocode}
%
%    The key \option{tocskip} defines the vertical separation inside the lists
%    \cs{tableofcontents}, \cs{listoffigures} and \cs{listoftables}. By
%    default there is no extra separatation (i.e., \texttt{0pt}). If
%    specified without a value the standard \cs{parskip} is used,
%    otherwise the given value.
%    \begin{macrocode}
\DeclareStringOption[0pt]{tocskip}[\parskip]
%    \end{macrocode}
%
%   Execute any package options:
%    \begin{macrocode}
\ProcessKeyvalOptions*
%    \end{macrocode}
%
%    So now we can evaluate the given options and adjust the
%    parameter settings:
%    \begin{macrocode}
\ifx\parskip@skip\@empty
%    \end{macrocode}
%    If no \option{skip} was given (or it was empty) set \cs{parskip}
%    to half of \verb=.5\baselineskip= plus \texttt{2pt} stretch. Stretch
%    or shrink inside \cs{baselineskip} is ignored in this case.
%    \begin{macrocode}
  \parskip=.5\baselineskip plus 2pt\relax
\else
%    \end{macrocode}
%    Otherwise set it to the specified value:
% \changes{v2.0c}{2019/02/16}{Support calc by using \cs{setlength}
%                             for assignments}
%    \begin{macrocode}
  \setlength\parskip\parskip@skip
\fi
%    \end{macrocode}
%    Setting \cs{parfillskip} was suggested by Donald Arseneau at some
%    point on comp.text.tex:
%    \begin{macrocode}
\setlength\parfillskip\parskip@parfill
\advance\parfillskip 0pt plus 1fil\relax
%    \end{macrocode}
%    \cs{parindent} gets whatever was specified. If the key was given
%    without an option this will essentially reassign the now ``current'' value.
%    \begin{macrocode}
\setlength\parindent\parskip@indent
%    \end{macrocode}
%
%
%
% \subsection{Handling document elements}
%
% Setting up a non-zero \cs{parskip} has some side-effects in document
% elements such as lists or headings etc. Here we try to keep these
% side-effects somewhat under control.
%
% We make use of the \pkg{etoolbox} package to do patching.
%    \begin{macrocode}
\RequirePackage{etoolbox}
%    \end{macrocode}
%
% \subsubsection{Lists}
%
%    To accompany this, the vertical spacing in the list environments is changed
%    to use the same as \cs{parskip} in all relevant places (for
%    \cs{normalsize} only), i.e.
%\begin{verbatim}
%   \parsep = \parskip
%   \itemsep = \z@ % add nothing to \parskip between items
%   \topsep = \z@ % add nothing to \parskip before first item
%\end{verbatim}
%
%    However, if the user explicitly asked for a zero parskip (via the
%    \option{skip} option) we
%    shouldn't do this but rather keep the default list settings, so
%    we better check for this.
%
%    \begin{macrocode}
\ifdim \parskip > 0pt
%    \end{macrocode}
%    
%    \begin{macrocode}
  \def\@listI{\leftmargin\leftmargini
     \topsep\z@ \parsep\parskip \itemsep\z@}
  \let\@listi\@listI
  \@listi
%    \end{macrocode}
%    
%    \begin{macrocode}
  \def\@listii{\leftmargin\leftmarginii
     \labelwidth\leftmarginii\advance\labelwidth-\labelsep
     \topsep\z@ \parsep\parskip \itemsep\z@}
%    \end{macrocode}
%    
%    \begin{macrocode}
  \def\@listiii{\leftmargin\leftmarginiii
      \labelwidth\leftmarginiii\advance\labelwidth-\labelsep
      \topsep\z@ \parsep\parskip \itemsep\z@}
%     
% and finally ...
%   \partopsep = \z@ % don't even add anything before first item (beyond 
%                    % \parskip) even if the list is preceded by a blank line
  \partopsep=\z@
\fi
%    \end{macrocode}
%
%
% \subsubsection{TOCs and similar lists}
%
% Within a table of contents or a list of figures we don't want any
% additional vertical spacing just because the individual lines in
% such a list are implemented as one-line paragraphs. So we locally
% set the \cs{parskip} to zero by default. Should be really something that is
% done already in \LaTeX{}.
% \changes{v2.0e}{2020/05/19}{Fix space at start of \cs{@starttoc} (gh/12)}
%    \begin{macrocode}
\patchcmd\@starttoc
    {\begingroup \makeatletter}
    {\begingroup \makeatletter
%    \end{macrocode}
%    Just setting \cs{parskip} to zero as it was done in the original
%    version of the package, does not always work. If the list starts
%    out with an ordinary paragraph (and not with \cs{addvspace} as it
%    usually does) we will get a zero \cs{parskip} but the heading
%    above assumes we get the normal \cs{parskip} and has therefore
%    removed that amount from its own vertical skip. As long as the
%    parskip value is not too large people didn't notice that heading
%    and list moved closer to each other but if you use, say,
%    \texttt{[skip=20pt]} you will even see an overlap.
%
%    We therefore do the following: we look at the last skip, undo it
%    and then issue a skip that is equal to \cs{parskip} +
%    \cs{lastskip}.
%     This way the skip seen by any following code has the right value
%    which is important for \cs{addvspace} calulations. Only then we
%    locally set \cs{parskip} to zero or rather to
%    \cs{parskip@tocskip}, the parameter that the user can set through
%    an option.
% \changes{v2.0e}{2020/05/19}{Add \texttt{tocskip} option}
%    \begin{macrocode}
      \skip@\lastskip
      \advance\skip@\parskip
      \vskip-\lastskip
      \vskip\skip@
      \parskip\parskip@tocskip}
    {}{\typeout{Couldn't patch \string\@starttoc}}
%    \end{macrocode}
%
%
%
%
% \subsubsection{Standard headings}
%
%  For the same reason we don't want to see an additional \cs{parskip}
% being added before and after a display heading, so we subtract its
% value (in two places):
%    \begin{macrocode}
\patchcmd\@startsection
    {\addvspace\@tempskipa}
    {\advance\@tempskipa-\parskip\addvspace\@tempskipa}
    {}{\typeout{Couldn't patch \string\@startsection}}
%    \end{macrocode}
%
%    \begin{macrocode}
\patchcmd\@xsect
    {\vskip\@tempskipa}
    {\advance\@tempskipa-\parskip\vskip\@tempskipa}
    {}{\typeout{Couldn't patch \string\@xsect}}
%    \end{macrocode}
%
%
%
%
% \subsubsection{\pkg{titlesec} headings}
%
% If \pkg{titlesec} is used then headings are built using different
% commands and we have to cancel the \cs{parskip} there. The principle
% is the same. Of course, the patching should only happen if that
% package really got loaded, so we defer it to the start of the
% document and test for it:
%    \begin{macrocode}
\AtBeginDocument{%    
\ifx\ttl@straight@ii\@undefined\else  % titlesec got loaded
\patchcmd\ttl@straight@ii
    {\addvspace{\@tempskipa}}%
    {\advance\@tempskipa-\parskip \addvspace\@tempskipa}%
    {}{\typeout{Couldn't patch \string\ttl@straight@ii}}%
\patchcmd\ttl@straight@ii
    {\vspace{\@tempskipb}}%
    {\advance\@tempskipb-\parskip \vspace\@tempskipb}%
    {}{\typeout{Couldn't patch \string\ttl@straight@ii}}%
\patchcmd\ttl@part@ii
    {\vspace*{\@tempskipa}}%
    {\advance\@tempskipa-\parskip \vspace*\@tempskipa}%
    {}{\typeout{Couldn't patch \string\ttl@part@ii}}%
\patchcmd\ttl@part@ii
    {\vspace{\@tempskipb}}%
    {\advance\@tempskipb-\parskip \vspace\@tempskipb}%
    {}{\typeout{Couldn't patch \string\ttl@part@ii}}%
\patchcmd\ttl@page@ii
    {\vspace*{\@tempskipa}}%
    {\advance\@tempskipa-\parskip \vspace*\@tempskipa}%
    {}{\typeout{Couldn't patch \string\ttl@page@ii}}%
\patchcmd\ttl@page@ii
    {\vspace{\@tempskipb}}%
    {\advance\@tempskipb-\parskip \vspace\@tempskipb}%
    {}{\typeout{Couldn't patch \string\ttl@page@ii}}%
\fi}    
%    \end{macrocode}
%
%
%
% \subsubsection{\pkg{amsthm} theorems}
%
% The \pkg{amsthm} package is one of the few packages that make an
% explicit correction for \cs{parskip} which isn't any longer adequate
% if this \pkg{parskip} package is loaded. We therefore remove that
% setting from the package if it was loaded.
% \changes{v2.0b}{2018/09/17}{Support \cs{amsthm} (sx/450551)}
%    \begin{macrocode}
\AtBeginDocument{%    
\ifx\deferred@thm@head\@undefined\else  % amsthm got loaded
\patchcmd\deferred@thm@head
  {\addvspace{-\parskip}}{}%
  {}{\typeout{Couldn't patch \string\deferred@thm@head!}}%
\fi} 
%    \end{macrocode}
%
%
% \subsection{Closing shop}
%

%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% \Finale
%
\endinput