parskip (12sep18)

git-svn-id: svn://tug.org/texlive/trunk@48650 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 402 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/parskip/parskip.dtx b/Master/texmf-dist/source/latex/parskip/parskip.dtx
new file mode 100644
index 00000000000..be894e39a8a
--- /dev/null
+++ b/Master/texmf-dist/source/latex/parskip/parskip.dtx
@@ -0,0 +1,402 @@
+% \iffalse meta-comment
+%
+%% File: parskip.dtx
+%%   (C) Copyright 1989 H.Partl, TU Wien
+%%   (C) Copyright 2001 Robin Fairbairns
+%%   (C) Copyright 2018 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/
+%
+% 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{indent}]
+%    With the package option \texttt{indent} it is possible to explicitly
+%    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 that forms the minimum.
+% \end{description}
+%
+%
+% \section{Differences to the original package}
+%
+% If the package us 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/tree/parskip/parskip}
+% \end{quote}
+% In case of problems with the package you can report them at
+% \begin{quote}
+%   \url{https://github.com/FrankMittelbach/fmitex/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 as little
+% as possible 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}[2018-08-24 v2.0a 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).
+%    \begin{macrocode}
+\DeclareStringOption{skip}
+%    \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 \verb=.5\baselineskip= plus \texttt{2pt} stretch. This has to
+%    be done in 2 steps as \cs{baselineskip} might already contain a stretch.
+%    \begin{macrocode}
+  \parskip.5\baselineskip
+  \advance\parskip 0pt plus 2pt\relax
+\else
+%    \end{macrocode}
+%    Otherwise set it to the specified value:
+%    \begin{macrocode}
+  \parskip\parskip@skip\relax
+\fi
+%    \end{macrocode}
+%    Setting \cs{parfillskip} was suggested by Donald Arseneau at some
+%    point on comp.text.tex:
+%    \begin{macrocode}
+\parfillskip \parskip@parfill\relax
+\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}
+\parindent\parskip@indent\relax
+%    \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. Should be really something that is
+% done already in \LaTeX{}.
+%    \begin{macrocode}
+\patchcmd\@starttoc
+    {\begingroup \makeatletter}
+    {\begingroup \makeatletter \parskip\z@}
+    {}{\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}
+%
+%
+%
+% \subsection{Closing shop}
+%
+
+%    \begin{macrocode}
+%<*package>
+%    \end{macrocode}
+%
+% \Finale
+%
+\endinput