Skip to content

Commit

Permalink
several changes for first release
Browse files Browse the repository at this point in the history
  • Loading branch information
Markus Kohm committed Aug 4, 2023
1 parent 299fb13 commit 04c1ec0
Show file tree
Hide file tree
Showing 3 changed files with 122 additions and 82 deletions.
102 changes: 64 additions & 38 deletions setspaceenhanced/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Copyright © 2008–2023 Markus Kohm

Release: unreleased
Release: 2023-08-04 v1.0

License: LPPL 1.3c

Expand All @@ -25,7 +25,7 @@ The Current Maintainer and author of this work is Markus Kohm.

----------------------------------------------------------------------------

# ABSTRACT
# Abstract

For several years
[KOMA-Script](https://www.sourceforge.net/project/koma-script) provided a
Expand All @@ -41,33 +41,59 @@ replacements for the original packages they were intended to improve. Package
features and improvements by patching package
[`setspace`](https://ctan.org/pkg/setspace).

# Unpacking and Installation for Developers and Distributors
# Unpacking and Installation for Users

Distributors should be aware that there is no official release of the new
standalone packages `setspaceenhanced` yet. There is only a developer
version. The first official release will hopefully come with the next
KOMA-Script release.
If you are a user, you should wait until all the packages has been added to
your preferred TeX distribution. Then you can use the package manager of your
TeX distribution to install all the packages.

*For now, distributors should just ignore this package.*
# Unpacking for Distributors

Developers can use `l3build` to unpack and install all files and even the
documentation. But this cannot be done with a single `l3build` run for all of
the packages. Instead you have to go to the sub-folder of the package you want
to install and run
Distributors should download the [distribution from
CTAN](https://www.ctan.org/pkg/setspaceenhanced). This consists in:

l3build install

to locally install the package of the sub-folder without manuals, or run
* `setspaceenhanced.dtx`
* `README.md`
* `LICENSE.md`
* `setspaceenhanced.pdf`

l3build install --full
If distributors also want to distribute `setspaceenhanced.sty`, they can
unpack it using

tex setspaceenhanced.dtx

to locally install the package of the sub-folder with manuals.
Note, that you have to use `tex` not `latex`, `pdflatex`, `xelatex` or
`lualatex`!

# Unpacking and Installation for Users
Note also, that a legal distribution consists at least in:

If you are a user, you should wait until all the packages has been added to
your preferred TeX distribution. Then you can use the package manager of your
TeX distribution to install all the packages.
* `setspaceenhanced.dtx`
* `README.md`

The following files are optionally, but must not be distributed without the
previous ones:

* `LICENSE.md`
* `setspaceenhanced.sty`
* `setspaceenhanced.pdf`

# Unpacking and Installation for Developers

Developers who want the current developer version of the code to be installed
for testing, should clone [the `third-party-enhancements`
repository](https://github.com/komascript/third-party-enhancements), e.g.,
using

git clone https://github.com/komascript/third-party-enhancements.git

You can
than either unpack and install all the third-party enhancements using:

l3build install --full

from within the main directory of the cloned respository (omit option `--full`
if you don't want the manual) or `setspaceenhanced` only doing the same from
within the `setspaceenhanced` sub-directory.

# How to get the Manuals

Expand All @@ -77,23 +103,21 @@ After installation you should get the user manual using:

See the manual of your TeX distribution for more information.

You can also build the manuals from the source. To do so, clone the source of
the whole project, go to the sub-folder `setspaceenhanced` and run:
Developers or distributors can also build the manuals from the source using:

l3build doc

This will result in the file `setspaceenhanced.pdf`. This is the user manual
and (optionally) the implemenation documentation of `setspaceenhanced`.

# How to Contribute

To become a contributor, clone the code and do heavy testing. If you find an
issue, please report it using the [issue tracker](../../../issues). You can
also, e.g., make new test files to the packages. See the
[`l3build`](https://ctan.prg/pkg/l3build) manual for more information about
tests. If you've created a new test and think that it would be useful. Please
either do a pull request or [add a new issue](../../../issues/new/choose) and
include your test file.
To become a contributor, e.g., do heavy testing. If you find an issue, please
report it using the [issue
tracker](https://github.com/komascript/third-party-enhancements/issues). You
can also become a developer and, e.g., make new test files to the
packages. See the [`l3build`](https://ctan.prg/pkg/l3build) manual for more
information about tests. If you've created a new test and think that it would
be useful. Please either do a pull request or [add a new
issue](https://github.com/komascript/third-party-enhancements/issues/new/choose)
and include your test file.

Another kind of contribution would be to contact an author of one of the
third-party packages and convince her or him to integrate the code of the
Expand All @@ -102,15 +126,17 @@ corresponding enhancement package from this project into her or his package.
# How to Report Issues

If you think you have found a bug (or another kind of issue) using
`setspaceenhanced` you should use the [issue tracker](../../../issues). Please
`setspaceenhanced` you should use the [issue
tracker](https://github.com/komascript/third-party-enhancements/issues). Please
first search for similar issues already reported and maybe also already fixed
and closed. Maybe the replies to such a similar report would help you too.

If your issue is new, you should report it also using the [issue
tracker](../../../issues). Please be kind, not only when writing the report
but also when reading replies and commenting or answering. And please always
add a minimal working example and usually the relevant parts of the `log`-file
to your report. Please use the [markdown for
tracker](https://github.com/komascript/third-party-enhancements/issues). Please
be kind, not only when writing the report but also when reading replies and
commenting or answering. And please always add a minimal working example and
usually the relevant parts of the `log`-file to your report. Please use the
[markdown for
code](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks)
to add such files into the text of your report. The correct language
identifier for LaTeX code would be `latex`. For `log`-files you won't need any
Expand Down
6 changes: 3 additions & 3 deletions setspaceenhanced/build.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
setspaceenhanced.
]]

release_info = "2023-07-28 v0.1"
release_info = "2023-08-04 v1.0"

-- Bundle and modules

Expand Down Expand Up @@ -72,8 +72,8 @@ function update_tag (file,content,tagname,tagdate)
" {" .. tagdate .. "}{" .. tagname .. "}\n" )
elseif string.match (file, "%.md$") then
return string.gsub (content,
"\nRelease: %d%d%d%d%-%d%d%-%d%d v[%d%.]*%d+ \n",
"\nRelease: " .. tagdate .. " v" .. tagname .. " \n")
"\nRelease: %d%d%d%d%-%d%d%-%d%d v[%d%.]*%d+",
"\nRelease: " .. tagdate .. " v" .. tagname )
elseif string.match (file, "%.lua$") then
return string.gsub (content,
'\nrelease_info%s*=%s*"%d%d%d%d%-%d%d%-%d%d%s*v[%d%.]*%d+"',
Expand Down
96 changes: 55 additions & 41 deletions setspaceenhanced/setspaceenhanced.dtx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,6 @@
% and version 1.<3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of the file `setspaceenhanced.dtx' and `README.md'.
Expand All @@ -34,7 +32,7 @@
%</dtx>
%<*dtx|package>
%<package>\ProvidesExplPackage{setspaceenhanced}
{2023-07-28}{0.1}
{2023-08-04}{1.0}
{%
%<*dtx>
sources and unpack driver of
Expand Down Expand Up @@ -156,11 +154,13 @@
%</dtx>
%\fi
%
% \changes{v0.1}{2023/06/01}{start of \KOMAScript{} spin-off}
% \changes{v0.1}{2023/06/01}{new \KOMAScript{} spin-off}
%
% \GetFileInfo{setspaceenhanced.dtx}
% \title{Improving ``\pkg{setspace}''}
% \author{\href{mailto:komascript@gmx.info}{Markus Kohm}}
% \author{\href{mailto:komascript@gmx.info}{Markus Kohm}\thanks{Repository and
% bug reports:
% \url{https://github.com/komascript/third-party-enhancements}}}
% \date{Version \filedate{} \fileversion}
% \maketitle
% \begin{abstract}
Expand Down Expand Up @@ -229,11 +229,12 @@ which also apply when using a \KOMAScript{} class or the \KOMAScript{} package
\pkg{setspace} does not care for the \cs{baselineskip} selected by
\cs{fontsize}. Instead it sets the stretch factor always depending on the
document font size. And using \cs{singlespacing}, \cs{onehalfspacing} or
\cs{doublespacing} or even \cs{setstretch} after switching the font size using
\cs{fontsize} instead of \cs{Huge}, \cs{huge}, \cs{LARGE}, \cs{Large},
\cs{large}, \cs{normalsize}, \cs{small}, \cs{footnotesize}, \cs{scriptsize},
\cs{tiny}, or another command defined using \cs{@setsize}, reactivates the
last used such font size commd. So using something like
\cs{doublespacing} or even \cs{setstretch}\SpecialCommandIndex{\setstretch}
after switching the font size using \cs{fontsize} instead of \cs{Huge},
\cs{huge}, \cs{LARGE}, \cs{Large}, \cs{large}, \cs{normalsize}, \cs{small},
\cs{footnotesize}, \cs{scriptsize}, \cs{tiny}, or another command defined
using \cs{@setsize}, reactivates the last used such font size commd. So using
something like
\begin{verbatim}
\normalsize\fontsize{5pt}{7pt}\selectfont\onehalfspacing
\end{verbatim}
Expand All @@ -252,7 +253,7 @@ of the 5\,pt font.
In other words: Package \pkg*{setspaceenhanced} uses a completely different
definition of \cs{onehalfspacing} and \cs{doublespacing}. It always uses
\cs{f@size} and \cs{f@baselineskip} to calculate a factor resulting in real
onehalfspacing resp. doublespacing. This also means, if you use one of these
onehalfspacing and doublespacing. This also means, if you use one of these
commands after changing the font size, a new stretch factor is calculated
depending on the current font size without changing the font size.

Expand Down Expand Up @@ -296,8 +297,8 @@ use of \cs{singlespacing}, \cs{onehalfspacing}, \cs{doublespacing}, or
\cs{setstretch} can it be ensured that the enhancements of
\pkg*{setspaceenhanced} are initialized and used correctly.

When using a class that uses \pkg{setspace}, the correct operation can be ensured
with
When using a class that uses \pkg{setspace}, the correct operation can be
ensured with
\begin{verbatim}
\AddToHook{package/setspace/after}{\RequirePackage{setspaceenhanced}}
\end{verbatim}
Expand All @@ -314,7 +315,7 @@ same optional argument for \cs{RequirePackage}, that is used for loading

Package \pkg*{setspaceenhanced} provides all options and commands of the user
interface of \pkg{setspace}, see \autocite{pkg:setspace:manual}. Following we
document only the differences resp. enhancements.
document only the differences and enhancements.

There are some options influencing the behavior and result of the examples
shown in the section before. All these options are
Expand All @@ -335,50 +336,52 @@ group.

\begin{description}\setkomafont{descriptionlabel}{\ttfamily}
\item[byselectfont=\meta{boolean}]%
\DescribeOption[noprint]{byselectfont}%
\DescribeOption{byselectfont}%
\hfill initial=\optvalue{false}, default=\optvalue{true}\\
In the \pkg*{setspaceenhanced} examples in the previous section, the correct
factor has only been used, because of using \cs{onehalfspacing} after
changing the font size, e.g., to \cs{small}. If you use \cs{onehalfspacing}
before changing the font size, the factor is calculated with the previous
valid font size, which is the document font size 12\,pt in all these
examples. This behavior can be changed to a more dynamic automatism using
option \opt{byselectfont} resp. \opt{byselectfont=true}. This will use the
generic \LaTeX{} hook \texttt{selectfont} to reactivate \cs{onehalfspacing}
or \cs{doublespacing} after every \texttt{selectfont} if the font size has
been changed.
examples. This\SpecialCommandIndex{\selectfont}\marginline{\cs{selectfont}}
behavior can be changed to a more dynamic automatism using option
\opt{byselectfont} or \opt{byselectfont=true}. This will use the generic
\LaTeX{} hook \texttt{selectfont} to reactivate \cs{onehalfspacing} or
\cs{doublespacing} after every \cs{selectfont} if the font size has been
changed.
\item[doublespacing=\meta{real}]%
\DescribeOption{onehalfspacing}%
\hfill initial=\texttt{nan}, default=\emph{empty}\\
If this option is used without value, it is the same as \pkg{setspace}'s
package option \opt{doublespacing} resp. using command
\cs{doublespacing}. But if you assign a real
number\footnote{\label{ftn:fp}Here are all values allowed, that would be
allowed as second argument of \LaTeX3 function \cs{fp\string_set:Nn}} this
would be used as the new stretch factor used for doublespacing. This also
means, that the default calculation of the factor is deactivated. But a
factor of \texttt{nan} would reactivate the calculation of the factor
depending on the font size and the baseline skip set for the font size. It
is recommended to use the option always without value!
package option \opt{doublespacing} or using command \cs{doublespacing}. But
if you assign a real number\footnote{\label{ftn:fp}Here are all values
allowed, that would be allowed as second argument of \LaTeX3 function
\cs{fp\string_set:Nn}} this would be used as the new stretch factor used
for doublespacing. This also means, that the default calculation of the
factor is deactivated. But a factor of \texttt{nan} would reactivate the
calculation of the factor depending on the font size and the baseline skip
set for the font size. It is recommended to use the option always without
value!
\item[fontsize=\meta{boolean}]%
\DescribeOption{fontsize}%
\DescribeCommand{\setstretch}%
\hfill initial=\optvalue{false}, default=\optvalue{true}\\
As explained in \autoref{sec:whywithoutkomascript}, \pkg{setspace}'s
\cs{setstretch} behaves different after a font size command like \cs{Huge},
\cs{huge}, \cs{LARGE}, \cs{Large}, \cs{large}, \cs{normalsize}, \cs{small},
\cs{footnotesize}, \cs{scriptsize}, \cs{tiny}, or another command defined
using \cs{@setsize} than after using \cs{fontsize}\cs{selectfont}. With the
using \cs{@setsize} than after using |\fontsize{…}{…}\selectfont|. With the
last the font size will be reset to the previous usage of one of the other
or the document font size. For a lot of users this is somehow
unexpected. With option \opt{fontsize} resp. \opt{fontsize=true} this is
unexpected. With option \opt{fontsize} or \opt{fontsize=true} this is
changed and using \cs{setstretch} does not reactivate the last used
\cs{Huge}, \cs{huge}, \cs{LARGE}, \cs{Large}, \cs{large}, \cs{normalsize},
\cs{small}, \cs{footnotesize}, \cs{scriptsize}, \cs{tiny}.
\item[onehalfspacing=\meta{real}]%
\DescribeOption{onehalfspacing}%
\hfill initial=nan, default=\emph{empty}\\
\hfill initial=\texttt{nan}, default=\emph{empty}\\
If this option is used without value, it is the same as \pkg{setspace}'s
package option \opt{onehalfspacing} resp. using command
package option \opt{onehalfspacing} or using command
\cs{onehalfspacing}. But if you assign a real number\footref{ftn:fp} this
would be used as the new stretch factor used for onehalfspacing. This also
means, that the default calculation of the factor is deactivated. But a
Expand All @@ -389,13 +392,24 @@ group.
\DescribeOption{singlespacing}%
\hfill initial=1, default=\emph{empty}\\
If this option is used without value, it is the same as \pkg{setspace}'s
package option \opt{singlespacing} resp. using command
\cs{singlespacing}. But if you assign a real number\footref{ftn:fp} this
would be used as the new stretch factor used for singlespacing. So this is
similar to using \cs{SetSinglespace}\marg{real}\cs{singlespacing}. A factor
of \texttt{nan} would activate the calculation of the factor depending on
the font size and the baseline skip set for the font size. It is recommended
to use the option always without value!
package option \opt{singlespacing} or using command \cs{singlespacing}. But
if you assign a real number\footref{ftn:fp} this would be used as the new
stretch factor used for singlespacing. So this is similar to using
\cs{SetSinglespace}\marg{real}\cs{singlespacing}. A factor of \texttt{nan}
would activate the calculation of the factor depending on the font size and
the baseline skip set for the font size. It is recommended to use the option
always without value!
\end{description}

\subsubsection*{Compatibility Notes:}

\begin{description}
\item[\pkg*{scrhack}] If you want to use this package together with package
\pkg*{scrhack} from \href{https://www.ctan.org/pkg/koma-script}{\KOMAScript}
before version 3.42, you should deactivate the \file{setspace} hack using
\pkg*{scrhack}' option \opt{setspace=false}. From version 3.42
\pkg*{scrhack} does not use the old hacks any longer but
\pkg*{setspaceenhanced} and is therefore compatible again.
\end{description}

\section{How does the result of
Expand Down Expand Up @@ -448,7 +462,7 @@ Here the difference from the correct value 16.425\,pt is very, very small:
0.00004\,pt. So you can say, this is really onehalfspacing depending on the
used font size.

Moreover of you have a document:
Moreover if you have a document:
\begin{verbatim}
\documentclass[12pt]{article}
\usepackage{setspace}
Expand Down

0 comments on commit 04c1ec0

Please sign in to comment.