% \iffalse meta-comment
% SPDX-FileCopyrightText: Copyright (c) 2021-2026 Yegor Bugayenko
% SPDX-License-Identifier: MIT
% \fi

% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}

% \GetFileInfo{handstroke.dtx}
% \DoNotIndex{\endgroup,\begingroup,\let,\else,\fi,\newcommand,\newenvironment}
% \DoNotIndex{\ProcessPgfPackageOptions}

% \iffalse
%<*driver>
\ProvidesFile{handstroke.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{handstroke}
%<*package>
[2026-07-13 0.4.0 Hand-Written Underline]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{microtype}
\AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
\PassOptionsToPackage{hyperindex=false}{hyperref}
\usepackage{href-ul}
\usepackage{handstroke}
\usepackage{amsmath}
\usepackage{multicol}
\usepackage{xcolor}
\usepackage[dtx,runs=2]{docshots}
\PageIndex
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
	\DocInput{handstroke.dtx}
	\PrintChanges
	\PrintIndex
\end{document}
%</driver>
% \fi

% \title{|handstroke|: \LaTeX{} Package \\ for Hand-Written Underline\thanks{The sources are in GitHub at \href{https://github.com/yegor256/handstroke}{yegor256/handstroke}}}
% \author{Yegor Bugayenko \\ \texttt{yegor256@gmail.com}}
% \date{\filedate, \fileversion}
%
% \maketitle
%
% \section{Introduction}
%
% A plain, ruler-straight underline blends into the text and is
% easy to miss. This package draws the line as if it were sketched
% by hand: it wavers a little, stands apart from the typeset
% letters, and catches the reader's eye where an ordinary rule
% would go unnoticed. Reach for the |\handstroke| command whenever a
% word or a phrase truly deserves attention:
% \begin{docshot}
% \documentclass{article}
% \usepackage[paperwidth=14em]{geometry}
% \usepackage[colored]{handstroke}
% \pagestyle{empty}
% \begin{document}\raggedright
% Don't forget to \handstroke{encrypt}
% the data before sending them over the
% network, it's \handstroke{important}!
% \end{document}
% \end{docshot}

% \DescribeMacro{\handstroke}
% The |\handstroke| command takes a single argument and underlines it,
% much like the familiar |\ul|. The only difference is the shape of
% the line: instead of a straight rule, |\handstroke| sketches an
% uneven handstroke that looks hand-drawn and stands out on the page.
%
% By default the handstroke is drawn in gray. Load the package with the
% |colored| option to paint it in color instead, and pass
% |color=|\meta{name} to choose which one (|orange| by default), as
% in |\usepackage[colored, color=red]{handstroke}|.
%
% A single stroke may also be recolored on its own, without touching the
% rest of the document, by giving |\handstroke| an optional
% |color=|\meta{name} argument. This overrides both the gray default and
% whatever the package-wide |color| option asked for, but only for that
% one line:
% \begin{docshot}
% \documentclass{article}
% \usepackage[paperwidth=8em]{geometry}
% \usepackage{handstroke}
% \pagestyle{empty}
% \begin{document}\raggedright
% This word is
% \handstroke[color=red]{urgent},
% while this one is
% \handstroke[color=blue]{calm}.
% \end{document}
% \end{docshot}

% \section{Package Options}

% \DescribeMacro{colored}
% The |colored| package option makes the line be colored, with the help
% of the \href{https://ctan.org/pkg/xcolor}{xcolor} package.

% \DescribeMacro{color}
% The |color| package option (|orange| by default) defines the color
% of the line.

% \DescribeMacro{synonym}
% The |synonym| package option defines a shorter alias for the
% |\handstroke| command, so that |\usepackage[synonym=hs]{handstroke}|
% lets you write |\hs{word}| instead of |\handstroke{word}|:
% \begin{docshot}
% \documentclass{article}
% \usepackage[paperwidth=10em]{geometry}
% \usepackage[synonym=hs]{handstroke}
% \pagestyle{empty}
% \begin{document}\raggedright
% How about \hs{this}?
% \end{document}
% \end{docshot}
%
% The chosen name need not be new. When it already belongs to an existing
% command, such as |\emph|, that command is renewed to draw a handstroke,
% rather than aborting with an error.

% \DescribeMacro{emph}
% The |emph| package option is a shortcut for |synonym=emph|: it renews the
% standard |\emph| command so that |\emph{word}| draws a handstroke.

% \DescribeMacro{ul}
% The |ul| package option is a shortcut for |synonym=ul|: it lets you write
% |\ul{word}| in place of |\handstroke{word}|.
%
% They combine freely: |[synonym=hs,ul,emph]| makes |\hs|, |\ul| and
% |\emph| all draw handstrokes at once.

% \StopEventually{}

% \section{Implementation}
% \changes{v0.1.0}{2025/07/06}{Initial version}
% \changes{v0.2.0}{2025/07/12}{The package was renamed fro \texttt{stroke}
% to \texttt{handstroke} for the sake
% of disambiguation and better clarity.}
% \changes{v0.3.0}{2026/07/12}{The \texttt{color} option can now be passed
% to the \texttt{\textbackslash handstroke} command to recolor a single
% line.}
% \changes{v0.4.0}{2026/07/12}{The \texttt{synonym} package option defines
% a shorter alias for the \texttt{\textbackslash handstroke} command,
% renewing the target when it already exists, such as
% \texttt{\textbackslash emph}.}
% \changes{v0.4.0}{2026/07/13}{The \texttt{emph} and \texttt{ul} package
% options were added as shortcuts for \texttt{synonym=emph} and
% \texttt{synonym=ul}, and several synonyms can now be combined in one load.}

% First, we parse package options with the help of
% the \href{https://ctan.org/pkg/pgfopts}{pgfopts} package. Every
% |synonym| appends one more name to |\handstroke@synonyms|, so the
% options accumulate and several aliases can be requested at once. The
% |emph| and |ul| options are styles that expand to |synonym=emph| and
% |synonym=ul|, sharing that same machinery:
%    \begin{macrocode}
\RequirePackage{pgfopts}
\def\handstroke@synonyms{}
\pgfkeys{
  /handstroke/.cd,
  colored/.store in=\handstroke@colored,
  color/.store in=\handstroke@color,
  color/.default=orange,
  color,
  synonym/.code={%
    \g@addto@macro\handstroke@synonyms{\handstroke@alias{#1}}},
  emph/.style={synonym=emph},
  emph/.default=,
  ul/.style={synonym=ul},
  ul/.default=,
}
\ProcessPgfPackageOptions{/handstroke}
%    \end{macrocode}

% Then, we load the \href{https://ctan.org/pkg/xcolor}{xcolor} package,
% if coloring is required via the |colored| package option:
%    \begin{macrocode}
\makeatletter
\ifdefined\handstroke@colored
  \RequirePackage{xcolor}
\fi
\makeatother
%    \end{macrocode}

% Then, we load the \href{https://ctan.org/pkg/pgf}{tikz} package,
% together with a few required libraries
% that provide the coordinate arithmetic and the random-steps
% decoration used below:
%    \begin{macrocode}
\RequirePackage{tikz}
\usetikzlibrary{calc}
\usetikzlibrary{decorations.pathmorphing}
%    \end{macrocode}

% \begin{macro}{\handstroke}
% Finally, we define the |\handstroke| command itself. It typesets its
% argument inside a |tikz| node and then draws a wavering
% rectangle path just beneath the baseline, so that only the lower
% edge shows and reads as an underline. The optional first argument
% accepts a |color=|\meta{name} key that overrides the ink for this one
% stroke only:
%    \begin{macrocode}
\makeatletter
\pgfkeys{
  /handstroke/stroke/.cd,
  color/.store in=\handstroke@ink,
}
\newcommand\handstroke[2][]{%
  \ifdefined\handstroke@colored%
    \let\handstroke@ink\handstroke@color%
  \else\def\handstroke@ink{gray!80}\fi%
  \pgfkeys{/handstroke/stroke/.cd, #1}%
  \tikz[baseline=(text.base)] {
    \node[inner sep=0em, outer sep=0em] (text) {#2};
    \begin{scope}
      \path[use as bounding box]
        (text.east) rectangle (text.west);
      \draw[decorate,
        decoration={random steps,
          amplitude=0.05em, segment length=0.3em},
        line join=round,
        line cap=round,
        line width=.08em,
        draw=\handstroke@ink]
        ($(text.west) + (-0.2em, -.46em)$)
        rectangle
        ($(text.east) + (+0.2em, -.46em)$);
    \end{scope}
  }%
}
\makeatother
%    \end{macrocode}
% \end{macro}

% Once |\handstroke| exists, we walk the collected names and let each one
% alias it. Because |\let| overwrites whatever meaning a name carried
% before, an existing command such as |\emph| is renewed rather than
% aborting with an error:
%    \begin{macrocode}
\makeatletter
\newcommand\handstroke@alias[1]{%
  \expandafter\let\csname#1\endcsname\handstroke}
\handstroke@synonyms
\makeatother
%    \end{macrocode}

%    \begin{macrocode}
\endinput
%    \end{macrocode}

% \Finale

%\clearpage
%
%\PrintChanges
%\clearpage
%\PrintIndex