summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/parskip/parskip.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/parskip/parskip.dtx
Initial commit
Diffstat (limited to 'macros/latex/contrib/parskip/parskip.dtx')
-rw-r--r--macros/latex/contrib/parskip/parskip.dtx421
1 files changed, 421 insertions, 0 deletions
diff --git a/macros/latex/contrib/parskip/parskip.dtx b/macros/latex/contrib/parskip/parskip.dtx
new file mode 100644
index 0000000000..731cb2a9f4
--- /dev/null
+++ b/macros/latex/contrib/parskip/parskip.dtx
@@ -0,0 +1,421 @@
+% \iffalse meta-comment
+%
+%% File: parskip.dtx
+%% (C) Copyright 1989 H.Partl, TU Wien
+%% (C) Copyright 2001 Robin Fairbairns
+%% (C) Copyright 2018-2019 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 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/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}[2019-01-16 v2.0c 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:
+% \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. 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}
+%
+%
+%
+% \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