summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/scaletextbullet/scaletextbullet.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-11-11 03:03:56 +0000
committerNorbert Preining <norbert@preining.info>2024-11-11 03:03:56 +0000
commita1ce7e07933cf42e71b2860e4cc32812f372686c (patch)
tree799debce50580d2639908d9fecc58ad454c1ae96 /macros/latex/contrib/scaletextbullet/scaletextbullet.tex
parent39dffb518e71d6b367f1739413d905ebc8a09466 (diff)
CTAN sync 202411110303
Diffstat (limited to 'macros/latex/contrib/scaletextbullet/scaletextbullet.tex')
-rw-r--r--macros/latex/contrib/scaletextbullet/scaletextbullet.tex224
1 files changed, 224 insertions, 0 deletions
diff --git a/macros/latex/contrib/scaletextbullet/scaletextbullet.tex b/macros/latex/contrib/scaletextbullet/scaletextbullet.tex
new file mode 100644
index 0000000000..95cfd59273
--- /dev/null
+++ b/macros/latex/contrib/scaletextbullet/scaletextbullet.tex
@@ -0,0 +1,224 @@
+\documentclass{beery}
+
+\NewDocumentCommand\textbulletfactor{}{\cs{textbullet} factor}
+
+
+\begin{document}
+
+
+\section*
+ {%
+ \SetFontStep*{1}%
+ The \pkg{scaletextbullet} package%
+ }
+
+Resize the \cs{textbullet} without changing its vertical center
+
+Oliver Beery
+
+Version 1.0.0\quad{}10 November 2024
+
+
+\section{Introduction}
+\label{sec:intro}
+
+The \pkg{scaletextbullet} package enables the user to resize the \cs{textbullet} without moving its vertical center, unlike direct usage of the \LaTeXe{} and \pkg{expl3} commands \cs{scalebox} and \cs{box_scale:}.
+This process is not fully automated\---the user must use \cs{SetTextBulletFactor} to set the \textbulletfactor{} to the correct value to display the resized \cs{textbullet} at the correct height.
+The \textbulletfactor{} is the ratio of the width of the \cs{textbullet}, excluding its empty space, to its width, including its empty space.
+One way of estimating the \textbulletfactor{} is by using \cs{scaletextbulletdebug}.
+
+This package provides a solution that works in text mode.
+For a solution that works only in math mode, see the linked \TeX{} Stack Exchange thread.%
+\footnote{\url{https://tex.stackexchange.com/questions/119319/how-to-correctly-shrink-the-bullets-of-itemize}}
+
+
+\section{Commands}
+\label{sec:commands}
+
+This package defines some commands whose argument takes a \meta{floating point expression} or \meta{integer expression}.
+This syntax has the same representation as the arguments to \cs{fpeval} and \cs{inteval}, documented in \pkg{usrguide}.%
+\footnote{\url{https://ctan.org/pkg/usrguide}}
+
+\cs{SetTextBulletFactor} \marg{floating point expression}
+\KeepNextPar*
+
+Sets the \textbulletfactor{} to the result of computing the \meta{floating point expression}.
+The \textbulletfactor{} is the ratio of the width of the \cs{textbullet}, excluding its empty space, to its width, including its empty space.
+This change is local to the current group.
+The initial \textbulletfactor{} is \num{0.4}\---this matches the dimensions of the \cs{textbullet} of the Latin Modern font at size \qty{10}{pt}.
+
+\cs{ScaleTextBullet} \marg{floating point expression}
+\KeepNextPar*
+
+Prints a \cs{textbullet} with its size scaled by the result of computing the \meta{floating point expression}.
+The new \cs{textbullet} will be printed with the same vertical center only if the \textbulletfactor{} is set to the correct value.
+
+\cs{ScaleTextBullets} \oarg{floating point expression} \marg{integer expression}
+\KeepNextPar*
+
+Prints a number of \cs{textbullet}s equal to the value of \meta{integer expression} with about the same total area as the original \cs{textbullet}.%
+\footnote
+ {%
+ In calculating the total area, I have approximated each \cs{textbullet} as a perfect circle, but, of course, the actual shape depends on the font used.%
+ }
+If the optional argument is used, the size of each \cs{textbullet} is instead scaled by the result of computing the \meta{floating point expression}.
+The new \cs{textbullet} will be printed with the same vertical center only if the \textbulletfactor{} is set to the correct value.
+
+\cs{scaletextbulletdebug}
+\KeepNextPar*
+
+This command is provided only to help the user estimate the \textbulletfactor{}.
+Prints \num{15} consecutive \cs{textbullet}s with decreasing sizes.
+The \cs{textbullet}s are followed by the original \cs{textbullet} inside a framed box.
+The framed box has width equal to the \textbulletfactor{} \texttimes{} the total width of the \cs{textbullet} (this includes its empty space).
+
+The \textbulletfactor{} is set to the correct value when the 15 consecutive \cs{textbullet}s have the same vertical center and the \cs{textbullet} fits nicely inside the framed box.
+
+
+\section{Application}
+\label{sec:application}
+
+I wrote this package primarily to create nicer\-/looking itemized lists.
+The default list labels in \LaTeX{} (and other programs) fail to communicate the list level within the list hierarchy:
+
+\begin{multicols}{2}
+ \begin{itemize}[label=\textbullet]
+ \item List level 1
+ \begin{itemize}[label=\textbf{--}]
+ \item List level 2
+ \item List level 2
+ \begin{itemize}[label=\textasteriskcentered]
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \item List level 1
+ \begin{itemize}[label=\textbf{--}]
+ \item List level 2
+ \begin{itemize}[label=\textasteriskcentered]
+ \item List level 3
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \end{itemize}
+\end{multicols}
+
+This contrasts with traditional enumerated list structures where the list level is obvious from the numbering of the list label:
+
+\begin{multicols}{2}
+ \begin{enumerate}
+ \item List level 1
+ \begin{enumerate}
+ \item List level 2
+ \item List level 2
+ \begin{enumerate}
+ \item List level 3
+ \end{enumerate}
+ \end{enumerate}
+ \item List level 1
+ \begin{enumerate}
+ \item List level 2
+ \begin{enumerate}
+ \item List level 3
+ \item List level 3
+ \end{enumerate}
+ \end{enumerate}
+ \end{enumerate}
+\end{multicols}
+
+This package allows the user to create nice\-/looking itemized lists using \cs{ScaleTextBullets}:
+
+\begin{multicols}{2}
+ \begin{itemize}
+ \item List level 1
+ \begin{itemize}
+ \item List level 2
+ \item List level 2
+ \begin{itemize}
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \item List level 1
+ \begin{itemize}
+ \item List level 2
+ \begin{itemize}
+ \item List level 3
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \end{itemize}
+\end{multicols}
+
+Maybe the visual effect is more clear with different fonts.
+This example uses STIX Two Text and Source Serif 4, respectively.
+
+\begingroup
+ \SetTextBulletFactor{0.54}
+ \newfontfamilystixtwo
+ \begin{multicols}{2}
+ \begin{itemize}
+ \item List level 1
+ \begin{itemize}
+ \item List level 2
+ \item List level 2
+ \begin{itemize}
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \item List level 1
+ \begin{itemize}
+ \item List level 2
+ \begin{itemize}
+ \item List level 3
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \end{itemize}
+ \end{multicols}
+\endgroup
+
+\begingroup
+ \SetTextBulletFactor{0.75}
+ \newfontfamilysourceseriffour
+ \begin{multicols}{2}
+ \begin{itemize}
+ \item List level 1
+ \begin{itemize}
+ \item List level 2
+ \item List level 2
+ \begin{itemize}
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \item List level 1
+ \begin{itemize}
+ \item List level 2
+ \begin{itemize}
+ \item List level 3
+ \item List level 3
+ \end{itemize}
+ \end{itemize}
+ \end{itemize}
+ \end{multicols}
+\endgroup
+
+
+\section{Implementation notes}
+\label{sec:implementation}
+
+The procedure of resizing the \cs{textbullet} without changing its vertical center, including the definition of the \textbulletfactor{}, makes an important assumption:
+That the \cs{textbullet} is a perfect circle.
+Of course, this is not completely accurate and the actual shape depends on the font used.
+This means that the \textbulletfactor{} may not be exactly the ratio of the width of the \cs{textbullet}, excluding its empty space, to its width, including its empty space.
+
+In writing this package, I have referenced a comment on the \TeX{} Stack Exchange by the user egreg.%
+\footnote{\url{https://tex.stackexchange.com/questions/620507/how-to-resize-textbullet-without-the-bullet-moving-down/638599\#638599}}
+This package uses the same procedure for resizing the \cs{textbullet} without changing its vertical center.
+
+
+\section{Programming}
+\label{sec:programming}
+
+This package is written in \pkg{expl3}, but does not provide any public functions or variables.
+
+
+\end{document} \ No newline at end of file