% fxpicture-doc.tex - the documentation of the fxpicture package.
%
% Written by Claude AI (Anthropic), with direction from CodeCogs Ltd.
% Copyright (C) 2026 CodeCogs Ltd. Distributed under the LaTeX Project Public License 1.3c.
%
% Compile with pdflatex (twice).
\documentclass[a4paper,11pt]{article}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage[margin=25mm]{geometry}
\usepackage{microtype}
\usepackage{booktabs}
\usepackage{array}
\usepackage{xcolor}
\usepackage{fxpicture}
\usepackage[most]{tcolorbox}
\usepackage{hyperref}
\hypersetup{
  colorlinks, linkcolor=fxlink, urlcolor=fxlink, citecolor=fxlink,
  pdftitle={The fxpicture package},
  pdfauthor={Claude AI, with direction from CodeCogs Ltd.},
  pdfsubject={Line styles for LaTeX's picture environment},
  pdfkeywords={LaTeX, picture, pict2e, dashed, dotted, line style}}
\definecolor{fxlink}{rgb}{0.05,0.25,0.55}
\definecolor{fxcode}{rgb}{0.96,0.96,0.94}
\definecolor{fxframe}{rgb}{0.75,0.75,0.72}

\newcommand*\cs[1]{\texttt{\char`\\#1}}
\newcommand*\meta[1]{\textlangle\textit{#1}\textrangle}
\newcommand*\pkg[1]{\textsf{#1}}
\newcommand*\marg[1]{\texttt{\{}\meta{#1}\texttt{\}}}

\lstdefinestyle{fx}{
  language=[LaTeX]TeX, basicstyle=\ttfamily\small, columns=fullflexible,
  keepspaces, upquote, commentstyle=\color{black!55}\itshape,
  texcsstyle=*\color{fxlink}, moretexcs={linestyle,dashpattern,put,line,vector,Vector,
    oval,qbezier,cbezier,circle,polygon,polyline,arc,thicklines,thinlines,linethickness,
    roundcap,buttcap,setlength,unitlength,multiput,Line}}
\lstset{style=fx}

% An example: its code on the left, what it draws on the right.
\newtcblisting{example}{
  listing side text, sidebyside align=center, lefthand width=0.55\linewidth,
  colback=fxcode, colframe=fxframe, boxrule=0.4pt, arc=1mm,
  listing options={style=fx}}
% Code only.
\newtcblisting{code}{
  listing only, colback=fxcode, colframe=fxframe, boxrule=0.4pt, arc=1mm,
  listing options={style=fx}}

\title{The \pkg{fxpicture} package\\[4pt]
  \large Line styles for \LaTeX's \texttt{picture} environment}
\author{Written by Claude AI, with direction from CodeCogs Ltd.\\[2pt]
  \small\url{https://fxeditor.codecogs.com}}
\date{Version 1.0, 15 October 2026}

\begin{document}
\maketitle

\begin{abstract}
\noindent
\pkg{fxpicture} adds dashed, dotted and dash-dotted lines to \LaTeX's \texttt{picture}
environment. It builds on \pkg{pict2e}, and gives it two declarations,
\cs{linestyle} and \cs{dashpattern}. Like \cs{linethickness}, they last until the end of the
group, and they apply to every line that \pkg{pict2e} strokes, from \cs{line} and \cs{vector}
to \cs{oval}, \cs{circle} and Bézier curves.
\end{abstract}

\tableofcontents

\section{Introduction}

The \texttt{picture} environment is the drawing language built into \LaTeX. The \pkg{pict2e}
package removes its old limits: lines and arrows at any slope, circles of any size, ovals,
arcs, polygons and Bézier curves, all drawn by the output driver. Neither package draws a
dashed or dotted line, though. The nearest are \cs{dashbox}, which dashes only the frame of a
box, and \cs{qbezier}\texttt{[}\meta{n}\texttt{]}, which draws a curve as $n$ separate dots.

\pkg{fxpicture} fills that gap. It asks the driver to dash the path, which is what
PostScript and PDF were designed for, so dashes run on round corners and curves, and a dashed
picture is no larger or slower to typeset than a solid one.
\begin{example}
\setlength{\unitlength}{1mm}
\begin{picture}(50,32)
 {\linestyle{dashed}
  \put(5,2){\line(1,0){40}}
  \put(25,13){\oval(40,10)}
  \put(5,22){\qbezier(0,0)(20,15)(40,0)}
 }
\end{picture}
\end{example}

\paragraph{A working implementation.} \pkg{fxpicture} was made alongside the
\texttt{picture} support of CodeCogs' online equation editor, which draws the same line styles
as SVG in the browser. To try it, see \url{https://fxeditor.codecogs.com}.

\section{Loading the package}

\begin{code}
\usepackage{fxpicture}
\end{code}
\pkg{fxpicture} loads \pkg{pict2e}, and passes any options it is given on to it, so a driver
or an arrow style can be chosen in the usual way:
\begin{code}
\usepackage[pstarrows]{fxpicture}
\end{code}
If \pkg{pict2e} is already loaded, load \pkg{fxpicture} after it. \pkg{fxpicture} needs a
\pkg{pict2e} with a driver. With \pkg{pict2e}'s \texttt{original} option, which leaves
\LaTeX's own picture commands in place, there is nothing to dash, and the line styles do
nothing.

\section{Commands}

\begin{center}
\begin{tabular}{@{}l>{\raggedright\arraybackslash}p{0.6\linewidth}@{}}
\cs{linestyle}\marg{style} & Sets the style of the lines that follow, until the end of the
  group. The styles are \texttt{solid}, \texttt{dashed}, \texttt{dotted} and
  \texttt{dashdot}.\\[4pt]
\cs{dashpattern}\marg{on}\marg{off} & Dashes the lines that follow with dashes \meta{on}
  long and gaps \meta{off} long, until the end of the group.
\end{tabular}
\end{center}

\noindent The named styles, and a pattern of your own, look like this:

\begin{center}
\setlength{\unitlength}{1mm}
\begin{tabular}{@{}lll@{}}
\toprule
\meta{style} & pattern & \\
\midrule
\texttt{solid}   & (the default)                              & \begin{picture}(36,2)\put(0,1){\line(1,0){36}}\end{picture}\\[2pt]
\texttt{dashed}  & on 3\,pt, off 3\,pt                        & \begin{picture}(36,2)\linestyle{dashed}\put(0,1){\line(1,0){36}}\end{picture}\\[2pt]
\texttt{dotted}  & on 1 line width, off 2\,pt                 & \begin{picture}(36,2)\linestyle{dotted}\put(0,1){\line(1,0){36}}\end{picture}\\[2pt]
\texttt{dashdot} & on 3\,pt, off 2\,pt, on 1 line width, off 2\,pt & \begin{picture}(36,2)\linestyle{dashdot}\put(0,1){\line(1,0){36}}\end{picture}\\[2pt]
\cs{dashpattern}\texttt{\{3pt\}\{2pt\}} & on 3\,pt, off 2\,pt & \begin{picture}(36,2)\dashpattern{3pt}{2pt}\put(0,1){\line(1,0){36}}\end{picture}\\
\bottomrule
\end{tabular}
\end{center}

The patterns are the same as TikZ's \texttt{dashed}, \texttt{dotted} and
\texttt{dash dot}, so a \texttt{picture} and a TikZ drawing on the same page look alike.

\paragraph{Lengths.} The arguments of \cs{dashpattern} are lengths, such as \texttt{3pt} or
\texttt{1mm}, or plain numbers, which count as multiples of \cs{unitlength}, like other
\texttt{picture} lengths. A plain number uses \cs{unitlength} as it is when \cs{dashpattern}
is given, not when the line is drawn. Neither length may be negative, and they cannot both be
zero.

\paragraph{Dots follow the line width.} The dots of \texttt{dotted} and \texttt{dashdot} are
as long as the line is thick. The width is read when each line is drawn, so the dots grow with
\cs{thicklines} or \cs{linethickness}, and they stay square:
\begin{example}
\setlength{\unitlength}{1mm}
\begin{picture}(40,12)
 \linestyle{dotted}
 \put(0,10){\line(1,0){40}}
 \thicklines
 \put(0,5){\line(1,0){40}}
 \linethickness{1.2pt}
 \put(0,0){\line(1,0){40}}
\end{picture}
\end{example}

\paragraph{Round dots.} For round dots, combine \pkg{pict2e}'s \cs{roundcap} with a
\cs{dashpattern} whose dashes have no length. Every dash then becomes a dot as wide as the
line. Note that without \cs{roundcap}, dashes of zero length can't be seen.
\begin{example}
\setlength{\unitlength}{1mm}
\begin{picture}(40,4)
 \linethickness{1.2pt}
 \roundcap\dashpattern{0pt}{3pt}
 \put(1,2){\line(1,0){38}}
\end{picture}
\end{example}

\section{Examples}

\subsection{Scope}

\cs{linestyle} and \cs{dashpattern} are declarations, so a pair of braces limits them to a
part of a picture. The last style given wins, so \cs{linestyle}\texttt{\{solid\}} switches
back to solid lines:
\begin{example}
\setlength{\unitlength}{1mm}
\begin{picture}(40,22)
 \put(0,20){\line(1,0){40}}
 {\linestyle{dashed}
  \put(0,15){\line(1,0){40}}
  {\linestyle{dotted}
   \put(0,10){\line(1,0){40}}}
  \put(0,5){\line(1,0){40}}
  \linestyle{solid}
  \put(0,0){\line(1,0){40}}}
\end{picture}
\end{example}

\subsection{Every kind of line}

\begin{example}
\setlength{\unitlength}{1mm}
\begin{picture}(50,40)
 \linestyle{dashed}
 \put(7,33){\circle{12}}
 \put(27,33){\oval(18,10)}
 \put(44,30){\arc[180,360]{6}}
 \put(0,16){\cbezier(0,0)(15,10)(30,-6)(50,2)}
 \polygon(0,0)(18,0)(9,10)
 \polyline(24,0)(30,10)(36,0)(42,10)(48,0)
\end{picture}
\end{example}

\subsection{Arrows}

The shaft of an arrow is dashed, and its head stays solid. Both of \pkg{pict2e}'s arrowheads
can be used, and the head keeps its shape.
\begin{example}
\setlength{\unitlength}{1mm}
\begin{picture}(45,30)
 \linestyle{dashed}
 \put(0,28){\vector(1,0){45}}
 \put(0,0){\vector(3,1){42}}
 \thicklines
 \linestyle{dashdot}
 \put(0,20){\vector(1,0){45}}
\end{picture}
\end{example}

\subsection{A figure}

\begin{example}
\setlength{\unitlength}{1mm}
\begin{picture}(50,36)(-5,-5)
 \put(0,0){\vector(1,0){45}}
 \put(0,0){\vector(0,1){30}}
 \put(46,-1){$x$}\put(-1,31){$y$}
 \qbezier(0,2)(15,40)(40,20)
 {\linestyle{dotted}
  \put(20,0){\line(0,1){24.5}}
  \put(0,24.5){\line(1,0){20}}}
 {\linestyle{dashed}
  \put(4,10){\line(4,3){30}}}
 \put(20,24.5){\circle*{1.2}}
\end{picture}
\end{example}

\section{What is dashed}

\begin{itemize}
\item \textbf{Dashed:} every path that \pkg{pict2e} strokes, from \cs{line}, \cs{Line},
  \cs{polyline}, \cs{polygon}, \cs{circle}, \cs{oval}, \cs{arc}, \cs{qbezier}, \cs{cbezier},
  and \cs{moveto} \dots\ \cs{strokepath}, to the shafts of \cs{vector}, \cs{Vector} and
  \cs{polyvector}.
\item \textbf{Not dashed:} filled shapes, which are \cs{circle*}, \cs{polygon*}, \cs{arc*},
  \cs{fillpath} and arrowheads. Also \cs{qbezier}\texttt{[}\meta{n}\texttt{]} with a number of
  points, which draws dots of its own, and \cs{dashbox}, which has its own dashes. Text is not
  affected.
\end{itemize}

\noindent Each path starts its pattern afresh, so every line starts with a dash. The pattern
carries on round the corners of one path, such as a polygon or an oval, as PostScript and PDF
always dash. The pattern is not stretched to fit the length of the line, so a line may end
part way through a gap.

\section{How it works}

This section is for those who want to know what \pkg{fxpicture} changes in \pkg{pict2e}. The
full code follows in section~\ref{sec:code}.

\subsection{pict2e's paths}

\pkg{pict2e} draws each shape in the same way. The command, \cs{oval} for example, builds a
path with \cs{pIIe@moveto}, \cs{pIIe@lineto} and \cs{pIIe@curveto}, which collect PostScript
or PDF operators in a token register, \cs{pIIe@GRAPH}. Then \cs{pIIe@strokeGraph} or
\cs{pIIe@fillGraph} hands the register to \cs{pIIe@drawGraph}. That macro puts the drawing
state in front of the path and the paint operator after it, and passes the whole to the
driver as one literal. For a stroke, the state is the scale from points to big points, the line
width, and any line cap and line join, for example in PDF:
\begin{code}
q 0.99626 0 0 0.99626 0 0 cm  0.4 w  0 0 m 113.81 0 l S Q
\end{code}
The literal is wrapped in a save and a restore (\texttt{q}~\dots~\texttt{Q} in PDF,
\texttt{save}~\dots~\texttt{restore} in PostScript), so nothing set in it lasts past the
shape.

\subsection{The dash}

\pkg{fxpicture} replaces \cs{pIIe@drawGraph} with a copy that writes one more operator, the
dash, after the line join, in the branch that strokes. Fills are left as they are. The dash is
the macro \cs{fxp@dash}, which the styles set:
\begin{code}
q 0.99626 0 0 0.99626 0 0 cm  0.4 w [3 3] 0 d  0 0 m 113.81 0 l S Q
\end{code}
Lengths are written in points, since \pkg{pict2e} has already scaled its user space to
points. The operator is \texttt{d} for PDF, from pdf\TeX, Lua\TeX, Xe\TeX\ and dvipdfm(x),
and \texttt{setdash} for PostScript, from dvips. \pkg{pict2e}'s mode tells \pkg{fxpicture}
which to use.

\cs{fxp@dash} is expanded inside the \cs{edef} that builds the state. So \texttt{dotted} and
\texttt{dashdot} write the line width there, \cs{strip@pt}\cs{@wholewidth}, and their dots
take the width of the line being drawn. \cs{dashpattern} works out its lengths at once, which
is why a plain number takes \cs{unitlength} as it is then.

The solid style leaves \cs{fxp@dash} empty. So a picture with no \cs{linestyle} comes out
exactly as \pkg{pict2e} makes it, byte for byte. Since every shape is saved and restored, a
dash never reaches past its own shape, and nothing has to be undone at the end of a group.

\subsection{Arrows}

\pkg{pict2e} draws an arrow as one filled outline, which goes round the head and the shaft
together. Filling ignores dashes, so with a line style \pkg{fxpicture} draws an arrow in two
parts:
\begin{enumerate}
\item It runs \pkg{pict2e}'s own arrowhead code with \cs{pIIe@lineto} changed to skip the
  points at $x=0$. In both the \LaTeX\ and the PSTricks arrowheads, these are the only points
  of the outline at $x=0$: the two back corners of the shaft. What is left is the head, in its
  own shape.
\item It strokes the shaft as a line of its own, from the tail to half way into the head, and
  then fills the head on top. The dashes so end under the head.
\end{enumerate}
Solid arrows are \pkg{pict2e}'s, untouched. \cs{ltxarrows} and \cs{pstarrows} are redefined
to choose the head for both cases. An arrow shorter than its head has no shaft, and is drawn as
its head alone.

\subsection{If pict2e changes}

\pkg{fxpicture} replaces a macro that is internal to \pkg{pict2e}. When loaded, it compares
\cs{pIIe@drawGraph} with the one it was written for, from \pkg{pict2e} 0.4b of 2020, and warns
if they differ.

\subsection{SVG and other outputs}

The line styles map directly onto other drawing systems. In SVG, \cs{linestyle}\texttt{\{dashed\}}
is \texttt{stroke-dasharray="3 3"}, and \cs{dashpattern}\texttt{\{3pt\}\{2pt\}} is
\texttt{stroke-dasharray="3 2"}, in points. SVG, like PDF, starts the pattern afresh on each
path. This is how the editor at \url{https://fxeditor.codecogs.com} draws them.

\clearpage
\section{The code}\label{sec:code}

{\lstinputlisting[basicstyle=\ttfamily\footnotesize, breaklines, numbers=left,
  numberstyle=\tiny\color{black!45}, frame=single, rulecolor=\color{fxframe},
  backgroundcolor=\color{fxcode}, texcsstyle=*\color{black},
  commentstyle=\color{black!55}]{fxpicture.sty}}

\section{Author, licence and history}

\pkg{fxpicture} was written by Claude AI (Anthropic), with direction from CodeCogs Ltd.

\medskip
\noindent Copyright \copyright\ 2026 CodeCogs Ltd.

\medskip
\noindent This work may be distributed and/or modified under the conditions of the \LaTeX\
Project Public License, either version 1.3c of this license or (at your option) any later
version. The latest version of this license is in
\url{https://www.latex-project.org/lppl.txt}. This work has the LPPL maintenance status
`maintained'. The Current Maintainer of this work is CodeCogs Ltd.

\medskip
\noindent For a working implementation, see \url{https://fxeditor.codecogs.com}.

\subsection*{History}
\begin{description}
\item[1.0 (2026/10/15)] First release.
\end{description}

\end{document}