# paracolrule

`paracolrule` adds decorative separator rules to the LaTeX
[`paracol`](https://ctan.org/pkg/paracol) package.

- **Version**: 0.1.0
- **Date**: 2026-08-22
- **Author**: Kosei Kawaguchi (a.k.a. KKTeX)
- **License**: LaTeX Project Public License 1.3c or later
- **Repository**: [https://github.com/KKTeX/paracolrule](https://github.com/KKTeX/paracolrule)
- **Support**: p.c.aces1056@gmail.com

It changes only the rule segments generated by `paracol`. Page breaking,
spanning text, arbitrary column counts and widths, background painting, and
per-gap colors remain under `paracol`'s control.

## Usage

```latex
\usepackage{xcolor}
\usepackage{paracolrule}

\setlength{\columnseprule}{1pt}
\colseprulecolor{blue!70!black}
\ParacolRuleSetup{
  style=dashed,
  dash-length=5pt,
  gap-length=3pt
}

\begin{paracol}{2}
  Main text
  \switchcolumn
  Commentary
\end{paracol}
```

Built-in styles are `solid`, `dashed`, `dotted`, and `double`. A custom
renderer can be installed with `\ParacolRuleSetRenderer{\YourMacro}`; the
renderer receives the adjusted rule-segment height as its only argument.
Dashed and dotted styles place a mark at both ends of every segment and
calculate one common interval for all intervening marks. They therefore reach
the exact bottom without a visibly shortened or uneven final gap.

Rule extents follow `multicolrule`: `extend-top` and `extend-bot` use positive
values to extend and negative values to shorten. `expand` sets both values;
`shift` moves the rule without changing its length. With zero extensions, the
decorated rule keeps the exact segment boundaries generated by `paracol`.
Those boundaries belong to the column box, not to the visible ink of its first
and last glyphs; no font-dependent correction is guessed.

TikZ custom rules follow the `multicolrule` convention:

```latex
\usepackage[tikz]{paracolrule}
\ParacolRuleSetup{
  custom-line={
    \draw[line width=1pt] (TOP) to[bend left=8] (BOT);
  }
}
```

The code runs inside a `tikzpicture`; `(TOP)` and `(BOT)` are the exact
endpoints of each separator segment. TikZ support is also detected when
`tikz` was loaded before `paracolrule`. A custom TikZ rule uses the normal
`\colseprulecolor`; per-gap color overrides apply only to the built-in
renderers because `paracol` reuses one separator box for every gap.

## Compatibility

Version 0.1.0 is tested with `paracol` 1.37. Because `paracol` does not expose a
public separator-rendering hook, this package verifies its two internal patch
points at load time and fails loudly if they have changed.

## Building

```sh
make test
make doc
make sample
make zip
```

The package source is maintained directly in `paracolrule.sty`. The manual is
`paracolrule-doc.tex`, and the multi-page visual example is
`paracolrule-sample.tex`.

## License

LaTeX Project Public License 1.3c or later.