| 1 |
% \iffalse meta-comment |
| 2 |
%<*internal> |
| 3 |
\iffalse |
| 4 |
%</internal> |
| 5 |
%<*readme> |
| 6 |
multicolrule - Decorative rules between columns |
| 7 |
================================================= |
| 8 |
|
| 9 |
The multicolrule package lets you customize the appearance of |
| 10 |
the vertical rule that appears between columns of multicolumn |
| 11 |
text. It is primarily intended to work with the multicol |
| 12 |
package, hence its name, but it also supports the twocolumn |
| 13 |
option and \twocolumn macro provided by the standard classes |
| 14 |
(and related classes such as the KOMA-Script equivalents). |
| 15 |
|
| 16 |
Installation |
| 17 |
------------ |
| 18 |
|
| 19 |
This package is provided as a .dtx file. To install it and |
| 20 |
compile the documentation at the same time, simply process the |
| 21 |
.dtx file with LaTeX (for example, `pdflatex multicolrule.dtx`). |
| 22 |
To extract the package only, process the file with TeX |
| 23 |
(`tex multicolrule.dtx`). Note that the documentation uses |
| 24 |
the l3doc class to index the code, and so to get the index, you |
| 25 |
must issue: |
| 26 |
|
| 27 |
`makeindex -s gind.ist -o multicolrule.ind multicolrule.idx` |
| 28 |
|
| 29 |
and to get the change list, you must issue |
| 30 |
|
| 31 |
`makeindex -s gglo.ist -o multicolrule.gls multicolrule.glo`. |
| 32 |
|
| 33 |
This package requires expl3 and xparse. |
| 34 |
%</readme> |
| 35 |
%<*internal> |
| 36 |
\fi |
| 37 |
\def\nameofplainTeX{plain} |
| 38 |
\ifx\fmtname\nameofplainTeX\else |
| 39 |
\expandafter\begingroup |
| 40 |
\fi |
| 41 |
%</internal> |
| 42 |
%<*install> |
| 43 |
\input l3docstrip.tex |
| 44 |
\keepsilent |
| 45 |
\askforoverwritefalse |
| 46 |
\preamble |
| 47 |
---------------------------------------------------------------- |
| 48 |
multicolrule --- Decorative rules between columns |
| 49 |
Author: Karl Hagen |
| 50 |
Email: [email protected] |
| 51 |
Released under the LaTeX Project Public License v1.3c or later |
| 52 |
See http://www.latex-project.org/lppl.txt |
| 53 |
---------------------------------------------------------------- |
| 54 |
|
| 55 |
\endpreamble |
| 56 |
\postamble |
| 57 |
Copyright (C) 2018-2020 by Karl Hagen <[email protected]> |
| 58 |
|
| 59 |
This file may be distributed and/or modified under the |
| 60 |
conditions of the LaTeX Project Public License (LPPL), either |
| 61 |
version 1.3c of this license or (at your option) any later |
| 62 |
version. The latest version of this license is in the file: |
| 63 |
https://www.latex-project.org/lppl.txt |
| 64 |
|
| 65 |
This work is "maintained" (as per LPPL maintenance status) by |
| 66 |
Karl Hagen. |
| 67 |
|
| 68 |
This work consists of the files multicolrule.dtx and |
| 69 |
mcrule-examples.tex, |
| 70 |
and the derived files multicolrule.ins, |
| 71 |
multicolrule.sty, |
| 72 |
multicolrule.pdf, and |
| 73 |
mcrule-examples.pdf. |
| 74 |
\endpostamble |
| 75 |
\usedir{tex/latex/multicolrule} |
| 76 |
\generate{ |
| 77 |
\file{\jobname.sty}{\from{\jobname.dtx}{package}} |
| 78 |
} |
| 79 |
%</install> |
| 80 |
%<install>\endbatchfile |
| 81 |
%<*internal> |
| 82 |
\usedir{source/latex/multicolrule} |
| 83 |
\generate{ |
| 84 |
\file{\jobname.ins}{\from{\jobname.dtx}{install}} |
| 85 |
} |
| 86 |
\nopreamble\nopostamble |
| 87 |
\usedir{doc/latex/multicolrule} |
| 88 |
\generate{ |
| 89 |
\file{README.md}{\from{\jobname.dtx}{readme}} |
| 90 |
} |
| 91 |
\ifx\fmtname\nameofplainTeX |
| 92 |
\expandafter\endbatchfile |
| 93 |
\else |
| 94 |
\expandafter\endgroup |
| 95 |
\fi |
| 96 |
%</internal> |
| 97 |
%<*driver|package> |
| 98 |
\RequirePackage{expl3} |
| 99 |
\RequirePackage{xparse} |
| 100 |
%</driver|package> |
| 101 |
%<*driver> |
| 102 |
\PassOptionsToPackage{svgnames}{xcolor} |
| 103 |
\documentclass{l3doc} |
| 104 |
\usepackage[T1]{fontenc} |
| 105 |
\usepackage[ttscale=0.85]{libertine} |
| 106 |
\usepackage{microtype} |
| 107 |
\usepackage[tikz]{multicolrule} |
| 108 |
\usepackage{longtable} |
| 109 |
\usepackage{ragged2e} |
| 110 |
\usepackage{scrlayer-scrpage} |
| 111 |
\usepackage{scrlayer-notecolumn} |
| 112 |
\usepackage{bbding} |
| 113 |
\usepackage{pgfornament} |
| 114 |
\pagestyle{scrheadings} |
| 115 |
\automark[subsection]{section} |
| 116 |
\DeclareNewNoteColumn[ |
| 117 |
reversemarginpar, |
| 118 |
font=\color{Navy}\footnotesize\ttfamily |
| 119 |
]{illustration} |
| 120 |
\ProvideDocumentCommand\opt{m}{\texttt{#1}} |
| 121 |
\NewDocumentCommand{\stydsc}{m}{^^A |
| 122 |
\makenote*[illustration]{^^A |
| 123 |
\hspace*{32pt}\parbox{\marginparwidth-32pt}{^^A |
| 124 |
\RaggedRight#1}^^A |
| 125 |
}^^A |
| 126 |
} |
| 127 |
\NewDocumentCommand{\mcrule}{}{\textcolor{Maroon}{multicolrule}} |
| 128 |
\NewDocumentCommand{\kvdesc}{m}{\textcolor{Navy}{\texttt{#1}}} |
| 129 |
\setlength{\parindent}{16pt} |
| 130 |
\setlength{\columnsep}{24pt} |
| 131 |
\SetMCRule{width=thin,color=Maroon,line-style=dots} |
| 132 |
\EnableCrossrefs |
| 133 |
\CodelineIndex |
| 134 |
\RecordChanges |
| 135 |
\begin{document} |
| 136 |
\DocInput{\jobname.dtx} |
| 137 |
\end{document} |
| 138 |
%</driver> |
| 139 |
% \fi |
| 140 |
% |
| 141 |
%\GetFileInfo{\jobname.sty} |
| 142 |
% |
| 143 |
%\DoNotIndex{\AfterPackage,\begin,\bool_gset_true:N,\bool_if:NTF, |
| 144 |
% \bool_lazy_and:nnT,\cs_gset_eq:NN,\bool_if_p:n,\bool_lazy_and:nnTF, |
| 145 |
% \bool_not_p:n,\bool_new:N,\box_ht:N,\box_dp:N,\box_move_down:nn, |
| 146 |
% \cs_generate_variant:Nn,\cs_gset:Npn,\cs_new:Npn, |
| 147 |
% \cs_new_nopar:Npn,\cs_set:Npn, |
| 148 |
% \c_one_int,\c_zero_dim,\c_zero_int, |
| 149 |
% \dim_compare_p:nNn,\dim_new:N,\dim_set:Nn, |
| 150 |
% \dim_compare:nNnTF,\dim_eval:n,\dim_max:nn,\dimen, |
| 151 |
% \end,\ExplSyntaxOff,\ExplSyntaxOn,\exp_stop_f:, |
| 152 |
% \fill,\fp_to_dim:n,\hbox:n,\hspace,\ht, |
| 153 |
% \int_compare:nNnTF,\int_compare:nNnT,\int_compare_p:nNn, |
| 154 |
% \int_gdecr:N,\int_gincr:N,\int_gset:Nn,\int_gzero:N, |
| 155 |
% \int_new:N,\int_set:Nn,\kern,\keys_define:nn, |
| 156 |
% \keys_set:nn,\keys_set_filter:nnV, |
| 157 |
% \msg_error:nnn,\msg_info:nnn,\msg_new:nnn,\msg_new:nnnn,\msg_warning:nn, |
| 158 |
% \NewDocumentCommand,\node,\prg_replicate:nn,\ProcessKeysOptions, |
| 159 |
% \prop_get:NnNTF,\prop_gput:Nnn,\prop_item:Nn,\prop_new:N, |
| 160 |
% \ProvidesExplPackage,\RequirePackage,\rule,\normalcolor, |
| 161 |
% \seq_count:N,\seq_item:Nn,\seq_new:N,\seq_set_split:Nnn, |
| 162 |
% \tl_if_blank:VF,\tl_if_empty:NT,\tl_if_empty:NTF,\tl_new:N,\tl_set:Nn, |
| 163 |
% \tl_set:Nx,\tw@,\vbox:n,\vbox_to_ht:nn,\vfill,\vrule,\l_tmpa_tl, |
| 164 |
% \cs_new_protected:Npn,\@ifpackageloaded,\@width,\xpatchcmd} |
| 165 |
% |
| 166 |
%\title{^^A |
| 167 |
% \textsf{multicolrule} --- Decorative rules between columns\thanks{^^A |
| 168 |
% This file describes version \fileversion, last revised \filedate.^^A |
| 169 |
% }^^A |
| 170 |
%} |
| 171 |
%\author{^^A |
| 172 |
% Karl Hagen\thanks{\href{mailto://[email protected]}^^A |
| 173 |
% {[email protected]}}} |
| 174 |
%\date{Released \filedate} |
| 175 |
% |
| 176 |
%\maketitle |
| 177 |
% |
| 178 |
% \changes{v1.0}{2018/12/15}{Initial public release} |
| 179 |
% \changes{v1.1}{2018/12/21}{Support bidi} |
| 180 |
% \changes{v1.1}{2018/12/21}{Allow extended rules} |
| 181 |
% \changes{v1.2}{2019/1/1}{Define rule patterns} |
| 182 |
% \changes{v1.2}{2019/1/1}{Allow per-column rule changes} |
| 183 |
% \changes{v1.2a}{2019/2/12}{Improve documentation} |
| 184 |
% |
| 185 |
%\begin{abstract} |
| 186 |
% The \mcrule{} package lets you customize the appearance of the vertical rule |
| 187 |
% that appears between columns of multicolumn text. It is primarily intended to |
| 188 |
% work with the \pkg{multicol} package, hence its name, but it also supports |
| 189 |
% the twocolumn option and \cs{twocolumn} macro provided by the standard |
| 190 |
% classes (and related classes such as the KOMA-Script equivalents), as well as |
| 191 |
% the \pkg{bidi} package (and through it, all RTL scripts loaded with |
| 192 |
% \pkg{polyglossia}). |
| 193 |
%\end{abstract} |
| 194 |
% |
| 195 |
%\tableofcontents |
| 196 |
% |
| 197 |
%\begin{documentation} |
| 198 |
% \raggedcolumns |
| 199 |
% |
| 200 |
% \begin{multicols}{2}[\section{Introduction}] |
| 201 |
% \SetMCRule{line-style=dashed} |
| 202 |
% |
| 203 |
% In\stydsc{line-style=dashed} \LaTeX, there are two lengths that control the |
| 204 |
% formatting between columns of multicolumn text: \cs{columnsep} specifies the |
| 205 |
% space between adjacent columns, and \cs{columnseprule} specifies the width of |
| 206 |
% a solid vertical rule that is placed centered between the columns. The |
| 207 |
% \pkg{multicol} package adds the ability to change the color of the rule, but |
| 208 |
% in both vanilla \LaTeX{} and \pkg{multicol}, the rule itself is drawn |
| 209 |
% directly inside the routines that output the column boxes, and is therefore |
| 210 |
% difficult for users to alter. |
| 211 |
% |
| 212 |
% Of course it's a legitimate question why anyone should \emph{want} to change |
| 213 |
% this rule, or indeed use one at all, as good typography tends to avoid using |
| 214 |
% large vertical lines.\footnote{See, for example, the remarks in the |
| 215 |
% documentation for the \pkg{booktabs} package.} In my own case, I needed to |
| 216 |
% modify the rule because of the requirements of a particular style I was |
| 217 |
% imitating, and having done the hard work of creating the necessary |
| 218 |
% infrastructure for one line style, it was simple to extend the solution to a |
| 219 |
% more general case. I hope someone else will find the options here useful. |
| 220 |
% |
| 221 |
% The basic line styles that \mcrule{} makes available are illustrated |
| 222 |
% throughout this guide. The default line-width used is 0.4pt (thin), and the |
| 223 |
% default color is \texttt{Maroon}. You can also find examples of rules created |
| 224 |
% with all available options in the file \file{mcrule-example.pdf}. |
| 225 |
% \end{multicols} |
| 226 |
% |
| 227 |
% \begin{multicols}{2} |
| 228 |
% \SetMCRule{custom-line={\path (TOP) to [ornament=85] (BOT);},extend-top=-24pt, |
| 229 |
% extend-bot=-8pt} |
| 230 |
% \subsection*{New for Version 1.3} |
| 231 |
% Version\stydsc{custom-line=\\\{\textbackslash path (TOP) to [ornament=85] |
| 232 |
% (BOT);\}, extend-top=-24pt, extend-bot=-8pt} 1.3 adds a strut rule. This |
| 233 |
% places an invisible rule (a strut) that obeys the other options for the rule. |
| 234 |
% Using a strut allows you to achieve effects such as selectively disabling one |
| 235 |
% separator within a pattern or using the extend and reserve options to control |
| 236 |
% the spacing to the text outside the \env{multicols} environment. |
| 237 |
% |
| 238 |
% \subsection*{New for Version 1.2} |
| 239 |
% Version 1.2 adds the ability to define |
| 240 |
% patterns, which are aliases for a series of \cs{SetMCRule} settings. With |
| 241 |
% patterns, you can change individual separators on the same page. For example, |
| 242 |
% in three-column text, the left separator can differ from the right. |
| 243 |
% You can also alter the appearance of one or more separators anywhere within |
| 244 |
% the environment (see section \ref{sec:patterns}). |
| 245 |
% |
| 246 |
% \subsection*{New for Version 1.1} |
| 247 |
% Version 1.1 supports drawing decorative rules if you have the \pkg{bidi} |
| 248 |
% package loaded, which can occur automatically if you set a right-to-left |
| 249 |
% language with \pkg{polyglossia}. It also provides a mechanism to extend or |
| 250 |
% shrink rules beyond the natural height of the columns, as well as to have the |
| 251 |
% rule fill the available space to the end of the text area (see section |
| 252 |
% \ref{sec:extend}). |
| 253 |
% \end{multicols} |
| 254 |
% |
| 255 |
% \begin{multicols}{2}[\subsection{Bugs and Known Limitations}] |
| 256 |
% The\stydsc{line-style=dots} \mcrule{} package is written using expl3 syntax, |
| 257 |
% and so requires a less-than-ancient installation of \LaTeX. It requires the |
| 258 |
% packages \pkg{l3keys2e}, \pkg{xparse}, \pkg{xpatch}, \pkg{xcolor}, |
| 259 |
% \pkg{scrlfile}, and depending on the mode of operation may also require |
| 260 |
% \pkg{multicol} and \pkg{tikz}. If you have an up-to-date distribution, these |
| 261 |
% requirements should cause no issues. |
| 262 |
% |
| 263 |
% I am sure that there are bugs that remain to be uncovered, inefficient methods |
| 264 |
% that could stand improvement, and useful features that still need to be |
| 265 |
% implemented. The development code is maintained on |
| 266 |
% \href{https://github.com/polysyllabic/multicolrule}{github}, and you can file |
| 267 |
% feature requests or bug reports there. Alternatively, you can send an email |
| 268 |
% to \href{mailto://[email protected]}{[email protected]}. I welcome |
| 269 |
% contributions for additional styles, especially to provide more options when |
| 270 |
% running the package without \pkg{tikz}. |
| 271 |
% |
| 272 |
% The following are the issues I'm currently aware of that aren't \mcrule{} |
| 273 |
% errors but which may cause buggy looking behavior: |
| 274 |
% |
| 275 |
% This package works by patching the output routines of either \pkg{multicol} |
| 276 |
% or the \LaTeX{} kernel, depending on the mode of operation. If \pkg{bidi} is |
| 277 |
% loaded, it will also patch that. It will have no effect if you use a class or |
| 278 |
% package that outputs column text via alternate mechanisms. This includes |
| 279 |
% \pkg{parcolumns}, \pkg{paracol}, and probably any other class that does its |
| 280 |
% own multi-column formatting. If you would like support for one of these, |
| 281 |
% please send me an email or file a feature request on github and I'll see what |
| 282 |
% I can do. |
| 283 |
% |
| 284 |
% The line styles that work by repeating elements in a tiled pattern may have |
| 285 |
% significant gaps at the end of columns, particularly for larger patterns. |
| 286 |
% You can mitigate this problem slightly by tweaking the spaces above and |
| 287 |
% below a pattern, but the basic problem is a side-effect of the way these |
| 288 |
% patterns are implemented (with \cs{cleaders}), which means that only an |
| 289 |
% integer number of copies can be produced. Lines drawn with \pkg{tikz} do not |
| 290 |
% have this problem. |
| 291 |
% |
| 292 |
% Extending rules beyond their natural column lengths can seriously mess up |
| 293 |
% the output, including, in certain edge cases, causing \pkg{multicol} to |
| 294 |
% overprint columns or even put them in the margins. The fact that the extended |
| 295 |
% rule affects the vertical layout was a deliberate design decision and is |
| 296 |
% necessary to support the \kvdesc{extend-fill} and \kvdesc{extend-reserve} |
| 297 |
% options. A future version may support drawing the rules to a background layer |
| 298 |
% so that the text is not shifted. |
| 299 |
% \end{multicols} |
| 300 |
% |
| 301 |
% \begin{multicols}{2}[\subsection{License}] |
| 302 |
% \SetMCRule{width=ultra-thick,line-style=dotted} |
| 303 |
% The\stydsc{\texttt{line-style=dotted, width=ultra-thick}} \mcrule{} |
| 304 |
% package is copyright 2018--2020 by Karl Hagen. It may be distributed and/or |
| 305 |
% modified under the conditions of the \LaTeX{} Project Public License, either |
| 306 |
% version 1.3c of this license or (at your option) any later version. The |
| 307 |
% latest version of this license is in |
| 308 |
% |
| 309 |
% \medskip |
| 310 |
% \noindent{\footnotesize\url{http://www.latex-project.org/lppl.txt}.} |
| 311 |
% \medskip |
| 312 |
% |
| 313 |
% This work has the LPPL maintenance status `maintained.' The Current |
| 314 |
% Maintainer of this work is Karl Hagen. |
| 315 |
% \end{multicols} |
| 316 |
% |
| 317 |
%\begin{multicols}{2}[\section{Package Options}] |
| 318 |
% \SetMCRule{line-style=dash-dot} |
| 319 |
% |
| 320 |
% \subsection{Default Operation} |
| 321 |
% Loading\stydsc{line-style=dash-dot} \mcrule{} with its default settings |
| 322 |
% enables \pkg{multicol} support, and that package will be loaded if it |
| 323 |
% hasn't been already. Note that if you need to pass any parameters to |
| 324 |
% \pkg{multicol}, such as |docolaction|, you should load \pkg{multicol} with |
| 325 |
% the appropriate settings \emph{before} you load \mcrule, as \LaTeX{} does not |
| 326 |
% support reloading packages with different parameters. |
| 327 |
% |
| 328 |
% \subsection{Option `tikz'} |
| 329 |
% \DescribeOption{tikz} |
| 330 |
% You can use more line styles if you also use the \pkg{tikz} |
| 331 |
% package. Some line styles are only available if \pkg{tikz} is enabled, and |
| 332 |
% others look better with it. The default behavior of \mcrule{} depends on the |
| 333 |
% status of the \pkg{tikz} package at the time \mcrule{} is loaded. If |
| 334 |
% \mcrule{} detects that \pkg{tikz} is already loaded, then tikz support will |
| 335 |
% be enabled by default. Otherwise, you need to provide the \opt{tikz} option |
| 336 |
% to enable it. This option also accepts explicit boolean values, so you can |
| 337 |
% pass |tikz=false| if you want to explicitly disable tikz support. If tikz |
| 338 |
% support is not enabled (or if it is explicitly disabled), the line styles |
| 339 |
% marked \emph{tikz only} in section \ref{sec:linestyles} will be unavailable |
| 340 |
% and errors will result if you try to use them. |
| 341 |
% |
| 342 |
% \subsection{Option `twocolumn'} |
| 343 |
% \DescribeOption{twocolumn} |
| 344 |
% The \mcrule{} package recognizes the option \opt{twocolumn}, |
| 345 |
% either as a package option or as a global class option. If you pass this option |
| 346 |
% to your document class, you do not need to pass it a second time to the |
| 347 |
% package. It is only necessary to use the package option if you plan to have a |
| 348 |
% predominantly one-column document and use \cs{twocolumn} to switch |
| 349 |
% temporarily into two-column mode. |
| 350 |
% |
| 351 |
% Because \pkg{multicol} does not work well with the ordinary two-column |
| 352 |
% mode, \mcrule{} is only designed to work with one or the other at a time. If |
| 353 |
% you try to use the \opt{twocolumn} option when \pkg{multicol} has already |
| 354 |
% been loaded, you will receive a warning and nothing is guaranteed. But the |
| 355 |
% custom rules will at best only appear in the conventional two-column mode and |
| 356 |
% not within a \env{multicols} environment. |
| 357 |
% \end{multicols} |
| 358 |
% |
| 359 |
% \section{The User Interface} |
| 360 |
% \begin{function}{\SetMCRule} |
| 361 |
% \begin{syntax} |
| 362 |
% \cs{SetMCRule} \meta{key-value list} |
| 363 |
% \end{syntax} |
| 364 |
% \end{function} |
| 365 |
% |
| 366 |
% \begin{multicols}{2} |
| 367 |
% \SetMCRule{width=2pt,line-style=circles} |
| 368 |
% \noindent \DescribeMacro{\SetMCRule} |
| 369 |
% The\stydsc{line-style=circles,\\ width=2pt} main user command for \mcrule{} is |
| 370 |
% \cs{SetMCRule}. It takes one parameter containing a key-value list of all |
| 371 |
% options you want to set. You can issue this command in the preamble or the |
| 372 |
% document body. Changes to the rule settings are local to the current group. |
| 373 |
% For example, if you call \cs{SetMCRule} inside a \env{multicols} environment, |
| 374 |
% the rule settings will revert to their previous values once the environment |
| 375 |
% ends. Also note that any changes made with \cs{SetMCRule} when multiple |
| 376 |
% columns are active will appear starting on the same page as your current |
| 377 |
% location when you issue the command, and will extend the height of the full |
| 378 |
% column box. It is not possible to have a rule change styles in the middle of |
| 379 |
% a page unless you close out one \env{multicols} environment and begin another. |
| 380 |
% |
| 381 |
% Table \ref{table:mcrulekeys} summarizes the keys available in \cs{SetMCRule}. |
| 382 |
% The functions of each are described in detail in the sections that follow. |
| 383 |
% \end{multicols} |
| 384 |
% |
| 385 |
% \begin{longtable}{lp{3.5in}} |
| 386 |
% \caption{\cs{SetMCRule} keys\label{table:mcrulekeys}} \\ |
| 387 |
% \toprule |
| 388 |
% Key & Purpose\\ |
| 389 |
% \midrule |
| 390 |
% \endfirsthead |
| 391 |
% \caption{\textbackslash SetMCRule keys (cont.)} \\ |
| 392 |
% \toprule |
| 393 |
% Key & Purpose\\ |
| 394 |
% \midrule |
| 395 |
% \endhead |
| 396 |
% \kvdesc{color} & Set the color of the rule (see sec. \ref{sec:color})\\ |
| 397 |
% \kvdesc{color-model} & Set the color model of the rule (see sec. |
| 398 |
% \ref{sec:color})\\ |
| 399 |
% \kvdesc{custom-line} & Set a custom \pkg{tikz} line for the rule |
| 400 |
% (\emph{tikz only}; see sec. \ref{sec:custom})\\ |
| 401 |
% \kvdesc{custom-pattern} & Set a custom individual pattern for the rule (see |
| 402 |
% sec. \ref{sec:custom})\\ |
| 403 |
% \kvdesc{custom-tile} & Set a custom tiling pattern for the rule |
| 404 |
% (see sec. \ref{sec:custom})\\ |
| 405 |
% \kvdesc{double} & Draw two copies of the rule (see sec. |
| 406 |
% \ref{sec:repeats})\\ |
| 407 |
% \kvdesc{expand} & Change the extend distance by the same amount at the top |
| 408 |
% and bottom of the column (see sec. \ref{sec:extend})\\ |
| 409 |
% \kvdesc{extend-bot} & Set an extra amount to extend the rule at the bottom of |
| 410 |
% the column (see sec. \ref{sec:extend})\\ |
| 411 |
% \kvdesc{extend-fill} & Extend rule to the bottom of the text area |
| 412 |
% (\emph{multicol} only; see sec. \ref{sec:extend})\\ |
| 413 |
% \kvdesc{extend-reserve} & Space to reserve at bottom of text area when using |
| 414 |
% \kvdesc{extend-fill} (\emph{multicol} only; see sec, \ref{sec:extend})\\ |
| 415 |
% \kvdesc{extend-top} & Set an extra amount to extend the rule at the top of |
| 416 |
% the column (see sec. \ref{sec:extend})\\ |
| 417 |
% \kvdesc{line-style} & Select the type of rule printed |
| 418 |
% (default=\emph{default}; see sec. \ref{sec:linestyles})\\ |
| 419 |
% \kvdesc{pattern-after} & Number of separators to delay before beginning to |
| 420 |
% use the specified patterns (default=0; see sec. \ref{sec:patterns})\\ |
| 421 |
% \kvdesc{pattern-for} & Number times separators to apply the patterns to |
| 422 |
% before returning to default (default=$-1$; see sec. \ref{sec:patterns})\\ |
| 423 |
% \kvdesc{patterns} & Specify one or more patterns use to draw rules. |
| 424 |
% (default=\emph{none}; see sec. \ref{sec:patterns})\\ |
| 425 |
% \kvdesc{single} & Draw a single copy of the rule (\emph{default}; |
| 426 |
% see sec. \ref{sec:repeats})\\ |
| 427 |
% \kvdesc{repeat} & Set the number of times to draw the rule (see |
| 428 |
% sec. \ref{sec:repeats})\\ |
| 429 |
% \kvdesc{repeat-distance} & Set the horizontal space between |
| 430 |
% adjacent copies of repeated rules (see sec. \ref{sec:repeats})\\ |
| 431 |
% \kvdesc{shift} & Shift the extend distance downward; this affects both the |
| 432 |
% top and bottom of the column (see sec. \ref{sec:extend})\\ |
| 433 |
% \kvdesc{triple} & Draw three copies of the rule (see sec. |
| 434 |
% \ref{sec:repeats})\\ |
| 435 |
% \kvdesc{width} & Set the width of the rule (see sec. |
| 436 |
% \ref{sec:width})\\ |
| 437 |
% \bottomrule |
| 438 |
% \end{longtable} |
| 439 |
% |
| 440 |
% \begin{multicols}{2}[\subsection{Styles with the `line-style' option}^^A |
| 441 |
% \label{sec:linestyles}] |
| 442 |
% \SetMCRule{width=4pt,line-style=solid-circles} |
| 443 |
% |
| 444 |
% You\stydsc{line-style=solid-circles, width=4pt} can choose a style for the |
| 445 |
% rule with the \kvdesc{line-style} key. If the predefined styles are |
| 446 |
% insufficient for your purpose, see section \ref{sec:custom} for different |
| 447 |
% ways to customize the rule in even more radical ways. The width of many line |
| 448 |
% styles scales directly with the setting of \cs{columnseprule}, the default |
| 449 |
% \LaTeX{} length that controls the width of the column rule, but even those |
| 450 |
% that do not, the width must be non-zero for the rule to display (see section |
| 451 |
% \ref{sec:width}). |
| 452 |
% |
| 453 |
% Table \ref{table:linestyles} summarizes the available line styles. Most of |
| 454 |
% the basic patterns come in three versions, differing only in how closely the |
| 455 |
% pattern is spaced: normal, dense, and loose. These settings parallel those |
| 456 |
% found in \pkg{tikz} and use the same spacing between elements. There are no |
| 457 |
% named settings for double lines and the like because you control that feature |
| 458 |
% separately, with the \kvdesc{repeat} key. All line styles can be repeated as |
| 459 |
% many times as you like (see section \ref{sec:repeats}). |
| 460 |
% \end{multicols} |
| 461 |
% |
| 462 |
% \begin{longtable}{lp{3in}} |
| 463 |
% \caption{Styles available for the line-style key\label{table:linestyles}}\\ |
| 464 |
% \toprule |
| 465 |
% Style & Description\\ |
| 466 |
% \midrule |
| 467 |
% \endfirsthead |
| 468 |
% \caption{Available line-style settings (cont.)} \\ |
| 469 |
% \toprule |
| 470 |
% Style & Description\\ |
| 471 |
% \midrule |
| 472 |
% \endhead |
| 473 |
% \kvdesc{circles} & A series of hollow circles (\emph{tikz |
| 474 |
% only})\\ |
| 475 |
% \kvdesc{dash-dot} & A dash followed by a square dot (\emph{tikz |
| 476 |
% only})\\ |
| 477 |
% \kvdesc{dash-dot-dot} & A dash followed by two square dots |
| 478 |
% (\emph{tikz only})\\ |
| 479 |
% \kvdesc{dashed} & A series of dashed lines\\ |
| 480 |
% \kvdesc{default} & A solid rule drawn the same way as the default |
| 481 |
% \pkg{multicol} rule. Does not support extended rules.\\ |
| 482 |
% \kvdesc{dense-circles} & The same as \kvdesc{circles} |
| 483 |
% but more closely spaced (\emph{tikz only})\\ |
| 484 |
% \kvdesc{dense-dots} & The same as \kvdesc{dots} but |
| 485 |
% more closely spaced\\ |
| 486 |
% \kvdesc{dense-solid-circles} & The same as \kvdesc{solid-circles} but more |
| 487 |
% closely spaced (\emph{tikz only})\\ |
| 488 |
% \kvdesc{densely-dash-dot} & The same as \kvdesc{dash-dot} but more closely |
| 489 |
% spaced (\emph{tikz only})\\ |
| 490 |
% \kvdesc{densely-dash-dot-dot} & The same as \kvdesc{dash-dot-dot} but more |
| 491 |
% closely spaced (\emph{tikz only})\\ |
| 492 |
% \kvdesc{densely-dashed} & The same as \kvdesc{dashed} but more closely |
| 493 |
% spaced\\ |
| 494 |
% \kvdesc{densely-dotted} & The same as \kvdesc{dotted} but more closely |
| 495 |
% spaced\\ |
| 496 |
% \kvdesc{dots} & A series of dots drawn with the period (full-stop) of the |
| 497 |
% current font\\ |
| 498 |
% \kvdesc{dotted} & A series of square dots\\ |
| 499 |
% \kvdesc{loose-dots} & The same as \kvdesc{dots} but spaced further apart\\ |
| 500 |
% \kvdesc{loose-circles} & The same as \kvdesc{circles} but spaced further |
| 501 |
% apart (\emph{tikz only})\\ |
| 502 |
% \kvdesc{loose-solid-circles} & The same as \kvdesc{solid-circles} but |
| 503 |
% spaced further apart (\emph{tikz only})\\ |
| 504 |
% \kvdesc{loosely-dash-dot} & The same as \kvdesc{dash-dot} but spaced |
| 505 |
% further apart (\emph{tikz only})\\ |
| 506 |
% \kvdesc{loosely-dash-dot-dot} & The same as \kvdesc{dash-dot-dot} but |
| 507 |
% spaced further apart (\emph{tikz only})\\ |
| 508 |
% \kvdesc{loosely-dashed} & The same as \kvdesc{dashed} but spaced further |
| 509 |
% apart\\ |
| 510 |
% \kvdesc{loosely-dotted} & The same as \kvdesc{dotted} but spaced further |
| 511 |
% apart\\ |
| 512 |
% \kvdesc{solid} & A solid line, like \kvdesc{default}, but supports extending |
| 513 |
% rules\\ |
| 514 |
% \kvdesc{solid-circles} & A series of filled circles (\emph{tikz only})\\ |
| 515 |
% \kvdesc{strut} & An invisible (0pt) strut is drawn in place of a solid rule.\\ |
| 516 |
% \bottomrule |
| 517 |
% \end{longtable} |
| 518 |
% |
| 519 |
% \begin{multicols}{2} |
| 520 |
% \SetMCRule{width=thin,line-style=solid} |
| 521 |
% The\stydsc{line-style=solid} \kvdesc{default} and \kvdesc{solid} line styles |
| 522 |
% are nearly the same, except that the \kvdesc{solid} line (as of version 1.1) |
| 523 |
% supports the rule-extension commands described in section \ref{sec:extend}. |
| 524 |
% This means that if you want a solid rule with altered top or bottom |
| 525 |
% extensions, you must explicitly set the line style to \kvdesc{solid}. If you |
| 526 |
% make no calls to \cs{SetMCRule} after loading \mcrule, the column divider |
| 527 |
% will continue to behave exactly as it does with the ordinary \pkg{multicol} |
| 528 |
% package. |
| 529 |
% |
| 530 |
% You can alter the rule's width and color either through \cs{SetMCRule} with |
| 531 |
% the \kvdesc{width} and \kvdesc{color} keys described in sections |
| 532 |
% \ref{sec:width} and \ref{sec:color}, respectively, or directly by changing |
| 533 |
% the value of \cs{columnseprule} and renewing the \cs{columnseprulecolor} |
| 534 |
% macro. |
| 535 |
% |
| 536 |
% The \kvdesc{dots} style and its variants are rendered with a period (.) in |
| 537 |
% the currently active font. This is one of the styles, mentioned above, that |
| 538 |
% do not change their size as the line width increases. The same is true of |
| 539 |
% custom tiles. |
| 540 |
% |
| 541 |
% The \kvdesc{dotted} styles differ from \kvdesc{dots} in that the former are |
| 542 |
% squares with side lengths equal to \cs{columnseprule}. This mirrors the |
| 543 |
% behavior of the equivalently named dotted patterns in \pkg{tikz}. |
| 544 |
% |
| 545 |
% The \kvdesc{strut} style draws a 0pt rule. Like every other line style, |
| 546 |
% however, the value of \cs{columnseprule} must be greater than 0pt for it |
| 547 |
% to be drawn. An invisible rule can be useful if you want to disable a rule |
| 548 |
% in the middle of a cycle of patterns or in conjunction with the extend |
| 549 |
% various extend options. See section \ref{sec:extend}. |
| 550 |
% \end{multicols} |
| 551 |
% |
| 552 |
% \subsubsection{Custom Patterns}\label{sec:custom} |
| 553 |
% \noindent\texttt{custom-tile =} \marg{pattern} \marg{space above} |
| 554 |
% \marg{space below} |
| 555 |
% \begin{multicols}{2} |
| 556 |
% \SetMCRule{custom-tile={\SparkleBold}{16pt}{16pt}} |
| 557 |
% |
| 558 |
% There\stydsc{custom-tile= \{\textbackslash SparkleBold\} \{16pt\}\{16pt\}} |
| 559 |
% are three options to create custom rules with \mcrule. The first is the |
| 560 |
% \kvdesc{custom-tile} key. This creates a rule consisting of vertically |
| 561 |
% stacked boxes of arbitrary content---the tile---running the height of the |
| 562 |
% column separator. The \kvdesc{custom-tile} key takes three parameters, |
| 563 |
% which must all be enclosed brackets and may not be omitted. The first |
| 564 |
% should contain the tokens you want to appear as the content of the tile. |
| 565 |
% The second is a dimension specifying the leading vertical space to apply |
| 566 |
% above each copy of the tile. The third is a dimension specifying the |
| 567 |
% trailing vertical space to insert below each copy of the tile. |
| 568 |
% |
| 569 |
% The rule in this section uses the \cs{SparkleBold} symbol from |
| 570 |
% \pkg{bbding}. Notice that when you use the \kvdesc{custom-tile} parameter, |
| 571 |
% or any of the other custom key commands, you do \emph{not} specify a separate |
| 572 |
% \kvdesc{line-style}. If you try to provide both, the last style given in the |
| 573 |
% list will be the one that is kept. |
| 574 |
% \end{multicols} |
| 575 |
% |
| 576 |
% \begin{multicols}{2}[\noindent\texttt{custom-pattern =} \marg{pattern} \marg{shift |
| 577 |
% down} \marg{shift up}] |
| 578 |
% \SetMCRule{custom-pattern={\HandRight}{0pt}{0pt}} |
| 579 |
% |
| 580 |
% The\stydsc{custom-pattern= \{\textbackslash HandRight\} \{0pt\}\{0pt\}} |
| 581 |
% second custom option is with the \kvdesc{custom-pattern} key. The syntax |
| 582 |
% is identical to that for \kvdesc{custom-tile}, but the content you specify |
| 583 |
% will appear once per page or column pair (if the columns occupy less than a |
| 584 |
% full page). This content will be vertically centered if the second and third |
| 585 |
% parameters are both 0pt. You can shift the content down by increasing the |
| 586 |
% second parameter, and up by increasing the third. The rule in this section |
| 587 |
% uses the \cs{HandRight} symbol from \pkg{bbding}. |
| 588 |
% \end{multicols} |
| 589 |
% |
| 590 |
% \begin{multicols}{2}[\noindent\texttt{custom-line =} \marg{draw command}] |
| 591 |
% \SetMCRule{custom-line={\path (TOP) to [ornament=88] (BOT);}} |
| 592 |
% |
| 593 |
% The\stydsc{custom-line=\{\textbackslash path (TOP) to [ornament=88] |
| 594 |
% (BOT);\}} third custom |
| 595 |
% pattern involves setting your own \pkg{tikz} drawing |
| 596 |
% function using the key \kvdesc{custom-line}. The rule in this section is |
| 597 |
% drawn with an ornament from \pkg{pgfornaments}. Obviously, this feature |
| 598 |
% requires \pkg{tikz} support. The value you provide to the |
| 599 |
% \kvdesc{custom-line} key should consist of a \pkg{tikz} command, such as |
| 600 |
% \cs{draw} or \cs{path}, without the surrounding \env{tikzpicture} |
| 601 |
% environment. |
| 602 |
% |
| 603 |
% Before the drawing command is called, \mcrule{} will set up a |
| 604 |
% \env{tikzpicture} with both the x- and y-coordinates scaled to points, and |
| 605 |
% two nodes, named \texttt{(TOP)} and \texttt{(BOT)}, which are set to the |
| 606 |
% coordinates of the top and bottom of the rule. You can then specify your own |
| 607 |
% \cs{draw} or \cs{path} function in whatever way you like. The rule separating |
| 608 |
% these columns was drawn with a decorative element from the \pkg{pgfornaments} |
| 609 |
% package. |
| 610 |
% |
| 611 |
% This function will use the color set in |
| 612 |
% \cs{columnseprulecolor} if you don't set it explicitly within the tikz |
| 613 |
% command, but you must provide everything else necessary to draw the line |
| 614 |
% correctly, including the line width. Note that nothing limits you to drawing |
| 615 |
% a picture that fits within the space between the columns. If the rule is |
| 616 |
% wider than the available space, it will be centered between the columns and |
| 617 |
% overlap the text. Normally, of course, that will be undesirable, but you can |
| 618 |
% use it to your advantage in certain cases. The file \file{mcrule-example.pdf} |
| 619 |
% contains examples showing the effect of a rule that is too wide, as well as |
| 620 |
% a custom rule which includes horizontal rules at the top and bottom of the |
| 621 |
% column.\footnote{This latter rule was developed as an answer to |
| 622 |
% \href{https://tex.stackexchange.com/questions/473828/horizontal-rules-before-and-after-multicols} |
| 623 |
% {StackExchange question 473828}.} |
| 624 |
% \end{multicols} |
| 625 |
% |
| 626 |
% \begin{multicols}{2}[\subsection{Colors}\label{sec:color}] |
| 627 |
% \SetMCRule{width=2pt,line-style=solid,color-model=cmy,color={0.7,0.5,0.3}} |
| 628 |
% You\stydsc{line-style=solid,\\width=2pt\\color-model=cmy,\\ |
| 629 |
% color=\{0.7,0.5,0.3\}} can set colors for the rule through the |
| 630 |
% \kvdesc{color} and, optionally, the \kvdesc{color-model} keys. \mcrule{} loads the |
| 631 |
% \pkg{xcolor} package to manage colors, and the \kvdesc{color} |
| 632 |
% parameter accepts any name that \pkg{xcolor} recognizes, either natively or |
| 633 |
% as the result of any names you have defined with \cs{definecolor} |
| 634 |
% (see the \pkg{xcolor} documentation). Note that if you want to use color names that |
| 635 |
% are defined through the one of \pkg{xcolor}'s package options, you must load |
| 636 |
% \pkg{xcolor} before both \mcrule{} and \pkg{tikz} with the relevant options. |
| 637 |
% |
| 638 |
% To specify a color by a numeric specification, you use the |
| 639 |
% \kvdesc{color-model} parameter to specify any color model that |
| 640 |
% \pkg{xcolor} recognizes (rgb, cmy, etc), and \kvdesc{color} to |
| 641 |
% hold the color-specification list. Because that list is itself comma-separated, |
| 642 |
% you must enclose it in brackets. |
| 643 |
% |
| 644 |
% The current color setting can always be found in |
| 645 |
% \cs{columnseprulecolor}. If you are running in twocolumn |
| 646 |
% mode without \pkg{multicol}, this command will be provided and colors will |
| 647 |
% work the same way they do with \pkg{multicol}. Note that setting the |
| 648 |
% \kvdesc{color} key causes \cs{columnseprulecolor} |
| 649 |
% to be redefined within the current group only. If you directly redefine |
| 650 |
% \cs{columnseprulecolor}, the color of the custom rule will |
| 651 |
% reflect this setting. This way, the settings of any packages that might alter |
| 652 |
% the rule color will be respected. |
| 653 |
%\end{multicols} |
| 654 |
% |
| 655 |
% \begin{multicols}{2}[\subsection{Width}\label{sec:width}] |
| 656 |
% \SetMCRule{width=thick,line-style=dash-dot-dot} |
| 657 |
% You\stydsc{line-style= dash-dot-dot,\\ width=thick} can set the width of the |
| 658 |
% rule with the \kvdesc{width} key. Legal values are any explicit dimension or |
| 659 |
% dimension expression, as well as one of the names listed in table |
| 660 |
% \ref{table:linewidths}. These names parallel those used by \pkg{tikz}, except |
| 661 |
% that spaces in the key names are replaced with hyphens. |
| 662 |
% |
| 663 |
% The current width of the rule is kept in \cs{columnseprule}, just as in |
| 664 |
% vanilla \LaTeX, and if it is set separately, the custom rule's width will |
| 665 |
% reflect this change. Note that although some line styles do not depend |
| 666 |
% directly on \cs{columnseprule} to calculate their actual width, the value |
| 667 |
% of \cs{columnseprule} must be greater than 0pt for any rule to appear. This |
| 668 |
% behavior is intentional and is in keeping with the way the default column |
| 669 |
% rules work. |
| 670 |
% \end{multicols} |
| 671 |
% |
| 672 |
% \begin{longtable}{ll} |
| 673 |
% \caption{Sizes of named line widths\label{table:linewidths}} \\ |
| 674 |
% \toprule |
| 675 |
% Name & Width\\ |
| 676 |
% \midrule |
| 677 |
% \endfirsthead |
| 678 |
% \caption{Sizes of named line widths (cont.)} \\ |
| 679 |
% \toprule |
| 680 |
% Name & Width\\ |
| 681 |
% \midrule |
| 682 |
% \endhead |
| 683 |
% \kvdesc{ultra-thin} & 0.1pt\\ |
| 684 |
% \kvdesc{very-thin} & 0.2pt\\ |
| 685 |
% \kvdesc{thin} & 0.4pt\\ |
| 686 |
% \kvdesc{semithick} & 0.6pt\\ |
| 687 |
% \kvdesc{thick} & 0.8pt\\ |
| 688 |
% \kvdesc{very-thick} & 1.2pt\\ |
| 689 |
% \kvdesc{ultra-thick} & 1.6pt\\ |
| 690 |
% \bottomrule |
| 691 |
% \end{longtable} |
| 692 |
% |
| 693 |
% \begin{multicols}{2}[\subsection{Repeated Rules}\label{sec:repeats}] |
| 694 |
% \SetMCRule{line-style=dash-dot-dot,triple=2pt} |
| 695 |
% |
| 696 |
% You can\stydsc{line-style= dash-dot-dot, triple=2pt} draw multiple, |
| 697 |
% adjacent copies of any rule by setting the number of times to draw the rule |
| 698 |
% with the \kvdesc{repeat} key. The space between copies is controlled with the |
| 699 |
% \kvdesc{repeat-distance} key. Initially, this distance is set to |
| 700 |
% \cs{columnseprule}. Note that you must enter an actual dimension expression |
| 701 |
% for this distance. The names used for line widths are not accepted. |
| 702 |
% |
| 703 |
% The keys \kvdesc{single}, \kvdesc{double}, and \kvdesc{triple} are shorthand |
| 704 |
% methods to set the number of repeats and the \kvdesc{repeat-distance} at the |
| 705 |
% same time. If you use the key without a value \kvdesc{repeat-distance} is set |
| 706 |
% to \cs{columnseprule}. |
| 707 |
% |
| 708 |
% There are no checks made to ensure that repeated rules will fit in the |
| 709 |
% available space between columns, so you should be careful using these |
| 710 |
% commands, especially with thicker rules. |
| 711 |
% \end{multicols} |
| 712 |
% |
| 713 |
%\begin{multicols}{2}[\subsection{Extended Rules}\label{sec:extend}] |
| 714 |
% \SetMCRule{line-style=dashed,expand=-16pt} |
| 715 |
% |
| 716 |
% You\stydsc{line-style=dashed, expand=-16pt} can specify an additional amount |
| 717 |
% by which the top or bottom of the rule projects beyond the column's natural |
| 718 |
% length with the keys \kvdesc{extend-top} and \kvdesc{extend-bot}, each of |
| 719 |
% which can be set to a dimension expression. Extending the top of the rule |
| 720 |
% with a positive dimension will push the columns down from any preceding |
| 721 |
% material. A positive value for \kvdesc{extend-bot} does the same in the other |
| 722 |
% direction when a column ends in the middle of a page, but the rule will |
| 723 |
% extend into the the bottom margin if the column goes to the end of the page. |
| 724 |
% |
| 725 |
% Note that positive values for extending the rules should be used with |
| 726 |
% caution and only in situations where you need a special effect for one column |
| 727 |
% or a small \env{multicol} environment. (See section \ref{sec:patterns} for a |
| 728 |
% way to limit the change to one or a few columns.) Overprinting and other |
| 729 |
% bizarre effects can result from extending the rule in the wrong place. |
| 730 |
% Negative values for both keys may be more generally useful, as they have the |
| 731 |
% effect of shrinking the rule. This behavior is illustrated with the rule for |
| 732 |
% this section. |
| 733 |
% |
| 734 |
% The \kvdesc{expand} and \kvdesc{shift} keys provide shorthands for two |
| 735 |
% common situations. You can use \kvdesc{expand} to set the same value for |
| 736 |
% \kvdesc{extend-top} and \kvdesc{extend-bot} For example, |expand=-16pt| is |
| 737 |
% equivalent to |extend-bot=-16pt, extend-top=-16pt|. The \kvdesc{shift} key |
| 738 |
% moves the rule downward for positive values and upward for negative ones |
| 739 |
% without changing the overall length of the rule. More precisely, |shift=x| |
| 740 |
% translates to |extend-bot=x, extend-top=-x|. For example, |shift=16pt| is |
| 741 |
% equivalent to |extend-bot=16pt, extend-top=-16pt|. |
| 742 |
%\end{multicols} |
| 743 |
% |
| 744 |
%\begin{multicols}{2} |
| 745 |
% \SetMCRule{line-style=solid,extend-fill} |
| 746 |
% The\stydsc{line-style=solid, extend-fill} \kvdesc{extend-fill} key is a |
| 747 |
% boolean option that, when set to true, will extend the rule to occupy any |
| 748 |
% space between the bottom of the columns and the end of the text area. |
| 749 |
% Providing the key with no value is equivalent to |extend-fill=true|. This |
| 750 |
% option is only relevant for the \env{multicols} environment. It will have |
| 751 |
% no effect with either \env{multicols*} or the plain \LaTeX{} two-column mode. |
| 752 |
% |
| 753 |
% If you want text below and on the same page as the \env{multicols} |
| 754 |
% environment when using \kvdesc{extend-fill}, you can reserve space for it |
| 755 |
% with \kvdesc{extend-reserve}, which takes a dimension expression specifying |
| 756 |
% the vertical space to leave available after the rule. If the value is greater |
| 757 |
% than zero, the height of the extended line will be reduced by the reserved |
| 758 |
% amount plus the value of \cs{multicolsep}. In other words, you only have to |
| 759 |
% specify the actual space you need for the text itself, not the space that |
| 760 |
% \pkg{multicol} adds automatically below the columns. Note that if the amount |
| 761 |
% you request for reserved space is less than the amount actually available at |
| 762 |
% the end of the page, the rule will not extend below the columns and you |
| 763 |
% probably will find this material spilling onto the next page anyway. |
| 764 |
%\end{multicols} |
| 765 |
% |
| 766 |
%\subsection{Rule Patterns}\label{sec:patterns} |
| 767 |
% \begin{function}{\DeclareMCRulePattern} |
| 768 |
% \begin{syntax} |
| 769 |
% \cs{DeclareMCRulePattern} \marg{name} \marg{key-value list} |
| 770 |
% \end{syntax} |
| 771 |
% \end{function} |
| 772 |
%\DeclareMCRulePattern{left-hand}{custom-tile={\HandLeft}{8pt}{8pt}} |
| 773 |
%\DeclareMCRulePattern{right-hand}{custom-tile={\HandRight}{8pt}{8pt}} |
| 774 |
%\begin{multicols}{3} |
| 775 |
% \noindent \DescribeMacro{\DeclareMCRulePattern} |
| 776 |
% \SetMCRule{patterns={right-hand,left-hand}} |
| 777 |
% A\stydsc{patterns=\{right-hand, left-hand\}\\ See the code sample below for |
| 778 |
% the definitions of the patterns} \emph{pattern} refers to a bundle of |
| 779 |
% settings used by \mcrule. Although you can use patterns as a shortcut to save |
| 780 |
% you a little typing, their main purpose is to let you to alter individual |
| 781 |
% rules within a multicol environment. For example, if you have three-column |
| 782 |
% text, you can make the left rule different from the right one. In two-column |
| 783 |
% text, you can have different rules for alternating pages. |
| 784 |
% |
| 785 |
% You declare a pattern for a line style with the command |
| 786 |
% \cs{DeclareMCRulePattern}. The \meta{name} should consist of letters and |
| 787 |
% hyphens only. The \meta{key-value list} can contain all keys that are valid |
| 788 |
% for \cs{SetMCRule} with the exception of \kvdesc{patterns}, which is filtered |
| 789 |
% out. In other words, if you put something like |patterns=foo| in the |
| 790 |
% pattern definition, it will be ignored. |
| 791 |
% |
| 792 |
% Once you have declared a pattern, you can use it as a value for the |
| 793 |
% \kvdesc{patterns} argument of \cs{SetMCRule}. This key can accept either a |
| 794 |
% single pattern or a comma-separated list of patterns. If you use a |
| 795 |
% comma-separated list, make sure you enclose it in braces. |
| 796 |
% |
| 797 |
% When a pattern is in effect, its settings are applied on top of the prior |
| 798 |
% settings. If you set the key to an empty list, any patterns currently in |
| 799 |
% effect will be canceled, and \mcrule{} will revert to the previous settings. |
| 800 |
% |
| 801 |
% If the \kvdesc{patterns} key contains more than one pattern, \mcrule{} will |
| 802 |
% cycle through the list of patterns, using one pattern each time a rule is |
| 803 |
% drawn between columns. Note that the patterns do not cycle within a single |
| 804 |
% column separator if you use the \kvdesc{repeat} key. This cycle is global, |
| 805 |
% so if the number column separators is not a multiple of the number of |
| 806 |
% patterns and you start a new \env{multicols} environment with the same |
| 807 |
% patterns in effect, the cycle will pick up where it left off. Every time you |
| 808 |
% set new patterns, however, the cycle begins anew with the first pattern in |
| 809 |
% the list. |
| 810 |
%\end{multicols} |
| 811 |
% |
| 812 |
% \noindent The columns above were defined with the following commands: |
| 813 |
% |
| 814 |
% \medskip |
| 815 |
% |
| 816 |
% \begin{BVerbatim} |
| 817 |
% \DeclareMCRulePattern{left-hand}{custom-tile={\HandLeft}{8pt}{8pt}} |
| 818 |
% \DeclareMCRulePattern{right-hand}{custom-tile={\HandRight}{8pt}{8pt}} |
| 819 |
% \begin{multicols}{3} |
| 820 |
% \SetMCRule{patterns={right-hand,left-hand}} |
| 821 |
% ... |
| 822 |
% \end{multicols} |
| 823 |
% \end{BVerbatim} |
| 824 |
% |
| 825 |
%\DeclareMCRulePattern{shrink-me}{line-style=solid,extend-top=-3\baselineskip} |
| 826 |
%\begin{multicols}{3} |
| 827 |
% \SetMCRule{line-style=solid,patterns=shrink-me,pattern-for=1} |
| 828 |
% If\stydsc{patterns=shrink-me, pattern-for=1\\ See the code sample below for |
| 829 |
% the definition of `shrink-me'} you want to alter the rule only for certain |
| 830 |
% column separators, you can use |
| 831 |
% the \kvdesc{pattern-after} and \kvdesc{pattern-for} keys, both of which |
| 832 |
% take integer values, in conjunction with \kvdesc{patterns}. |
| 833 |
% |
| 834 |
% The \kvdesc{pattern-for} key means ``use the given pattern or patterns for |
| 835 |
% this many column separators only.'' Afterwards, the pattern will be disabled, |
| 836 |
% meaning that it won't be applied any more and only the settings applied |
| 837 |
% directly will be in effect until it is reset. A negative value to this key |
| 838 |
% means that the patterns will be repeated indefinitely. The default is $-1$. |
| 839 |
% |
| 840 |
% The \kvdesc{pattern-after} key means ``wait until after this many column |
| 841 |
% separators before starting to apply the pattern. The default is 0. If you use |
| 842 |
% it in conjunction with \kvdesc{pattern-for}, the count of modified column |
| 843 |
% separators begins after the skipped columns. |
| 844 |
% |
| 845 |
% For example, suppose you have four-column text and want to alter the third |
| 846 |
% column separator on the first page of the environment only.\footnote{Remember |
| 847 |
% that you have one less column separator than you have columns.} You could |
| 848 |
% accomplish this task with the code below. |
| 849 |
% |
| 850 |
% Using predefined patterns adds processing overhead, since they must be |
| 851 |
% applied each time the rule is drawn. Therefore it is more efficient to avoid |
| 852 |
% patterns unless you need to actually change the line style from column to |
| 853 |
% column, although if you compile on a reasonably modern computer, you are |
| 854 |
% unlikely to notice too much delay. |
| 855 |
% |
| 856 |
% Note that any settings you provide in the same command where you apply a |
| 857 |
% \kvdesc{patterns} key do not alter definition of the pattern, even if they |
| 858 |
% come after the \kvdesc{patterns} key. Such settings will take effect before |
| 859 |
% the pattern is applied and will reappear after the pattern ends, if it does. |
| 860 |
% |
| 861 |
%\end{multicols} |
| 862 |
% |
| 863 |
% \noindent Shrinking the final two column separators in four-column text: |
| 864 |
% |
| 865 |
% \medskip |
| 866 |
% |
| 867 |
%\begin{BVerbatim} |
| 868 |
% \DeclareMCRulePattern{shrink-me}{line-style=solid, |
| 869 |
% extend-top=-3\baselineskip} |
| 870 |
% \begin{multicols}{4} |
| 871 |
% \SetMCRule{patterns=shrink-me,pattern-after=1,pattern-for=2} |
| 872 |
% ... |
| 873 |
% \end{multicols} |
| 874 |
%\end{BVerbatim} |
| 875 |
% |
| 876 |
%\end{documentation} |
| 877 |
% |
| 878 |
%\begin{implementation} |
| 879 |
% |
| 880 |
%\section{Implementation} |
| 881 |
% |
| 882 |
% \begin{macrocode} |
| 883 |
%<*package> |
| 884 |
% \end{macrocode} |
| 885 |
% |
| 886 |
% \begin{macrocode} |
| 887 |
%<@@=mcrule> |
| 888 |
% \end{macrocode} |
| 889 |
% |
| 890 |
%\subsection{Preliminaries} |
| 891 |
% |
| 892 |
% \begin{macrocode} |
| 893 |
\ProvidesExplPackage {multicolrule} {2020/09/14} {1.3a} |
| 894 |
{Decorative vertical rules between columns} |
| 895 |
% \end{macrocode} |
| 896 |
% |
| 897 |
% We always need these packages. |
| 898 |
% \begin{macrocode} |
| 899 |
\RequirePackage{l3keys2e} |
| 900 |
\RequirePackage{xpatch} |
| 901 |
\RequirePackage{xcolor} |
| 902 |
\RequirePackage{scrlfile} |
| 903 |
% \end{macrocode} |
| 904 |
% |
| 905 |
% Define the messages we use. |
| 906 |
% \begin{macrocode} |
| 907 |
\msg_new:nnn {multicolrule} {patch-success} {Patched~#1.} |
| 908 |
\msg_new:nnn {multicolrule} {patch-failure} {Error~patching~#1.} |
| 909 |
\msg_new:nnnn {multicolrule} {tikz-required} {Tikz~required} |
| 910 |
{The~'#1'~setting~requires~tikz~to~work.~Either~load~tikz~before~you~load~ |
| 911 |
multicolrule~or~use~multicolrule's~'tikz'~package~option.} |
| 912 |
\msg_new:nnnn {multicolrule} {multicol-loaded} {Multicol~loaded} {You~are~ |
| 913 |
using~the~'twocolumn'~option~with~multicol~already~loaded.~You~will~likely~ |
| 914 |
run~into~problems.} |
| 915 |
\msg_new:nnnn {multicolrule} {pattern-undefined} {Pattern~undefined} |
| 916 |
{The~multicolrule~pattern~'#1'~has~not~been~defined.} |
| 917 |
% \end{macrocode} |
| 918 |
% |
| 919 |
%\begin{variable}{\g_@@_twocolumn_bool,\g_@@_use_tikz_bool} |
| 920 |
% Flags for package options |
| 921 |
% \begin{macrocode} |
| 922 |
\bool_new:N \g_@@_twocolumn_bool |
| 923 |
\bool_new:N \g_@@_use_tikz_bool |
| 924 |
\bool_new:N \g_@@_paracol_bool |
| 925 |
% \end{macrocode} |
| 926 |
%\end{variable} |
| 927 |
% |
| 928 |
%\begin{variable}{\l_@@_repeat_int,\l_@@_repeat_distance_dim} |
| 929 |
% Variables to support repeated copies of the rule. |
| 930 |
% \begin{macrocode} |
| 931 |
\int_new:N \l_@@_repeat_int |
| 932 |
\int_set:Nn \l_@@_repeat_int {1} |
| 933 |
\dim_new:N \l_@@_repeat_distance_dim |
| 934 |
% \end{macrocode} |
| 935 |
%\end{variable} |
| 936 |
% |
| 937 |
%\begin{variable}{\l_@@_extend_top_dim, |
| 938 |
% \l_@@_extend_bot_dim, |
| 939 |
% \l_@@_extend_fill_bool, |
| 940 |
% \l_@@_extend_reserve_dim} |
| 941 |
% Variables to control the distance to extend the rule above and below the |
| 942 |
% natural column height. |
| 943 |
% \begin{macrocode} |
| 944 |
\dim_new:N \l_@@_extend_top_dim |
| 945 |
\dim_new:N \l_@@_extend_bot_dim |
| 946 |
\bool_new:N \l_@@_extend_fill_bool |
| 947 |
\dim_new:N \l_@@_extend_reserve_dim |
| 948 |
% \end{macrocode} |
| 949 |
%\end{variable} |
| 950 |
% |
| 951 |
%\begin{variable}{\l_@@_color_name_tl,\l_@@_color_model_tl} |
| 952 |
% Keep name and color model so we can set them separately while retaining |
| 953 |
% the value of the other one. |
| 954 |
% \begin{macrocode} |
| 955 |
\tl_new:N \l_@@_color_name_tl |
| 956 |
\tl_new:N \l_@@_color_model_tl |
| 957 |
% \end{macrocode} |
| 958 |
%\end{variable} |
| 959 |
% |
| 960 |
%\begin{variable}{\g_@@_patterns_prop, \g_@@_pattern_count_int, |
| 961 |
% \g_@@_pattern_for_int, \g_@@_pattern_after_int, |
| 962 |
% \l_@@_pattern_list_seq} |
| 963 |
% Variables to support defined patterns. |
| 964 |
% \begin{macrocode} |
| 965 |
\prop_new:N \g_@@_patterns_prop |
| 966 |
\int_new:N \g_@@_pattern_count_int |
| 967 |
\int_new:N \g_@@_pattern_for_int |
| 968 |
\int_new:N \g_@@_pattern_after_int |
| 969 |
\seq_new:N \l_@@_pattern_list_seq |
| 970 |
% \end{macrocode} |
| 971 |
%\end{variable} |
| 972 |
% |
| 973 |
% If \pkg{tikz} is already loaded, enable \pkg{tikz}-sensitive line styles |
| 974 |
% unless the user explicitly disables them. If \pkg{tikz} is not already |
| 975 |
% loaded, these functions are disabled unless they are explicitly loaded. |
| 976 |
% |
| 977 |
% \begin{macrocode} |
| 978 |
\@ifpackageloaded{tikz} |
| 979 |
{ |
| 980 |
\bool_gset_true:N \g_@@_use_tikz_bool |
| 981 |
}{} |
| 982 |
% \end{macrocode} |
| 983 |
% |
| 984 |
% Set up the keys for package options and process them. |
| 985 |
% |
| 986 |
% \begin{macrocode} |
| 987 |
\keys_define:nn {mcrule-opts} |
| 988 |
{ |
| 989 |
twocolumn .bool_gset:N = \g_@@_twocolumn_bool, |
| 990 |
twocolumn .default:n = true, |
| 991 |
tikz .bool_gset:N = \g_@@_use_tikz_bool, |
| 992 |
tikz .default:n = true, |
| 993 |
paracol .bool_gset:N = \g_@@_paracol_bool, |
| 994 |
paracol .default:n = true, |
| 995 |
} |
| 996 |
\ProcessKeysOptions{mcrule-opts} |
| 997 |
% \end{macrocode} |
| 998 |
% |
| 999 |
% \subsection{Patching Output Routines}\label{sec:patching} |
| 1000 |
% Now that we know what mode we're going to run in, we patch the output |
| 1001 |
% routine(s) to substitute our custom rule for the vanilla one. Since |
| 1002 |
% \pkg{multicol} doesn't fully support twocolumn mode, we patch one or the |
| 1003 |
% other, but not both. |
| 1004 |
% |
| 1005 |
% First we set some stubs for functions we'll need to redirect depending on |
| 1006 |
% the mode we're operating in. |
| 1007 |
% |
| 1008 |
%\begin{macro}{\@@_column_height:} |
| 1009 |
% Returns the fixed height of the columns. The actual code to calculate the |
| 1010 |
% height is set when we set the appropriate mode. |
| 1011 |
% |
| 1012 |
% \begin{macrocode} |
| 1013 |
\cs_new:Npn \@@_column_height: {} |
| 1014 |
% \end{macrocode} |
| 1015 |
%\end{macro} |
| 1016 |
% |
| 1017 |
%\begin{macro}{\@@_column_depth:} |
| 1018 |
% Returns the maximum depth of the columns. The actual code to calculate the |
| 1019 |
% depth is set when we set the appropriate mode. |
| 1020 |
% |
| 1021 |
% \begin{macrocode} |
| 1022 |
\cs_new:Npn \@@_column_depth: {} |
| 1023 |
% \end{macrocode} |
| 1024 |
%\end{macro} |
| 1025 |
% |
| 1026 |
%\begin{macro}{\@@_column_overflow:} |
| 1027 |
% Returns the amount by which text overflows the bottom of the columns. This |
| 1028 |
% situation occurs in \pkg{multicol} when \cs{maxbalancingoverflow} is greater |
| 1029 |
% than 0 (by default it's 12pt) and there would otherwise be a widow at the end |
| 1030 |
% of the environment, so we don't check for it in two-column mode. |
| 1031 |
% \changes{v1.2a}{2019/2/12}{New internal function} |
| 1032 |
% |
| 1033 |
% \begin{macrocode} |
| 1034 |
\cs_new:Npn \@@_column_overflow: {0pt} |
| 1035 |
% \end{macrocode} |
| 1036 |
%\end{macro} |
| 1037 |
% |
| 1038 |
%\begin{macro}{\@@_patch_mcol_output:N} |
| 1039 |
% We create a helper macro to simplify patching the appropriate part of the |
| 1040 |
% relevant \pkg{multicol} routines. The search and replace texts are identical |
| 1041 |
% across several routines, so only the name of the function to be patched |
| 1042 |
% needs to be passed as a parameter. We make \cs{columnseprulecolor} |
| 1043 |
% part of \cs{mcruledivider} so that we can set the color as part of a |
| 1044 |
% style pattern. |
| 1045 |
% \changes{v1.2}{2019/1/1}{Move \cs{columnseprulecolor} inside |
| 1046 |
% \cs{mcruledivider}} |
| 1047 |
% \begin{macrocode} |
| 1048 |
\cs_new_protected:Npn \@@_patch_mcol_output:N #1 |
| 1049 |
{ |
| 1050 |
\xpatchcmd{#1} {\columnseprulecolor\vrule\@width\columnseprule} |
| 1051 |
{\mcruledivider} |
| 1052 |
{\msg_info:nnn {multicolrule} {patch-success} {#1}} |
| 1053 |
{\msg_info:nnn {multicolrule} {patch-failure} {#1}} |
| 1054 |
} |
| 1055 |
% \end{macrocode} |
| 1056 |
%\end{macro} |
| 1057 |
% |
| 1058 |
%\begin{macro}{\@@_patch_twocol_output:N} |
| 1059 |
% The same idea as above, only for the vanilla twocolumn mode. |
| 1060 |
% \changes{v1.2}{2019/1/1}{Move \cs{columnseprulecolor} inside |
| 1061 |
% \cs{mcruledivider}} |
| 1062 |
% \begin{macrocode} |
| 1063 |
\cs_new_protected:Npn \@@_patch_twocol_output:N #1 |
| 1064 |
{ |
| 1065 |
\xpatchcmd{#1} {\normalcolor\vrule\@width\columnseprule} |
| 1066 |
{\mcruledivider} |
| 1067 |
{\msg_info:nnn {multicolrule} {patch-success} {#1}} |
| 1068 |
{\msg_info:nnn {multicolrule} {patch-failure} {#1}} |
| 1069 |
} |
| 1070 |
% \end{macrocode} |
| 1071 |
%\end{macro} |
| 1072 |
% |
| 1073 |
% Now the actual patching begins. |
| 1074 |
% |
| 1075 |
% \begin{macrocode} |
| 1076 |
\bool_if:NTF \g_@@_twocolumn_bool |
| 1077 |
{ |
| 1078 |
\@ifpackageloaded{multicol} |
| 1079 |
{\msg_warning:nn {multicolrule} {multicol-loaded}}{} |
| 1080 |
% \end{macrocode} |
| 1081 |
% |
| 1082 |
% Default \LaTeX{} lacks \cs{columnseprulecolor}, so if we're in two-column |
| 1083 |
% mode, we provide it here. |
| 1084 |
% |
| 1085 |
% \begin{macrocode} |
| 1086 |
\cs_gset:Npn \columnseprulecolor {\normalcolor} |
| 1087 |
% \end{macrocode} |
| 1088 |
% |
| 1089 |
% In vanilla twocolumn mode, the column height and depth can be taken directly |
| 1090 |
% from \cmd{\@outputbox}. |
| 1091 |
% |
| 1092 |
% \begin{macrocode} |
| 1093 |
\cs_gset:Npn \@@_column_height: {\box_ht:N \@outputbox} |
| 1094 |
\cs_gset:Npn \@@_column_depth: {\box_dp:N \@outputbox} |
| 1095 |
% \end{macrocode} |
| 1096 |
% |
| 1097 |
% Now patch the relevant code in \cmd{\@outputdblcol}, replacing the hard-coded |
| 1098 |
% rule with a macro that we can overwrite. |
| 1099 |
% |
| 1100 |
% \begin{macrocode} |
| 1101 |
\@@_patch_twocol_output:N \@outputdblcol |
| 1102 |
% \end{macrocode} |
| 1103 |
% |
| 1104 |
% \pkg{bidi} has two output routines to patch, and it insists on being loaded |
| 1105 |
% after \pkg{xcolor}, \pkg{tikz}, \emph{and} \pkg{multicol}, so it must always |
| 1106 |
% be loaded after us. We use \cs{AfterPackage} from \pkg{scrlfile} to insert |
| 1107 |
% the patch if \pkg{bidi} is loaded later on. |
| 1108 |
% \changes{v1.3a}{2020/9/14}{Update scrlfile command because of API change in that package.} |
| 1109 |
% |
| 1110 |
% \begin{macrocode} |
| 1111 |
\AfterAtEndOfPackage*{bidi} |
| 1112 |
{ |
| 1113 |
\@@_patch_twocol_output:N \RTL@outputdblcol |
| 1114 |
\@@_patch_twocol_output:N \LTR@outputdblcol |
| 1115 |
} |
| 1116 |
} |
| 1117 |
% \end{macrocode} |
| 1118 |
% |
| 1119 |
% Now patch for \pkg{multicol}. |
| 1120 |
% |
| 1121 |
% \begin{macrocode} |
| 1122 |
{ |
| 1123 |
\RequirePackage{multicol} |
| 1124 |
\@@_patch_mcol_output:N \LR@column@boxes |
| 1125 |
\@@_patch_mcol_output:N \RL@column@boxes |
| 1126 |
% \end{macrocode} |
| 1127 |
% |
| 1128 |
% In LTR mode, we are invoked after a column has been typeset, which destroys |
| 1129 |
% their boxes in the process. So the only boxes we can be sure still exist are |
| 1130 |
% \cmd{\mult@rightbox}, which will be set to the same column height as all the |
| 1131 |
% others, and \cmd{\mult@nat@firstbox}, which contains the first column at its |
| 1132 |
% natural height. |
| 1133 |
% |
| 1134 |
% \begin{macrocode} |
| 1135 |
\cs_gset:Npn \@@_column_height: |
| 1136 |
{ |
| 1137 |
\box_ht:N \mult@rightbox |
| 1138 |
} |
| 1139 |
% \end{macrocode} |
| 1140 |
% |
| 1141 |
% Since the depth can differ from column to column, we use |\dimen\tw@|, |
| 1142 |
% which \pkg{multicol} uses to hold the maximum depth of all the columns |
| 1143 |
% already typeset, but as it won't have reached the final one yet, we check |
| 1144 |
% that too. This could lead to an inconsistent height in the event that |
| 1145 |
% there are 3 or more columns and a middle column has a significantly larger |
| 1146 |
% depth than either the previous columns or the last column, but for now it |
| 1147 |
% does not seem worth accounting for a condition that is likely to be very |
| 1148 |
% rare in actual user documents. |
| 1149 |
% \changes{v1.2a}{2019/2/12}{Check depth of final column} |
| 1150 |
% |
| 1151 |
% \begin{macrocode} |
| 1152 |
\cs_gset:Npn \@@_column_depth: |
| 1153 |
{ |
| 1154 |
\dim_max:nn {\dimen\tw@}{\box_dp:N \mult@rightbox} |
| 1155 |
} |
| 1156 |
% \end{macrocode} |
| 1157 |
% |
| 1158 |
% To avoid widows, \pkg{multicol} allows some overflow, by default up to 12pt, |
| 1159 |
% and so it's possible that some text will overflow beyond the fixed bottom of |
| 1160 |
% the column. In this case, our rule won't descend far enough. To correct, we |
| 1161 |
% measure the column overflow as the difference between the natural height of |
| 1162 |
% the first box and the height of the last column, and add that amount if it's |
| 1163 |
% greater than 0pt. |
| 1164 |
% |
| 1165 |
% \begin{macrocode} |
| 1166 |
\cs_gset:Npn \@@_column_overflow: |
| 1167 |
{ |
| 1168 |
\dim_max:nn {\box_ht:N \mult@nat@firstbox - \box_ht:N \mult@rightbox}{0pt} |
| 1169 |
} |
| 1170 |
% \end{macrocode} |
| 1171 |
% |
| 1172 |
% We need to reissue \cs{LRmulticolcolumns} to update the actual code in |
| 1173 |
% \cmd{\mc@align@columns}. |
| 1174 |
% |
| 1175 |
% \begin{macrocode} |
| 1176 |
\LRmulticolcolumns |
| 1177 |
% \end{macrocode} |
| 1178 |
% |
| 1179 |
% The \pkg{bidi} package supplies its own versions of most core |
| 1180 |
% \pkg{multicol} functions, including the output boxes. Much of this is |
| 1181 |
% unnecessary, as current versions of \pkg{multicol} support printing the |
| 1182 |
% columns in right-to-left order, and the effect is to leave the original |
| 1183 |
% \pkg{multicol} definitions loaded but unused. As a result, after these |
| 1184 |
% changes, the \pkg{multicol} commands \cs{LRmulticolcolumns} and |
| 1185 |
% \cs{RLmulticolcolumns} have no visible effect. First we replace |
| 1186 |
% \pkg{bidi}'s copies of the column boxes routines with our patched version. |
| 1187 |
% |
| 1188 |
% \begin{macrocode} |
| 1189 |
\AfterPackage!{bidi} |
| 1190 |
{ |
| 1191 |
\cs_gset_eq:NN \LTR@column@boxes \LR@column@boxes |
| 1192 |
\cs_gset_eq:NN \RTL@column@boxes \RL@column@boxes |
| 1193 |
% \end{macrocode} |
| 1194 |
% |
| 1195 |
% While we're at it, we also redefine \cs{LRmulticolcolumns} and |
| 1196 |
% \cs{RLmulticolcolumns} so they work the way people expect them to. |
| 1197 |
% |
| 1198 |
% \begin{macrocode} |
| 1199 |
\cs_gset_eq:NN \LRmulticolcolumns \LTRmulticolcolumns |
| 1200 |
\cs_gset_eq:NN \RLmulticolcolumns \RTLmulticolcolumns |
| 1201 |
} |
| 1202 |
} |
| 1203 |
% \end{macrocode} |
| 1204 |
% |
| 1205 |
% \subsection{Creating the Rules} |
| 1206 |
% Now we declare utility functions for different rule types. |
| 1207 |
% |
| 1208 |
%\begin{function}{\mcruledivider} |
| 1209 |
% This is the function directly called by the patched output routines. Its main |
| 1210 |
% purpose is to call the internal function \cs{mcrule_divider:}, which contains |
| 1211 |
% the actual rule-typesetting instructions, the number of times specified in |
| 1212 |
% \cs{l_@@_repeat_int}. \pkg{multicol} puts the rule in a group in order to keep |
| 1213 |
% the color contained, which means that any local changes here will be lost at |
| 1214 |
% the end of the rule. For this reason, we must set the pattern, if any, here in |
| 1215 |
% order to support having different line styles between different columns. |
| 1216 |
% |
| 1217 |
% \begin{macrocode} |
| 1218 |
\cs_new_protected:Npn \mcruledivider |
| 1219 |
{ |
| 1220 |
% \end{macrocode} |
| 1221 |
% \changes{v1.2}{2019/1/1}{Add pattern support} |
| 1222 |
% If the |pattern-after| counter is set, wait that many iterations of the rule |
| 1223 |
% before we apply the patterns. |
| 1224 |
% \begin{macrocode} |
| 1225 |
\int_compare:nNnTF {\g_@@_pattern_after_int} > {\c_zero_int} |
| 1226 |
{ |
| 1227 |
\int_gdecr:N \g_@@_pattern_after_int |
| 1228 |
} |
| 1229 |
{ |
| 1230 |
% \end{macrocode} |
| 1231 |
% |
| 1232 |
% Don't change if the pattern is empty or the |pattern-for| counter has |
| 1233 |
% expired. The way the logic works here, negative values of |pattern-for| |
| 1234 |
% result in an indefinite number of repeats. |
| 1235 |
% |
| 1236 |
% \begin{macrocode} |
| 1237 |
\bool_lazy_and:nnT |
| 1238 |
{\int_compare_p:nNn {\seq_count:N \l_@@_pattern_list_seq} > {\c_zero_int}} |
| 1239 |
{! \int_compare_p:nNn {\g_@@_pattern_for_int} = {\c_zero_int}} |
| 1240 |
{ |
| 1241 |
\int_gincr:N \g_@@_pattern_count_int |
| 1242 |
\int_compare:nNnT {\g_@@_pattern_count_int} > |
| 1243 |
{\seq_count:N \l_@@_pattern_list_seq} |
| 1244 |
{ |
| 1245 |
\int_gset:Nn \g_@@_pattern_count_int {\c_one_int} |
| 1246 |
} |
| 1247 |
\tl_set:Nx \l_tmpa_tl {\seq_item:Nn \l_@@_pattern_list_seq |
| 1248 |
{\g_@@_pattern_count_int} } |
| 1249 |
\tl_if_blank:VF \l_tmpa_tl |
| 1250 |
{ |
| 1251 |
\@@_set_pattern:V \l_tmpa_tl |
| 1252 |
} |
| 1253 |
\int_compare:nNnT {\g_@@_pattern_for_int} > {\c_zero_int} |
| 1254 |
{ |
| 1255 |
\int_gdecr:N \g_@@_pattern_for_int |
| 1256 |
} |
| 1257 |
} |
| 1258 |
} |
| 1259 |
% \end{macrocode} |
| 1260 |
% |
| 1261 |
% Now that the pattern has been changed we can set the color. |
| 1262 |
% |
| 1263 |
% \begin{macrocode} |
| 1264 |
\columnseprulecolor |
| 1265 |
% \end{macrocode} |
| 1266 |
% |
| 1267 |
% We only call \cs{mcrule_divider:} if \cs{columnseprule} $>0$, so that all |
| 1268 |
% line styles can be turned off by setting it to 0, just as is the case with |
| 1269 |
% the vanilla rules. |
| 1270 |
% |
| 1271 |
% \begin{macrocode} |
| 1272 |
\bool_lazy_and:nnT |
| 1273 |
{\dim_compare_p:nNn {\columnseprule} > {\c_zero_dim}} |
| 1274 |
{\int_compare_p:nNn {\l_@@_repeat_int} > {\c_zero_int}} |
| 1275 |
{ |
| 1276 |
\mcrule_divider: |
| 1277 |
\prg_replicate:nn {\l_@@_repeat_int - \c_one_int} |
| 1278 |
{ |
| 1279 |
\hspace{\l_@@_repeat_distance_dim} |
| 1280 |
\mcrule_divider: |
| 1281 |
} |
| 1282 |
} |
| 1283 |
} |
| 1284 |
% \end{macrocode} |
| 1285 |
%\end{function} |
| 1286 |
% |
| 1287 |
%\begin{macro}{\@@_column_total_height:,\@@_column_total_depth:} |
| 1288 |
% Get column height and depth with any explicit alterations. |
| 1289 |
% \changes{v1.2a}{2019/2/12}{Account for overflow text} |
| 1290 |
% |
| 1291 |
% \begin{macrocode} |
| 1292 |
\cs_new:Npn \@@_column_total_height: |
| 1293 |
{ |
| 1294 |
\dim_eval:n {\@@_column_height: + \@@_column_depth: + |
| 1295 |
\@@_extend_column_top: + \@@_column_overflow: + \@@_extend_column_bottom:} |
| 1296 |
} |
| 1297 |
\cs_new:Npn \@@_column_total_depth: |
| 1298 |
{ |
| 1299 |
\dim_eval:n {\@@_column_depth: + \@@_column_overflow: + |
| 1300 |
\@@_extend_column_bottom:} |
| 1301 |
} |
| 1302 |
% \end{macrocode} |
| 1303 |
%\end{macro} |
| 1304 |
% |
| 1305 |
%\begin{macro}{\@@_extend_column_top:} |
| 1306 |
% Currently, the extend amount for the top is just the |
| 1307 |
% |\l_@@_extend_top_dim| distance. In the future we may allow more complex |
| 1308 |
% criteria, such as by odd or even page, or on a particular page. Although |
| 1309 |
% these might theoretically be useful, I'm not going to implement them until |
| 1310 |
% someone comes along with a use-case for it. |
| 1311 |
% \begin{macrocode} |
| 1312 |
\cs_new:Npn \@@_extend_column_top: |
| 1313 |
{ |
| 1314 |
\l_@@_extend_top_dim |
| 1315 |
} |
| 1316 |
% \end{macrocode} |
| 1317 |
%\end{macro} |
| 1318 |
% |
| 1319 |
%\begin{macro}{\@@_extend_column_bottom:} |
| 1320 |
% The |extend-fill| option, which is only applicable with \pkg{multicol}, |
| 1321 |
% extends the rule from the bottom of the column to the end of the text area, |
| 1322 |
% minus whatever reserved space the user specifies. If there's less space |
| 1323 |
% available than requested, we give everything we can. |
| 1324 |
% \begin{macrocode} |
| 1325 |
\cs_new:Npn \@@_extend_column_bottom: |
| 1326 |
{ |
| 1327 |
\bool_lazy_and:nnTF |
| 1328 |
{\bool_if_p:n {\l_@@_extend_fill_bool}} |
| 1329 |
{\bool_not_p:n {\g_@@_twocolumn_bool}} |
| 1330 |
{ |
| 1331 |
\dim_compare:nNnTF |
| 1332 |
{\@colroom - \@@_column_height: - \@@_extend_reserve:} > {\c_zero_dim} |
| 1333 |
{\@colroom - \@@_column_height: - \@@_extend_reserve:} |
| 1334 |
{\c_zero_dim} |
| 1335 |
} |
| 1336 |
{\l_@@_extend_bot_dim} |
| 1337 |
} |
| 1338 |
% \end{macrocode} |
| 1339 |
%\end{macro} |
| 1340 |
% |
| 1341 |
%\begin{macro}{\@@_extend_reserve:} |
| 1342 |
% The reserved space is the amount of user-provided space we want, but we also |
| 1343 |
% have to account for the space added with \cs{multicolsep}. |
| 1344 |
% \begin{macrocode} |
| 1345 |
\cs_new:Npn \@@_extend_reserve: |
| 1346 |
{ |
| 1347 |
\dim_compare:nNnTF {\l_@@_extend_reserve_dim} > {\c_zero_dim} |
| 1348 |
{\dim_eval:n {\l_@@_extend_reserve_dim + \multicolsep}} |
| 1349 |
{\c_zero_dim} |
| 1350 |
} |
| 1351 |
% \end{macrocode} |
| 1352 |
%\end{macro} |
| 1353 |
% |
| 1354 |
%\begin{function}{\mcrule_divider:} |
| 1355 |
% This is the routine that contains the instructions to draw one copy |
| 1356 |
% of rule between columns. The default is identical to the original definition |
| 1357 |
% used by \pkg{multicol}. It will be reset each time the user calls |
| 1358 |
% \cs{MCSetRule} to specify a new line style. |
| 1359 |
% \begin{macrocode} |
| 1360 |
\cs_new:Npn \mcrule_divider: {\vrule\@width\columnseprule} |
| 1361 |
% \end{macrocode} |
| 1362 |
%\end{function} |
| 1363 |
% |
| 1364 |
%\begin{macro}{\@@_pattern:nnn} |
| 1365 |
% \begin{syntax} |
| 1366 |
% \cs{@@_mcrule_pattern:nnn} \Arg{pattern} \Arg{space above} \Arg{space below} |
| 1367 |
% \end{syntax} |
| 1368 |
% Typesets a single copy of a pattern, vertically centered, in a vertical |
| 1369 |
% box that is the height of the current column. The pattern must be |
| 1370 |
% something that can go in a horizontal box. The \meta{space above} and |
| 1371 |
% \meta{space below} arguments must be dimension expressions. |
| 1372 |
% \changes{v1.2a}{2018/1/2}{Allow evaluated dimensions for kerns} |
| 1373 |
% \begin{macrocode} |
| 1374 |
\cs_new_nopar:Npn \@@_pattern:nnn #1#2#3 |
| 1375 |
{ |
| 1376 |
\box_move_down:nn {\@@_column_total_depth:} |
| 1377 |
{ |
| 1378 |
\vbox_to_ht:nn {\@@_column_total_height:} |
| 1379 |
{ |
| 1380 |
\tex_vfill:D |
| 1381 |
\tex_kern:D \dim_eval:n {#2} \exp_stop_f: |
| 1382 |
\hbox:n{#1} |
| 1383 |
\tex_kern:D \dim_eval:n {#3} \exp_stop_f: |
| 1384 |
\tex_vfill:D |
| 1385 |
} |
| 1386 |
} |
| 1387 |
} |
| 1388 |
% \end{macrocode} |
| 1389 |
%\end{macro} |
| 1390 |
% |
| 1391 |
%\begin{macro}{\@@_tile_pattern:nnn} |
| 1392 |
% \begin{syntax} |
| 1393 |
% \cs{mcrule_tile_pattern:nnn} \Arg{pattern} \Arg{space above} \Arg{space below} |
| 1394 |
% \end{syntax} |
| 1395 |
% Typesets multiple copies of pattern, tiled so as to occupy a vertical box |
| 1396 |
% that is the height of the current column. The pattern must be something |
| 1397 |
% that can go in a horizontal box. The \meta{space above} and |
| 1398 |
% \meta{space below} arguments must be dimension expressions. |
| 1399 |
% \changes{v1.2a}{2018/1/2}{Allow evaluated dimensions for kerns} |
| 1400 |
% \begin{macrocode} |
| 1401 |
\cs_new_nopar:Npn \@@_tile_pattern:nnn #1#2#3 |
| 1402 |
{ |
| 1403 |
\box_move_down:nn {\@@_column_total_depth:} |
| 1404 |
{ |
| 1405 |
\vbox_to_ht:nn {\@@_column_total_height:} |
| 1406 |
{ |
| 1407 |
\tex_cleaders:D \vbox:n |
| 1408 |
{ |
| 1409 |
\tex_kern:D \dim_eval:n {#2} \exp_stop_f: |
| 1410 |
\hbox:n{#1} |
| 1411 |
\tex_kern:D \dim_eval:n {#3} \exp_stop_f: |
| 1412 |
} |
| 1413 |
\tex_vfill:D |
| 1414 |
} |
| 1415 |
} |
| 1416 |
} |
| 1417 |
% \end{macrocode} |
| 1418 |
%\end{macro} |
| 1419 |
% |
| 1420 |
%\begin{macro}{\@@_line_pattern:nnnn} |
| 1421 |
% \begin{syntax} |
| 1422 |
% \cs{@@_mcrule_line_pattern:nnnn} \Arg{tikz-name} \Arg{height} \Arg{space above} |
| 1423 |
% \Arg{space below} |
| 1424 |
% \end{syntax} |
| 1425 |
% This function can draw a line pattern using either a \pkg{tikz} name or |
| 1426 |
% directly (as a tiled pattern). The latter case is currently limited to line |
| 1427 |
% patterns that can be described in terms of a solid line of length |
| 1428 |
% \meta{height} separated by spaces above and/or below the line. |
| 1429 |
% |
| 1430 |
% \begin{macrocode} |
| 1431 |
\cs_new:Npn \@@_line_pattern:nnnn #1#2#3#4 |
| 1432 |
{ |
| 1433 |
\bool_if:NTF \g_@@_use_tikz_bool |
| 1434 |
{ |
| 1435 |
\@@_pattern_line:n {#1} |
| 1436 |
} |
| 1437 |
{ |
| 1438 |
\@@_tile_pattern:nnn {\rule{\columnseprule}{#2}}{#3}{#4} |
| 1439 |
} |
| 1440 |
} |
| 1441 |
% \end{macrocode} |
| 1442 |
%\end{macro} |
| 1443 |
% |
| 1444 |
%\begin{macro}{\@@_solid_line:} |
| 1445 |
% Unlike the default solid line, which is created with a simple \tn{vrule}, |
| 1446 |
% this version allows us to extend the line beyond the natural space of the |
| 1447 |
% column. |
| 1448 |
% \begin{macrocode} |
| 1449 |
\cs_new:Npn \@@_solid_line: |
| 1450 |
{ |
| 1451 |
\rule[-\@@_column_total_depth:]{\columnseprule}{\@@_column_total_height:} |
| 1452 |
} |
| 1453 |
% \end{macrocode} |
| 1454 |
%\end{macro} |
| 1455 |
% |
| 1456 |
%\begin{macro}{\@@_strut:} |
| 1457 |
% Uses a zero-width rule, regardless of the actual value of \cs{columnseprule}. |
| 1458 |
% \changes{v1.3}{2019/10/1}{New function} |
| 1459 |
% \begin{macrocode} |
| 1460 |
\cs_new:Npn \@@_strut: |
| 1461 |
{ |
| 1462 |
\rule[-\@@_column_total_depth:]{0pt}{\@@_column_total_height:} |
| 1463 |
} |
| 1464 |
% \end{macrocode} |
| 1465 |
%\end{macro} |
| 1466 |
% |
| 1467 |
% \subsubsection{Tikz-only Routines} |
| 1468 |
% |
| 1469 |
% If we're supporting \pkg{tikz}, make sure it's loaded and redefine the |
| 1470 |
% relevant functions. We turn off |expl3| syntax to load the package because |
| 1471 |
% \pkg{tikz} relies on 2e catcodes, especially for spaces. |
| 1472 |
% |
| 1473 |
% \begin{macrocode} |
| 1474 |
\bool_if:NTF \g_@@_use_tikz_bool |
| 1475 |
{ |
| 1476 |
\ExplSyntaxOff |
| 1477 |
\RequirePackage{tikz} |
| 1478 |
\ExplSyntaxOn |
| 1479 |
% \end{macrocode} |
| 1480 |
% |
| 1481 |
%\begin{macro}{\@@_tikz_picture:n} |
| 1482 |
% \begin{syntax} |
| 1483 |
% |\__mcrule_tikz_picture:n| \Arg{draw function} |
| 1484 |
% \end{syntax} |
| 1485 |
% Set up the \env{tikzpicture} environment and declare two nodes, named |(TOP)| |
| 1486 |
% and |(BOT)|. This way we can pass a \cs{draw} routine directly, |
| 1487 |
% without worrying about the line's coordinates. |
| 1488 |
% |
| 1489 |
% \begin{macrocode} |
| 1490 |
\cs_set:Npn \@@_tikz_picture:n #1 |
| 1491 |
{ |
| 1492 |
\begin{tikzpicture}[x=1pt,y=1pt,inner~sep=0pt,outer~sep=0pt, |
| 1493 |
baseline={([yshift=\@@_column_total_depth:]current~bounding~box.south)}] |
| 1494 |
\node (TOP) at (0,\@@_column_total_height:) {}; |
| 1495 |
\node (BOT) at (0,0) {}; |
| 1496 |
#1 |
| 1497 |
\end{tikzpicture} |
| 1498 |
} |
| 1499 |
% \end{macrocode} |
| 1500 |
%\end{macro} |
| 1501 |
% |
| 1502 |
%\begin{macro}{\@@_pattern_line:n} |
| 1503 |
% \begin{syntax} |
| 1504 |
% \cs{@@_mcrule_pattern_line:n} \Arg{tikz pattern} |
| 1505 |
% \end{syntax} |
| 1506 |
% For the \pkg{tikz} versions of the predefined lines, we just draw |
| 1507 |
% a line the length of the column box. \meta{tikz pattern} should |
| 1508 |
% contain the name of a line style that \pkg{tikz} recognizes. |
| 1509 |
% \begin{macrocode} |
| 1510 |
\cs_set:Npn \@@_pattern_line:n #1 |
| 1511 |
{ |
| 1512 |
\begin{tikzpicture}[x=1pt,y=1pt,inner~sep=0pt,outer~sep=0pt, |
| 1513 |
baseline={([yshift=\@@_column_total_depth:]current~bounding~box.south)}] |
| 1514 |
\draw[line~width=\columnseprule,#1] (0,\@@_column_total_height:) -- (0,0); |
| 1515 |
\end{tikzpicture} |
| 1516 |
} |
| 1517 |
% \end{macrocode} |
| 1518 |
%\end{macro} |
| 1519 |
% |
| 1520 |
%\begin{macro}{\@@_circle:} |
| 1521 |
% Draw a hollow circle with a diameter equal to |\columnseprule|. This will be |
| 1522 |
% used as a tile pattern. |
| 1523 |
% |
| 1524 |
% \begin{macrocode} |
| 1525 |
\cs_set:Npn \@@_circle: |
| 1526 |
{ |
| 1527 |
\begin{tikzpicture}[x=1pt,y=1pt,inner~sep=0pt,outer~sep=0pt] |
| 1528 |
\draw (0,0) circle[radius=.5\columnseprule]; |
| 1529 |
\end{tikzpicture} |
| 1530 |
} |
| 1531 |
% \end{macrocode} |
| 1532 |
%\end{macro} |
| 1533 |
% |
| 1534 |
%\begin{macro}{\@@_solid_circle:} |
| 1535 |
% Draw a filled circle with a diameter equal to |\columnseprule|. This will be |
| 1536 |
% used as a tile pattern. |
| 1537 |
% |
| 1538 |
% \begin{macrocode} |
| 1539 |
\cs_set:Npn \@@_solid_circle: |
| 1540 |
{ |
| 1541 |
\begin{tikzpicture}[x=1pt,y=1pt,inner~sep=0pt,outer~sep=0pt] |
| 1542 |
\fill (0,0) circle[radius=.5\columnseprule]; |
| 1543 |
\end{tikzpicture} |
| 1544 |
} |
| 1545 |
} |
| 1546 |
% \end{macrocode} |
| 1547 |
%\end{macro} |
| 1548 |
% |
| 1549 |
% In case \pkg{tikz} functions are not active, we provide stubs |
| 1550 |
% that issue error messages. |
| 1551 |
% |
| 1552 |
% \begin{macrocode} |
| 1553 |
{ |
| 1554 |
\cs_set:Npn \@@_tikz_picture:n #1 |
| 1555 |
{\msg_error:nnn {multicolrule} {tikz-required} {#1}} |
| 1556 |
\cs_new:Npn \@@_pattern_line:n #1 |
| 1557 |
{\msg_error:nnn {multicolrule} {tikz-required} {#1}} |
| 1558 |
\cs_new:Npn \@@_circle: |
| 1559 |
{\msg_error:nnn {multicolrule} {tikz-required} {circles}} |
| 1560 |
\cs_new:Npn \@@_solid_circle: |
| 1561 |
{\msg_error:nnn {multicolrule} {tikz-required} {solid-circles}} |
| 1562 |
} |
| 1563 |
% \end{macrocode} |
| 1564 |
% |
| 1565 |
% \subsection{Color} |
| 1566 |
%\begin{macro}{\@@_set_rule_color:} |
| 1567 |
% Reset color definition in \cs{columnseprulecolor} by name or |
| 1568 |
% by model and color specification. |
| 1569 |
% |
| 1570 |
% \begin{macrocode} |
| 1571 |
\cs_new_protected:Npn \@@_set_rule_color: |
| 1572 |
{ |
| 1573 |
\tl_if_empty:NT \l_@@_color_name_tl |
| 1574 |
{ |
| 1575 |
\tl_set:Nn \l_@@_color_name_tl {black} |
| 1576 |
} |
| 1577 |
\tl_if_empty:NTF \l_@@_color_model_tl |
| 1578 |
{ |
| 1579 |
\cs_set:Npn \columnseprulecolor {\color{\l_@@_color_name_tl}} |
| 1580 |
} |
| 1581 |
{ |
| 1582 |
\cs_set:Npn \columnseprulecolor |
| 1583 |
{\color[\l_@@_color_model_tl]{\l_@@_color_name_tl}} |
| 1584 |
} |
| 1585 |
} |
| 1586 |
% \end{macrocode} |
| 1587 |
%\end{macro} |
| 1588 |
% |
| 1589 |
% \subsection{Patterns} |
| 1590 |
% |
| 1591 |
%\begin{macro}{\@@_set_pattern_list:n} |
| 1592 |
% Sets a comma-separated list of patterns as a sequence for later use. The |
| 1593 |
% global counter that indicates where we are in the list is also reset here, so |
| 1594 |
% setting a list of patterns always means that the next rule will use the first |
| 1595 |
% pattern in the list. |
| 1596 |
% \begin{macrocode} |
| 1597 |
\cs_new_protected:Npn \@@_set_pattern_list:n #1 |
| 1598 |
{ |
| 1599 |
\seq_set_split:Nnn \l_@@_pattern_list_seq {,} {#1} |
| 1600 |
\int_gzero:N \g_@@_pattern_count_int |
| 1601 |
\int_gzero:N \g_@@_pattern_after_int |
| 1602 |
\int_gset:Nn \g_@@_pattern_for_int {-1} |
| 1603 |
} |
| 1604 |
% \end{macrocode} |
| 1605 |
%\end{macro} |
| 1606 |
% |
| 1607 |
%\begin{macro}{\@@_set_pattern:n} |
| 1608 |
% |
| 1609 |
% Set the keys an individual pattern. To avoid potential recursion and loops, |
| 1610 |
% we filter out the key `pattern' when it appears in a pattern definition. |
| 1611 |
% \begin{macrocode} |
| 1612 |
\cs_new_protected:Npn \@@_set_pattern:n #1 |
| 1613 |
{ |
| 1614 |
\prop_get:NnNTF \g_@@_patterns_prop {#1} \l_tmpa_tl |
| 1615 |
{ |
| 1616 |
\keys_set_filter:nnV {mcrule} {patterns} \l_tmpa_tl |
| 1617 |
} |
| 1618 |
{ |
| 1619 |
\msg_error:nnn {multicolrule} {pattern-undefined} {#1} |
| 1620 |
} |
| 1621 |
\tl_set:Nn \l_tmpa_tl {\prop_item:Nn \g_@@_patterns_prop {#1}} |
| 1622 |
} |
| 1623 |
\cs_generate_variant:Nn \@@_set_pattern:n {V} |
| 1624 |
% \end{macrocode} |
| 1625 |
%\end{macro} |
| 1626 |
% |
| 1627 |
% \subsection{Key-Values} |
| 1628 |
% Set up all the key definitions. For the line styles, this involves |
| 1629 |
% resetting \cs{mcrule_divider:} to an appropriate value. |
| 1630 |
% \changes{v1.1}{2018/12/21}{Added extend-top, extend-bot, extend-fill, and |
| 1631 |
% extend-reserve keys} |
| 1632 |
% \changes{v1.2}{2019/1/1}{Added patterns, pattern-after, and pattern-for |
| 1633 |
% keys} |
| 1634 |
% \changes{v1.2a}{2019/2/12}{Added expand and shift shortcuts} |
| 1635 |
% |
| 1636 |
% \begin{macrocode} |
| 1637 |
\keys_define:nn {mcrule} |
| 1638 |
{ |
| 1639 |
extend-top .dim_set:N = \l_@@_extend_top_dim, |
| 1640 |
extend-bot .dim_set:N = \l_@@_extend_bot_dim, |
| 1641 |
extend-fill .bool_set:N = \l_@@_extend_fill_bool, |
| 1642 |
extend-fill .default:n = true, |
| 1643 |
extend-reserve .dim_set:N = \l_@@_extend_reserve_dim, |
| 1644 |
expand .code:n = { |
| 1645 |
\dim_set:Nn \l_@@_extend_bot_dim {#1} |
| 1646 |
\dim_set:Nn \l_@@_extend_top_dim {#1} |
| 1647 |
}, |
| 1648 |
shift .code:n = { |
| 1649 |
\dim_set:Nn \l_@@_extend_bot_dim {#1} |
| 1650 |
\dim_set:Nn \l_@@_extend_top_dim {\fp_to_dim:n {-1 * \l_@@_extend_bot_dim}} |
| 1651 |
}, |
| 1652 |
line-style .choice:, |
| 1653 |
line-style / default .code:n = \cs_set:Npn \mcrule_divider: |
| 1654 |
{\vrule\@width\columnseprule}, |
| 1655 |
line-style / solid .code:n = \cs_set:Npn \mcrule_divider: |
| 1656 |
{\@@_solid_line:}, |
| 1657 |
line-style / strut .code:n = \cs_set:Npn \mcrule_divider: |
| 1658 |
{\@@_strut:}, |
| 1659 |
line-style / dots .code:n = \cs_set:Npn \mcrule_divider: |
| 1660 |
{\@@_tile_pattern:nnn {.}{1pt}{1pt}}, |
| 1661 |
line-style / dense-dots .code:n = \cs_set:Npn \mcrule_divider: |
| 1662 |
{\@@_tile_pattern:nnn {.}{1pt}{0pt}}, |
| 1663 |
line-style / loose-dots .code:n = \cs_set:Npn \mcrule_divider: |
| 1664 |
{\@@_tile_pattern:nnn {.}{2pt}{2pt}}, |
| 1665 |
line-style / circles .code:n = \cs_set:Npn \mcrule_divider: |
| 1666 |
{\@@_tile_pattern:nnn {\@@_circle:}{1pt}{1pt}}, |
| 1667 |
line-style / dense-circles .code:n = \cs_set:Npn \mcrule_divider: |
| 1668 |
{\@@_tile_pattern:nnn {\@@_circle:}{1pt}{0pt}}, |
| 1669 |
line-style / loose-circles .code:n = \cs_set:Npn \mcrule_divider: |
| 1670 |
{\@@_tile_pattern:nnn {\@@_circle:}{2pt}{2pt}}, |
| 1671 |
line-style / solid-circles .code:n = \cs_set:Npn \mcrule_divider: |
| 1672 |
{\@@_tile_pattern:nnn {\@@_solid_circle:}{1pt}{1pt}}, |
| 1673 |
line-style / dense-solid-circles .code:n = \cs_set:Npn \mcrule_divider: |
| 1674 |
{\@@_tile_pattern:nnn {\@@_solid_circle:}{1pt}{0pt}}, |
| 1675 |
line-style / loose-solid-circles .code:n = \cs_set:Npn \mcrule_divider: |
| 1676 |
{\@@_tile_pattern:nnn {\@@_solid_circle:}{2pt}{2pt}}, |
| 1677 |
line-style / dotted .code:n = \cs_set:Npn \mcrule_divider: |
| 1678 |
{\@@_line_pattern:nnnn {dotted}{\columnseprule}{1pt}{1pt}}, |
| 1679 |
line-style / densely-dotted .code:n = \cs_set:Npn \mcrule_divider: |
| 1680 |
{\@@_line_pattern:nnnn {densely~dotted}{\columnseprule}{1pt}{0pt}}, |
| 1681 |
line-style / loosely-dotted .code:n = \cs_set:Npn \mcrule_divider: |
| 1682 |
{\@@_line_pattern:nnnn {loosely~dotted}{\columnseprule}{2pt}{2pt}}, |
| 1683 |
line-style / dashed .code:n = \cs_set:Npn \mcrule_divider: |
| 1684 |
{\@@_line_pattern:nnnn {dashed}{3pt}{1.5pt}{1.5pt}}, |
| 1685 |
line-style / densely-dashed .code:n = \cs_set:Npn \mcrule_divider: |
| 1686 |
{\@@_line_pattern:nnnn {densely~dashed}{3pt}{1pt}{1pt}}, |
| 1687 |
line-style / loosely-dashed .code:n = \cs_set:Npn \mcrule_divider: |
| 1688 |
{\@@_line_pattern:nnnn {loosely~dashed}{3pt}{3pt}{3pt}}, |
| 1689 |
line-style / dash-dot .code:n = \cs_set:Npn \mcrule_divider: |
| 1690 |
{\@@_pattern_line:n{dash~dot}}, |
| 1691 |
line-style / densely-dash-dot .code:n = \cs_set:Npn \mcrule_divider: |
| 1692 |
{\@@_pattern_line:n{densely~dash~dot}}, |
| 1693 |
line-style / loosely-dash-dot .code:n = \cs_set:Npn \mcrule_divider: |
| 1694 |
{\@@_pattern_line:n{loosely~dash~dot}}, |
| 1695 |
line-style / dash-dot-dot .code:n = \cs_set:Npn \mcrule_divider: |
| 1696 |
{\@@_pattern_line:n{dash~dot~dot}}, |
| 1697 |
line-style / densely-dash-dot-dot .code:n = \cs_set:Npn \mcrule_divider: |
| 1698 |
{\@@_pattern_line:n{densely~dash~dot~dot}}, |
| 1699 |
line-style / loosely-dash-dot-dot .code:n = \cs_set:Npn \mcrule_divider: |
| 1700 |
{\@@_pattern_line:n{loosely~dash~dot~dot}}, |
| 1701 |
color .code:n = { |
| 1702 |
\tl_set:Nn \l_@@_color_name_tl {#1} |
| 1703 |
\@@_set_rule_color: |
| 1704 |
}, |
| 1705 |
color-model .code:n = { |
| 1706 |
\tl_set:Nn \l_@@_color_model_tl {#1} |
| 1707 |
\@@_set_rule_color: |
| 1708 |
}, |
| 1709 |
custom-line .code:n = \cs_set:Npn \mcrule_divider: |
| 1710 |
{\@@_tikz_picture:n {#1}}, |
| 1711 |
custom-pattern .code:n = \cs_set:Npn \mcrule_divider: |
| 1712 |
{\@@_pattern:nnn #1}, |
| 1713 |
custom-tile .code:n = \cs_set:Npn \mcrule_divider: |
| 1714 |
{\@@_tile_pattern:nnn #1}, |
| 1715 |
width .choice:, |
| 1716 |
width / ultra-thin .code:n = \dim_set:Nn \columnseprule {0.1pt}, |
| 1717 |
width / very-thin .code:n = \dim_set:Nn \columnseprule {0.2pt}, |
| 1718 |
width / thin .code:n = \dim_set:Nn \columnseprule {0.4pt}, |
| 1719 |
width / semithick .code:n = \dim_set:Nn \columnseprule {0.6pt}, |
| 1720 |
width / thick .code:n = \dim_set:Nn \columnseprule {0.8pt}, |
| 1721 |
width / very-thick .code:n = \dim_set:Nn \columnseprule {1.2pt}, |
| 1722 |
width / ultra-thick .code:n = \dim_set:Nn \columnseprule {1.6pt}, |
| 1723 |
width / unknown .code:n = \dim_set:Nn \columnseprule {#1}, |
| 1724 |
repeat .int_set:N = \l_@@_repeat_int, |
| 1725 |
repeat-distance .dim_set:N = \l_@@_repeat_distance_dim, |
| 1726 |
single .meta:n = { |
| 1727 |
repeat = 1, |
| 1728 |
repeat-distance = #1 |
| 1729 |
}, |
| 1730 |
single .default:n = \columnseprule, |
| 1731 |
double .meta:n = { |
| 1732 |
repeat = 2, |
| 1733 |
repeat-distance = #1 |
| 1734 |
}, |
| 1735 |
double .default:n = \columnseprule, |
| 1736 |
triple .meta:n = { |
| 1737 |
repeat = 3, |
| 1738 |
repeat-distance = #1 |
| 1739 |
}, |
| 1740 |
triple .default:n = \columnseprule, |
| 1741 |
patterns .code:n = \@@_set_pattern_list:n {#1}, |
| 1742 |
patterns .groups:n = {patterns}, |
| 1743 |
pattern-after .int_gset:N = \g_@@_pattern_after_int, |
| 1744 |
pattern-for .int_gset:N = \g_@@_pattern_for_int, |
| 1745 |
} |
| 1746 |
% \end{macrocode} |
| 1747 |
% |
| 1748 |
% \subsection{User Interface} |
| 1749 |
% |
| 1750 |
%\begin{macro}{\SetMCRule} |
| 1751 |
% Set all keys for \mcrule{} |
| 1752 |
% \begin{syntax} |
| 1753 |
% |\SetMCRule| \marg{key-value list} |
| 1754 |
% \end{syntax} |
| 1755 |
% All we do here is pass the argument to expl3's key-setting routine. |
| 1756 |
% \begin{macrocode} |
| 1757 |
\NewDocumentCommand{\SetMCRule}{m} |
| 1758 |
{ |
| 1759 |
\keys_set:nn {mcrule} {#1} |
| 1760 |
} |
| 1761 |
% \end{macrocode} |
| 1762 |
%\end{macro} |
| 1763 |
% |
| 1764 |
%\begin{macro}{\DeclareMCRulePattern} |
| 1765 |
% \begin{syntax} |
| 1766 |
% \cs{DeclareMCRule} \Arg{name} \meta{key-value list} |
| 1767 |
% \end{syntax} |
| 1768 |
% Declare a new style pattern. |
| 1769 |
% If a pattern of that name exists, it will be overwritten silently. |
| 1770 |
% \begin{macrocode} |
| 1771 |
\NewDocumentCommand{\DeclareMCRulePattern}{m m} |
| 1772 |
{ |
| 1773 |
\prop_gput:Nnn \g_@@_patterns_prop {#1} {#2} |
| 1774 |
} |
| 1775 |
% \end{macrocode} |
| 1776 |
%\end{macro} |
| 1777 |
% |
| 1778 |
% \begin{macrocode} |
| 1779 |
%</package> |
| 1780 |
% \end{macrocode} |
| 1781 |
% |
| 1782 |
%\end{implementation} |
| 1783 |
% |
| 1784 |
% \PrintChanges |
| 1785 |
% |
| 1786 |
% \PrintIndex |