summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/parskip/parskip.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-09-12 21:53:04 +0000
committerKarl Berry <karl@freefriends.org>2018-09-12 21:53:04 +0000
commit6d5c17e5612d0bdedd3bb20cca991f933490e144 (patch)
tree201dc5798b901dda7cf1e98ddf3c6b31a2ab4427 /Master/texmf-dist/source/latex/parskip/parskip.dtx
parent438247783b0c69b215c163605b2898510758a7b3 (diff)
parskip (12sep18)
git-svn-id: svn://tug.org/texlive/trunk@48650 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/parskip/parskip.dtx')
-rw-r--r--Master/texmf-dist/source/latex/parskip/parskip.dtx402
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