% tikzfins-doc.tex -- documentation for the tikzfins package
% Version 0.3, 2026/11/04
%
% Copyright (C) 2026 Vernon Merrick Fanning
%
% 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
%   https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Vernon Merrick Fanning.
%
% This work consists of the files tikzfins.sty, tikzfins-doc.tex
% and README.md, and the derived file tikzfins-doc.pdf.
%
% All drawings in this work are original. They were made from scratch
% with TikZ paths for this package; none is traced from or based on a
% photograph or on anyone else's artwork.
\documentclass[11pt,a4paper]{article}

\newcommand\pkgversion{0.3}
\newcommand\pkgdate{2026/11/04}
\newcommand\pkgauthor{Vernon Merrick Fanning}

\usepackage[margin=2.4cm, top=2.2cm]{geometry}
\usepackage{mathpazo}
\usepackage[scaled=0.92]{helvet}
\usepackage{microtype}
\usepackage{tikzfins}
\usepackage{booktabs}
\usepackage{longtable}
\usepackage{array}
\usepackage{enumitem}
\usepackage[most]{tcolorbox}
\tcbuselibrary{listings}
\usepackage[colorlinks, linkcolor=finswater!60!black, urlcolor=finswater!60!black,
            pdftitle={The tikzfins package}, pdfauthor={\pkgauthor},
            pdfsubject={Aquarium fish and aquascapes with TikZ},
            pdfkeywords={TikZ, fish, aquarium, aquascape, reef, figurines}]{hyperref}

% ---- look ---------------------------------------------------------------
\colorlet{docaccent}{finswater!60!black}
\colorlet{doccode}{finswatertop!22!white}
\colorlet{docline}{finswater!55}
\setlength\parindent{0pt}
\setlength\parskip{0.55em}
\setlist{nosep, leftmargin=1.6em}

\makeatletter
\renewcommand\section{\@startsection{section}{1}{\z@}{-3.2ex plus -1ex minus -.2ex}%
  {1.4ex}{\sffamily\Large\bfseries\color{finsframe}}}
\renewcommand\subsection{\@startsection{subsection}{2}{\z@}{-2.6ex plus -1ex minus -.2ex}%
  {0.8ex}{\sffamily\large\bfseries\color{finsframe}}}
\makeatother

\newcommand\pkg[1]{\textsf{#1}}
\newcommand\bs{\char92 }
\newcommand\cs[1]{\texttt{\bs#1}}
\newcommand\key[1]{\texttt{#1}}
\newcommand\lb{\char`\{}
\newcommand\rb{\char`\}}
\newcommand\meta[1]{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}

\lstdefinestyle{fins}{
  language=[LaTeX]TeX,
  basicstyle=\ttfamily\small,
  columns=fullflexible,
  keepspaces=true,
  texcsstyle=*\color{docaccent}\bfseries,
  moretexcs={clownfish,bluetang,yellowtang,angelfish,moorishidol,goldfish,betta,
    guppy,neontetra,swordtail,discus,tigerbarb,pufferfish,seahorse,royalgramma,
    rock,stones,driftwood,vallisneria,amazonsword,cabomba,ludwigia,javafern,kelp,
    mossball,anemone,braincoral,staghorn,starfish,seashell,bubbles,airstone,
    treasurechest,castle,snail,corydoras,pleco,gourami,zebradanio,lionfish,
    damselfish,shark,shrimp,hermitcrab,jellyfish,foreach,node,tikz,draw},
  commentstyle=\color{black!50}\itshape,
  literate={\$}{{\char36}}1,
}
\lstset{style=fins}

% code on the left, result on the right
\DeclareTCBListing{example}{ !O{} }{
  enhanced, listing side text, colback=doccode, colframe=docline,
  boxrule=0.5pt, arc=2mm, left=2mm, right=2mm, top=1mm, bottom=1mm,
  righthand width=0.42\linewidth, sidebyside gap=4mm, valign=center,
  halign lower=center, listing options={style=fins}, #1}
% code above, result below
\DeclareTCBListing{examplewide}{ !O{} }{
  enhanced, listing above text, colback=doccode, colframe=docline,
  boxrule=0.5pt, arc=2mm, left=2mm, right=2mm, top=1mm, bottom=1mm,
  halign lower=center, listing options={style=fins}, #1}

% a labelled cell for the galleries
\newcommand\cell[4][-1.45]{% [label y], x, label, drawing command
  #4\node[font=\ttfamily\scriptsize, text=black!65] at (#2,#1) {#3};}

\begin{document}

% =========================================================================
\begin{titlepage}
  \centering
  \vspace*{1.0cm}
  {\sffamily\bfseries\fontsize{44}{48}\selectfont\color{finsframe} tikzfins\par}
  \vspace{0.5cm}
  {\Large Aquarium fish and aquascapes with Ti\emph{k}Z\par}
  \vspace{1.2cm}
  \begin{tikzpicture}
  \begin{aquarium}[width=15, height=8.4]
    \vallisneria[at={(0.9,0.6)}, height=6, count=12, sway=6]
    \rock[at={(3.3,0.75)}, variant=2, scale=1.1, moss]
    \javafern[at={(3.1,2.05)}, height=1.2, sway=-6]
    \anemone[at={(5.6,0.45)}]
    \clownfish[at={(5.9,2.2)}, scale=0.42, tail=10]
    \clownfish[at={(4.9,2.9)}, scale=0.32, facing=left]
    \braincoral[at={(8.6,0.45)}, scale=0.9]
    \staghorn[at={(11.0,0.45)}, scale=1.25]
    \ludwigia[at={(13.6,0.5)}, height=3.8]
    \starfish[at={(7.2,0.25)}, scale=0.45, face=happy]
    \treasurechest[at={(12.6,0.35)}, scale=0.65, bubbles=7]
    \airstone[at={(14.5,0.35)}, height=6.6]
    \stones[at={(9.8,0.25)}, count=4, width=1]
    \bluetang[at={(9.4,5.4)}, scale=0.62, facing=left]
    \yellowtang[at={(11.8,3.4)}, scale=0.5, facing=left]
    \moorishidol[at={(3.2,5.5)}, scale=0.5]
    \royalgramma[at={(7.9,3.0)}, scale=0.4]
    \seahorse[at={(13.1,5.6)}, scale=0.42]
    \pufferfish[at={(6.7,6.6)}, scale=0.42, bubbles=3]
  \end{aquarium}
  \end{tikzpicture}

  \vspace{0.9cm}
  \begin{tikzpicture}
    \goldfish[scale=0.62, facing=left, bones=2, speed, sweat, eye=big, mouth=open]
    \shark[at={(3.9,0.05)}, scale=0.5, facing=left, mouth=chomp, eye=angry]
    \snail[at={(7.7,-0.55)}, scale=0.62, hat=top]
    \pufferfish[at={(10.1,0)}, scale=0.62, puffed]
    \tigerbarb[at={(12.9,0)}, scale=0.62, legs, eye=googly]
  \end{tikzpicture}

  \vfill
  {\large \pkgauthor\par}
  \vspace{0.4cm}
  {Version \pkgversion\quad\textbullet\quad\pkgdate\par}
  \vspace{0.3cm}
  {\small Copyright \copyright\ 2026 \pkgauthor\par}
  \vspace{0.15cm}
  {\small Released under the \LaTeX\ Project Public License 1.3c or later\par}
  \vspace*{0.4cm}
\end{titlepage}

\begingroup\setlength\parskip{0pt}\tableofcontents\endgroup
\newpage

% =========================================================================
\section{Introduction}

\pkg{tikzfins} draws aquarium fish in side profile with Ti\emph{k}Z, together
with everything you need to build a tank around them: sand, gravel, aquasoil
and pebbles, rocks, driftwood, plants, corals, ornaments and bubbles. There are
twenty-two fish, from the clownfish, the blue tang and a blacktip reef shark to
the goldfish, the neon tetra and the corydoras of a home aquarium, and their
tank mates: snails, starfish, a cleaner shrimp, a hermit crab and a moon
jellyfish. They are drawn as flat vector illustrations, with counter-shading,
translucent fins and fin rays, and with the markings of the real species, so
they look at home in a diagram, a worksheet or a full aquascape.

It would not be a sibling of \pkg{tikzeats} without some nonsense. Any fish
can be eaten down to the bone, open an enormous mouth full of teeth, flee in a
cold sweat, grow a pair of legs in trainers, get caught on a hook, blow
bubbles, talk, wear a hat or a snorkel, and swim in a school.

\begin{example}
\begin{tikzpicture}
  \clownfish[bones=1]
\end{tikzpicture}
\end{example}

\pkg{tikzfins} was inspired by samcarter's
\href{https://ctan.org/pkg/tikzducks}{\pkg{tikzducks}} and
\href{https://ctan.org/pkg/tikzlings}{\pkg{tikzlings}}, Florian Sihler's
\href{https://ctan.org/pkg/tikzpingus}{\pkg{tikzpingus}}, and its older sibling
\pkg{tikzeats}. All figures are original drawings, made from scratch with
Ti\emph{k}Z paths, and the package can be loaded alongside all of these.

Until version 1.0, commands and keys may still change.

\subsection{Loading the package}

\begin{lstlisting}
\usepackage{tikzfins}
\end{lstlisting}

\pkg{tikzfins} needs only Ti\emph{k}Z, which it loads for you along with the
\texttt{calc}, \texttt{shapes.misc}, \texttt{decorations} and
\texttt{decorations.pathmorphing} libraries. It works with pdf\LaTeX,
Xe\LaTeX\ and Lua\LaTeX, and it has no package options.

% =========================================================================
\section{Basic use}

Every fish and every component is a command used inside a
\texttt{tikzpicture}, with an optional argument of \meta{key}=\meta{value}
options:

\begin{lstlisting}
\begin{tikzpicture}
  \goldfish
  \betta[at={(4,0)}, facing=left]
\end{tikzpicture}
\end{lstlisting}

At \key{scale=1} a fish is about 3\,cm long from nose to tail and is centred
on its \key{at} point. Aquarium components and bottom-dwelling invertebrates
are different: they \emph{stand} on their \key{at} point, which is the middle
of their base, so that you can put them on the sand.

\begin{description}[style=nextline, leftmargin=1.6em]
  \item[\key{at=\lb(\meta{x},\meta{y})\rb}] Moves the fish or component. The
    default is \key{(0,0)}.
  \item[\key{scale=}\meta{factor}] Resizes it. Unlike Ti\emph{k}Z's own
    \key{scale}, this key also scales line widths, so small fish stay delicate.
  \item[\key{facing=left|right}] Fish face right by default. \key{facing=left}
    mirrors a fish or a component.
  \item[\key{rotate=}\meta{angle}] Tilts it, for a fish swimming up or down.
  \item[\key{tail=}\meta{angle}] Swings the tail fin around its base, which
    makes a still picture look like it is swimming.
\end{description}

\begin{example}
\begin{tikzpicture}
  \guppy[scale=0.6]
  \guppy[at={(2.2,0.6)}, scale=0.8,
    rotate=15, tail=-20]
  \guppy[at={(1.2,-1)}, facing=left,
    scale=0.7, tail=20]
\end{tikzpicture}
\end{example}

% =========================================================================
\section{The fish}

\subsection{Reef fish}

\begin{center}
\begin{tikzpicture}
  \cell{0}{\bs clownfish}{\clownfish[scale=0.9]}
  \cell{4.2}{\bs bluetang}{\bluetang[at={(4.2,0)}, scale=0.9]}
  \cell{8.4}{\bs yellowtang}{\yellowtang[at={(8.4,0)}, scale=0.9]}
  \cell{12.5}{\bs royalgramma}{\royalgramma[at={(12.5,0)}, scale=0.9]}
\end{tikzpicture}

\vspace{0.6cm}
\begin{tikzpicture}
  \cell[-1.75]{0}{\bs moorishidol}{\moorishidol[scale=0.9]}
  \cell[-1.75]{4.0}{\bs pufferfish}{\pufferfish[at={(4.0,0)}, scale=0.9]}
  \cell[-1.75]{8.0}{puffed}{\pufferfish[at={(8.0,0)}, scale=0.8, puffed]}
  \cell[-1.75]{11.5}{\bs seahorse}{\seahorse[at={(11.5,0)}, scale=0.9]}
\end{tikzpicture}

\vspace{0.6cm}
\begin{tikzpicture}
  \cell[-1.6]{0}{\bs lionfish}{\lionfish[scale=0.85]}
  \cell[-1.6]{3.8}{\bs damselfish}{\damselfish[at={(3.8,0)}, scale=0.9]}
  \cell[-1.6]{7.2}{stripes=4}{\damselfish[at={(7.2,0)}, scale=0.9, stripes=4]}
  \cell[-1.6]{11.9}{\bs shark}{\shark[at={(11.6,0)}, scale=0.62]}
\end{tikzpicture}
\end{center}

\begin{description}[style=nextline, leftmargin=1.6em]
  \item[\cs{pufferfish}] \key{puffed} blows it up into a spiky ball; a puffed
    pufferfish opens its mouth unless you choose another one.
  \item[\cs{seahorse}] Stands upright, and has no bones to eat (see
    section~\ref{sec:bones}).
  \item[\cs{damselfish}] A humbug damselfish with three bars;
    \key{stripes=4} gives the four-stripe damselfish, whose tail is black too.
  \item[\cs{shark}] A blacktip reef shark. It is bigger than the other fish:
    about 4.6 long at \key{scale=1}.
\end{description}

\subsection{Freshwater fish}

\begin{center}
\begin{tikzpicture}
  \cell{0}{\bs goldfish}{\goldfish[scale=0.9]}
  \cell{4.4}{\bs betta}{\betta[at={(4.4,0)}, scale=0.8]}
  \cell{8.6}{\bs guppy}{\guppy[at={(8.6,0)}, scale=0.9]}
  \cell{12.6}{\bs neontetra}{\neontetra[at={(12.6,0)}, scale=0.9]}
\end{tikzpicture}

\vspace{0.6cm}
\begin{tikzpicture}
  \cell[-1.75]{0}{\bs swordtail}{\swordtail[at={(0.3,0)}, scale=0.8]}
  \cell[-1.75]{4.1}{\bs angelfish}{\angelfish[at={(4.1,0)}, scale=0.75]}
  \cell[-1.75]{8.1}{\bs discus}{\discus[at={(8.1,0)}, scale=0.9]}
  \cell[-1.75]{12.3}{\bs tigerbarb}{\tigerbarb[at={(12.3,0)}, scale=0.9]}
\end{tikzpicture}

\vspace{0.6cm}
\begin{tikzpicture}
  \cell[-1.45]{0}{\bs corydoras}{\corydoras[scale=0.95]}
  \cell[-1.45]{4.1}{type=bronze}{\corydoras[at={(4.1,0)}, scale=0.95, type=bronze]}
  \cell[-1.45]{8.2}{\bs pleco}{\pleco[at={(8.2,0)}, scale=0.95]}
  \cell[-1.45]{12.3}{\bs zebradanio}{\zebradanio[at={(12.3,0)}, scale=0.95]}
\end{tikzpicture}

\vspace{0.6cm}
\begin{tikzpicture}
  \cell[-1.5]{0}{\bs gourami}{\gourami[scale=0.9]}
  \cell[-1.5]{4.2}{type=blue}{\gourami[at={(4.2,0)}, scale=0.9, type=blue]}
\end{tikzpicture}
\end{center}

\begin{description}[style=nextline, leftmargin=1.6em]
  \item[\cs{corydoras}] A panda corydoras, with its black mask, dorsal fin and
    tail spot; \key{type=bronze} gives a bronze corydoras. Both have barbels
    and no mouth line unless you choose a \key{mouth}.
  \item[\cs{pleco}] A bristlenose pleco, with the bristles on its snout and a
    sucker mouth underneath.
  \item[\cs{gourami}] A male dwarf gourami, with its long feeler-like pelvic
    fins; \key{type=blue} gives a blue (three-spot) gourami.
\end{description}

% =========================================================================
\section{Invertebrates}\label{sec:inverts}

The tank mates stand on their \key{at} point like the aquarium components,
except the jellyfish, which floats, centred on it. Otherwise they work just
like fish: they take \key{scale}, \key{facing}, the colour keys, and all the
extras of section~\ref{sec:extras} except \key{bones} and \key{tail}.

\begin{center}
\begin{tikzpicture}
  \cell[-0.35]{0}{\bs snail}{\snail}
  \cell[-0.35]{3.0}{type=nerite}{\snail[at={(3.0,0)}, type=nerite]}
  \cell[-0.35]{5.9}{type=ramshorn}{\snail[at={(5.9,0)}, type=ramshorn]}
  \cell[-0.35]{9.6}{\bs shrimp}{\shrimp[at={(9.2,0)}, scale=0.95]}
  \cell[-0.35]{13.2}{\bs hermitcrab}{\hermitcrab[at={(13.4,0)}]}
\end{tikzpicture}

\vspace{0.5cm}
\begin{tikzpicture}
  \cell[-0.35]{0}{\bs starfish}{\starfish}
  \cell[-0.35]{2.5}{type=chocolatechip}{\starfish[at={(2.5,0)}, type=chocolatechip]}
  \cell[-0.35]{5.0}{type=linckia}{\starfish[at={(5.0,0)}, type=linckia]}
  \cell[-0.35]{7.5}{arms=9, face=happy}{\starfish[at={(7.5,0)}, arms=9, face=happy]}
  \cell[-0.35]{11.0}{\bs jellyfish}{\jellyfish[at={(11.0,1.4)}, scale=0.95]}
  \cell[-0.35]{13.6}{face=happy}{\jellyfish[at={(13.6,1.4)}, scale=0.8, face=happy, sway=10]}
\end{tikzpicture}
\end{center}

\begin{description}[style=nextline, leftmargin=1.6em]
  \item[\cs{snail}] A golden mystery snail by default; \key{type=nerite} gives
    a zebra nerite and \key{type=ramshorn} a red ramshorn snail. \key{body} is
    the shell, \key{pattern} its stripes and \key{accent} the snail itself.
    Its eye sits at the base of its tentacles, so \key{eye=googly} is on a
    stalk.
  \item[\cs{starfish}] \key{type=common} (the default), \key{chocolatechip}
    or \key{linckia}, the blue sea star. \key{arms=}\meta{n} sets the number
    of arms (default 5).
  \item[\cs{shrimp}] A cleaner shrimp: red back with a white stripe, long white
    antennae.
  \item[\cs{hermitcrab}] A hermit crab in a borrowed shell; \key{body} is the
    shell and \key{accent} the crab.
  \item[\cs{jellyfish}] A moon jellyfish. \key{sway} bends its arms and
    tentacles.
\end{description}

Real starfish and jellyfish have no faces, so they have none unless you ask:
\key{face=happy} or \key{face=sleepy} gives them a pair of eyes and a smile,
and \key{eye} and \key{mouth} work too.

\begin{example}
\begin{tikzpicture}
  \snail[hat=top, legs]
  \starfish[at={(2.1,0)}, eye=googly,
    mouth=chomp, type=chocolatechip,
    says={Hello}]
\end{tikzpicture}
\end{example}

% =========================================================================
\clearpage
\section{Faces}\label{sec:faces}

\subsection{Eyes}

Every fish takes \key{eye=}\meta{name}. The default is \key{normal}, a
realistic eye whose ring is the fish's \key{iris} colour.

\begin{center}
\begin{tikzpicture}
  \foreach \e [count=\i from 0] in {normal,googly,big,sleepy,closed,dead,
      heart,angry,dizzy,side,starry,none}{
    \pgfmathsetmacro\x{mod(\i,6)*2.75}
    \pgfmathsetmacro\y{-int(\i/6)*2.4}
    \begin{scope}[shift={(\x,\y)}]
      \cell[-0.95]{0}{eye=\e}{\yellowtang[scale=0.6, eye=\e, eye scale=1.3]}
    \end{scope}
  }
\end{tikzpicture}
\end{center}

\key{eye scale=}\meta{factor} makes the eye bigger or smaller.

\subsection{Mouths}

\key{mouth=}\meta{name} changes the mouth at the tip of the snout. Two of them
are human, which is exactly as unsettling as it sounds. \key{fangs} keeps the
mouth shut but lets two fangs poke out. \key{chomp} is different from the
others: rather than drawing a mouth on the fish, it opens the fish's whole head
into a pair of jaws lined with teeth (section~\ref{sec:jaws}).

\begin{center}
\begin{tikzpicture}
  \foreach \m [count=\i from 0] in {default,open,smile,frown,teeth,lips,blep,chomp,fangs,none}{
    \pgfmathsetmacro\x{mod(\i,5)*3.3}
    \pgfmathsetmacro\y{-int(\i/5)*2.5}
    \begin{scope}[shift={(\x,\y)}]
      \cell[-1.0]{0}{mouth=\m}{\goldfish[scale=0.6, mouth=\m]}
    \end{scope}
  }
\end{tikzpicture}
\end{center}

\subsection{Jaws}\label{sec:jaws}

With \key{mouth=chomp} a fish is ready to feed: its head opens into a wedge-shaped
gape, hinged behind and below the eye, and teeth line both jaws. The jaws follow
the outline of each fish, and the upper jaw always passes below the eye.
\key{gape=}\meta{angle} sets how wide they open, from about 30 to 120 degrees;
the default is 110.

\begin{center}
\begin{tikzpicture}
  \foreach \g [count=\i from 0] in {30,60,90,110}{
    \cell[-1.25]{\i*4.1}{gape=\g}{\pufferfish[at={(\i*4.1,0)}, mouth=chomp, gape=\g, scale=0.95]}
  }
\end{tikzpicture}
\end{center}

The seahorse and the invertebrates have no jaws to open, so for them
\key{chomp} draws a mouth full of teeth instead.

\subsection{Predator and prey}

\key{mouth=chomp} pairs nicely with \key{bones} (section~\ref{sec:bones}) and
the chase keys of section~\ref{sec:run}:

\begin{examplewide}
\begin{tikzpicture}
  \goldfish[facing=left, bones=2, eye=big, mouth=open, speed, sweat, scale=0.8]
  \shark[at={(5.6,0.1)}, facing=left, mouth=chomp, eye=angry, scale=0.7]
\end{tikzpicture}
\end{examplewide}

\begin{example}
\begin{tikzpicture}
  \discus[mouth=chomp, eye=angry]
  \guppy[at={(2.4,0.15)}, eye=big,
    sweat, scale=0.6]
\end{tikzpicture}
\end{example}

% =========================================================================
\section{Extras}\label{sec:extras}

\subsection{Eaten to the bone}\label{sec:bones}

\key{bones=}\meta{n} eats a fish from the tail, from 0 (the default) to 3. A
plain \key{bones} means 1. Every third leaves a row of bite marks and a little
more skeleton; \key{bones=3} leaves only the head. The colour of the bitten
edge is the fish's \key{inside} colour.

\begin{center}
\begin{tikzpicture}
  \foreach \n/\e [count=\i from 0] in {0/normal, 1/big, 2/sleepy, 3/dead}{
    \cell{\i*4.1}{bones=\n}{\goldfish[at={(\i*4.1,0)}, bones=\n, eye=\e, scale=0.9]}
  }
\end{tikzpicture}
\end{center}

Bones work on every fish except the \cs{seahorse}; it and the invertebrates
ignore the key with a warning.

\subsection{Legs}

\key{legs} gives a fish a pair of human legs with socks and trainers, for the
day it decides to leave the water.

\begin{center}
\begin{tikzpicture}
  \cell[-1.55]{0}{legs}{\clownfish[legs, scale=0.85]}
  \cell[-1.55]{4.3}{legs, eye=googly}{\pufferfish[at={(4.3,0)}, legs, eye=googly, scale=0.85]}
  \cell[-1.55]{8.4}{legs, says=...}{\tigerbarb[at={(8.4,0)}, legs, scale=0.85, mouth=smile, says={Bye!}]}
\end{tikzpicture}
\end{center}

\subsection{On the run}\label{sec:run}

\key{speed} draws speed lines behind the tail, and \key{sweat} sends two drops
of sweat flying off the head.

\begin{center}
\begin{tikzpicture}
  \cell[-1.2]{0.3}{speed}{\zebradanio[at={(0.6,0)}, speed, scale=0.9]}
  \cell[-1.2]{5.0}{sweat}{\clownfish[at={(5.0,0)}, sweat, eye=big, scale=0.75]}
  \cell[-1.2]{10.4}{speed, sweat}{\bluetang[at={(10.6,0)}, speed, sweat, eye=big, mouth=open, scale=0.75]}
\end{tikzpicture}
\end{center}

\subsection{Hooked, bubbles and speech}

\key{hooked} hangs the fish from a fishing line; \key{line length} sets how far
up the line goes (the default is 4, which an aquarium cuts off at its frame).
\key{bubbles=}\meta{n} lets out a trail of bubbles from the mouth (a plain
\key{bubbles} is 3). \key{says=\lb\meta{text}\rb} and
\key{thinks=\lb\meta{text}\rb} add a speech or thought bubble; the text can
contain maths and line breaks.

\begin{center}
\begin{tikzpicture}
  \cell[-1.3]{0}{hooked}{\swordtail[at={(0.4,0)}, hooked, line length=1.4, scale=0.85, eye=big]}
  \cell[-1.3]{4.3}{bubbles=4}{\goldfish[at={(4.3,0)}, bubbles=4, scale=0.8, mouth=open]}
  \cell[-1.3]{8.3}{says}{\bluetang[at={(8.3,0)}, scale=0.7, says={$2+2=5$}]}
  \cell[-1.3]{12.5}{thinks}{\neontetra[at={(12.5,0)}, scale=0.8, thinks={Food?}]}
\end{tikzpicture}
\end{center}

\subsection{Hats, snorkels and moustaches}

\key{hat=} takes \key{crown}, \key{party}, \key{top}, \key{pirate} or
\key{none}. \key{snorkel} gives a mask and snorkel, and \key{moustache} does
what it says.

\begin{center}
\begin{tikzpicture}
  \cell{0}{hat=crown}{\betta[scale=0.75, hat=crown]}
  \cell{3.4}{hat=party}{\guppy[at={(3.4,0)}, scale=0.85, hat=party]}
  \cell{6.8}{hat=top}{\goldfish[at={(6.8,0)}, scale=0.75, hat=top, moustache]}
  \cell{10.2}{hat=pirate}{\clownfish[at={(10.2,0)}, scale=0.7, hat=pirate, eye=angry]}
  \cell{13.6}{snorkel}{\yellowtang[at={(13.6,0)}, scale=0.7, snorkel]}
\end{tikzpicture}
\end{center}

\subsection{Belly up}

\key{belly up} turns a fish upside down. Bubbles and speech stay upright.

\begin{example}
\begin{tikzpicture}
  \guppy[belly up, eye=dead,
    thinks={Why?}]
\end{tikzpicture}
\end{example}

\subsection{Schools}

\key{school=}\meta{n} draws a whole school: the fish at \key{at} leads, and
the others follow in loose rows, slightly smaller and scattered.
\key{school spread=}\meta{factor} spaces them out, and \key{seed} gives a
different arrangement. Only the leader keeps its speech bubble, bubbles and
hook.

\begin{examplewide}
\begin{tikzpicture}
  \neontetra[school=9, scale=0.5, facing=left]
  \clownfish[at={(9.5,0.2)}, school=4, scale=0.4, seed=3, school spread=1.2]
\end{tikzpicture}
\end{examplewide}

% =========================================================================
\section{Building an aquascape}

\subsection{The aquarium}

The \texttt{aquarium} environment draws a tank with water, sand and a frame,
and clips everything inside it to the glass. Its lower left corner is at
\key{(0,0)}, so you can place things with ordinary coordinates.

\begin{examplewide}
\begin{tikzpicture}
\begin{aquarium}[width=13, height=6]
  \vallisneria[at={(1,0.5)}, height=4.5, sway=5]
  \rock[at={(4,0.6)}, variant=2, moss]
  \amazonsword[at={(7,0.4)}]
  \driftwood[at={(10.4,0.6)}, facing=left, scale=0.9]
  \mossball[at={(5.7,0.35)}, face=happy]
  \angelfish[at={(8.5,3.6)}, scale=0.6]
  \neontetra[at={(4.5,4.2)}, school=6, scale=0.4]
\end{aquarium}
\end{tikzpicture}
\end{examplewide}

The sand rises from about \key{0.5} at the front of the tank to about \key{1}
at the back (in units of \key{substrate height}). Things placed between
\key{y=0.3} and \key{0.6} have their bases buried in the front lip of the
sand; things placed higher appear further back. Draw the background first:
later commands are drawn on top.

\begin{description}[style=nextline, leftmargin=1.6em]
  \item[\key{width}, \key{height}] The inside of the tank. The defaults are 14
    and 8.
  \item[\key{substrate=}\meta{name}] What covers the floor: \key{sand} (the
    default), \key{gravel}, \key{soil} (dark aquasoil, the usual choice for a
    planted aquascape), \key{pebbles} (large river stones), \key{coral}
    (crushed coral, for a reef tank) or \key{none}. The \key{substrate height}
    (default 1) sets how high it piles up, and \key{sand} sets the colour of
    the sand.
  \item[\key{water=}\meta{colour}] The colour of the water. \key{water level}
    is the fraction of the tank that is filled (default 0.88).
  \item[\key{light rays}, \key{backdrop}, \key{glass}] Rays of light, faint
    hills in the background, and reflections on the glass. All are on by
    default; set them to \key{false} for a plainer tank.
  \item[\key{frame=}\meta{colour}] The colour of the rim and base.
\end{description}

\begin{center}
\begin{tikzpicture}
  \foreach \s [count=\i from 0] in {sand,gravel,soil,pebbles,coral}{
    \begin{aquarium}[at={(\i*3.2,0)}, width=2.85, height=1.9, substrate=\s,
                     light rays=false, backdrop=false, glass=false]
    \end{aquarium}
    \node[font=\ttfamily\scriptsize, text=black!65] at (\i*3.2+1.43,-0.6) {substrate=\s};
  }
\end{tikzpicture}
\end{center}

\begin{examplewide}
\begin{tikzpicture}
\begin{aquarium}[width=8, height=4.6, substrate=coral, water=teal!70!blue,
                 light rays=false]
  \anemone[at={(1.6,0.4)}]
  \clownfish[at={(1.9,2)}, scale=0.4]
  \braincoral[at={(4.4,0.35)}, scale=0.8]
  \staghorn[at={(6.7,0.4)}]
  \yellowtang[at={(5.3,3)}, scale=0.45, facing=left]
\end{aquarium}
\begin{aquarium}[at={(9,0)}, width=6, height=4.6, substrate=none,
                 water=finswater!60, backdrop=false]
  \kelp[at={(1,0)}, height=4, sway=-10]
  \kelp[at={(4.8,0)}, height=3.6, sway=12, seed=4]
  \seahorse[at={(3,2)}, scale=0.6]
\end{aquarium}
\end{tikzpicture}
\end{examplewide}

\subsection{The fish bowl}

The \texttt{fishbowl} environment draws a round bowl centred on \key{at}, with
a little gravel at the bottom. \key{radius} sets its size (default 1.8), and
\key{substrate} takes the same choices as for the aquarium.

\begin{example}
\begin{tikzpicture}
\begin{fishbowl}[radius=1.6,
    substrate=pebbles]
  \goldfish[at={(0,-0.15)},
    scale=0.55, bubbles=2]
\end{fishbowl}
\end{tikzpicture}
\end{example}

\subsection{Rocks and wood}

\begin{center}
\begin{tikzpicture}
  \cell[-0.35]{0}{\bs rock}{\rock}
  \cell[-0.35]{2.6}{variant=2, moss}{\rock[at={(2.6,0)}, variant=2, moss]}
  \cell[-0.35]{5.4}{variant=3}{\rock[at={(5.4,0)}, variant=3]}
  \cell[-0.35]{8.2}{\bs stones}{\stones[at={(8.2,0)}]}
  \cell[-0.35]{12}{\bs driftwood}{\driftwood[at={(12,0)}]}
\end{tikzpicture}
\end{center}

\cs{rock} comes in three \key{variant}s, and \key{moss} grows a cap of moss
on it. \cs{stones} scatters \key{count} pebbles (default 5) over a
\key{width} (default 1.8). Use \key{body} to recolour a rock.

\subsection{Plants}

\begin{center}
\begin{tikzpicture}
  \cell[-0.35]{0}{\bs vallisneria}{\vallisneria[height=3.2]}
  \cell[-0.35]{2.4}{\bs amazonsword}{\amazonsword[at={(2.4,0)}]}
  \cell[-0.35]{5.0}{\bs cabomba}{\cabomba[at={(5.0,0)}, height=2.8]}
  \cell[-0.35]{7.2}{\bs ludwigia}{\ludwigia[at={(7.2,0)}, height=2.6]}
  \cell[-0.35]{9.5}{\bs javafern}{\javafern[at={(9.5,0)}]}
  \cell[-0.35]{11.8}{\bs kelp}{\kelp[at={(11.8,0)}, height=3.2]}
  \cell[-0.35]{13.9}{\bs mossball}{\mossball[at={(13.9,0)}]}
\end{tikzpicture}
\end{center}

Every plant takes \key{height}, \key{sway} (an angle; positive leans to the
right, as if in a current) and \key{seed} (a different random plant). The
grassy and stemmy plants also take \key{count} (blades, stems or leaves) and
\key{width} (how far apart they spread). \cs{ludwigia} turns from its
\key{body} colour at the bottom to its \key{accent} colour at the top.
\cs{mossball} takes \key{radius}, and \key{face=happy} or \key{face=sleepy}.

\begin{example}
\begin{tikzpicture}
  \vallisneria[height=2.4, sway=-12]
  \ludwigia[at={(1.4,0)}, height=2.2,
    accent=orange, sway=10]
  \mossball[at={(2.6,0)}, face=sleepy]
\end{tikzpicture}
\end{example}

\subsection{Reef}

\begin{center}
\begin{tikzpicture}
  \cell[-0.35]{0}{\bs anemone}{\anemone}
  \cell[-0.35]{3.0}{\bs braincoral}{\braincoral[at={(3.0,0)}]}
  \cell[-0.35]{6.3}{\bs staghorn}{\staghorn[at={(6.3,0)}]}
  \cell[-0.35]{9.2}{\bs seashell}{\seashell[at={(9.2,0)}]}
\end{tikzpicture}
\end{center}

\cs{anemone} takes \key{count} tentacles (default 22), \key{height} and
\key{sway}; its tentacles are its \key{belly} colour with \key{accent} tips.
\cs{staghorn} takes \key{count}, the number of times it branches (default 3),
and \key{height}. The starfish are with the other invertebrates in
section~\ref{sec:inverts}.

\subsection{Ornaments and bubbles}

\begin{center}
\begin{tikzpicture}
  \cell[-0.35]{0}{\bs treasurechest}{\treasurechest[bubbles=3]}
  \cell[-0.35]{2.6}{open=false}{\treasurechest[at={(2.6,0)}, open=false]}
  \cell[-0.35]{5.6}{\bs castle}{\castle[at={(5.6,0)}]}
  \cell[-0.35]{8.4}{\bs airstone}{\airstone[at={(8.4,0)}, height=2.2]}
  \cell[-0.35]{10.6}{\bs bubbles}{\bubbles[at={(10.6,0)}, height=2.2]}
\end{tikzpicture}
\end{center}

\cs{treasurechest} is open by default and lets out \key{bubbles} (none by
default). \cs{airstone} and \cs{bubbles} take a \key{height} for their column
of bubbles.

\clearpage
\subsection{Putting it together}

A planted tank on aquasoil, with its clean-up crew on the bottom:

\begin{examplewide}
\begin{tikzpicture}
\begin{aquarium}[width=15, height=7.5, substrate=soil]
  \vallisneria[at={(0.9,0.6)}, height=5.6, count=12, sway=6]
  \ludwigia[at={(14.2,0.5)}, height=4.6]
  \rock[at={(12.3,0.75)}, variant=2, moss]
  \javafern[at={(12.1,2.1)}, height=1.2]
  \driftwood[at={(4,0.75)}]
  \amazonsword[at={(7.5,0.45)}, height=2.4]
  \corydoras[at={(5.6,0.72)}, scale=0.4]
  \corydoras[at={(6.4,0.6)}, scale=0.36, type=bronze, facing=left]
  \pleco[at={(10.3,0.55)}, scale=0.45, facing=left]
  \snail[at={(9.1,0.42)}, scale=0.38]
  \shrimp[at={(11.4,1.62)}, scale=0.32]
  \gourami[at={(7.2,3.3)}, scale=0.5]
  \neontetra[at={(3.6,4.6)}, school=7, scale=0.32]
  \zebradanio[at={(11.2,5.2)}, school=4, scale=0.32, facing=left]
\end{aquarium}
\end{tikzpicture}
\end{examplewide}

% =========================================================================
\section{Colours}

Every fish has a \key{body} colour; setting it also derives a lighter
\key{belly} and a darker \key{outline}, which you can then set yourself.
\key{fin} colours the fins, \key{iris} the eye, and \key{back} and
\key{back opacity} the shading along the back. \key{fin opacity} makes fins
more or less see-through. All of these take any \pkg{xcolor} expression.
Set \key{body} before \key{belly} or \key{outline}, because it overwrites
them.

\begin{example}
\begin{tikzpicture}
  \betta[body=finsheart, fin=finsheart,
    accent=finsstar, scale=0.8]
  \goldfish[at={(0,-2)}, body=white,
    belly=white, fin=white!90!black,
    scale=0.8]
\end{tikzpicture}
\end{example}

Most fish also have a \key{pattern} and an \key{accent} colour:

\begingroup
\small
\begin{longtable}{@{}lll@{}}
\toprule
& \key{pattern} & \key{accent}\\
\midrule
\endhead
\bottomrule
\endfoot
\cs{clownfish} & edges of the bands and fins & the bands\\
\cs{bluetang} & black marking and fin edges & the tail\\
\cs{yellowtang} & & the spine by the tail\\
\cs{angelfish} & the bars & \\
\cs{moorishidol} & the bands & the yellow parts\\
\cs{betta} & & the rims of the fins\\
\cs{guppy} & spots on the tail & the blue spot\\
\cs{neontetra} & the neon stripe & the red half\\
\cs{swordtail} & edges of the sword & the sword\\
\cs{discus} & the wavy lines & \\
\cs{tigerbarb} & the bands & red snout and fin edges\\
\cs{pufferfish} & the spots & \\
\cs{seahorse} & the rings & \\
\cs{royalgramma} & eye line and fin spot & the yellow half\\
\cs{lionfish} & the red bands & the white of the spines and rays\\
\cs{damselfish} & the bars & \\
\cs{shark} & the black fin tips & \\
\cs{corydoras} & the panda's mask and spots & \\
\cs{pleco} & & the pale spots\\
\cs{gourami} & bars (dwarf) or spots (blue) & the fin edges\\
\cs{zebradanio} & the stripes & \\
\midrule
\cs{snail} & stripes on the shell & the snail\\
\cs{starfish} & the chips & \\
\cs{shrimp} & the red back & the white stripe and antennae\\
\cs{hermitcrab} & stripes on the shell & the crab\\
\cs{jellyfish} & the horseshoes & the arms\\
\end{longtable}
\endgroup

The package defines these named colours, which you can use anywhere:

\begin{center}
\begin{tikzpicture}
  \foreach \c [count=\i from 0] in {finspupil,finsface,finsbone,finsboneline,finsflesh,finsskin,finsskinline,finssole,finsbubble,finsbubbleline,finshook,finsline,finsmouth,finslips,finstongue,finsheart,finsstar,finsstache,finsmask,finsstrap,finstube,finscrown,finscrownshade,finsparty,finstophat,finssoilA,finssoilB,finssoilC,finssoilD,finssoilE,finscoralA,finscoralB}{
    \pgfmathsetmacro\x{mod(\i,4)*4.05}
    \pgfmathsetmacro\y{-int(\i/4)*0.42}
    \filldraw[fill=\c, draw=black!40, line width=0.3pt, rounded corners=1pt]
      (\x,\y-0.14) rectangle ++(0.42,0.28);
    \node[anchor=west, font=\ttfamily\scriptsize] at (\x+0.5,\y) {\c};
  }
\end{tikzpicture}
\end{center}

\begin{center}
\begin{tikzpicture}
  \foreach \c [count=\i from 0] in {finscoralC,finscoralD,finscoralE,finswater,finswatertop,finsair,finsframe,finssand,finsgravelA,finsgravelB,finsgravelC,finsgravelD,finsgravelE,finsplant,finsplantlight,finsfern,finscabomba,finsludwigia,finsmoss,finsmosslight,finskelp,finskelplight,finsanemone,finsanemonetentacle,finsanemonetip,finsbrain,finsstaghorn,finsstaghorntip,finsstarfish,finsshell,finsshellrib,finswood}{
    \pgfmathsetmacro\x{mod(\i,4)*4.05}
    \pgfmathsetmacro\y{-int(\i/4)*0.42}
    \filldraw[fill=\c, draw=black!40, line width=0.3pt, rounded corners=1pt]
      (\x,\y-0.14) rectangle ++(0.42,0.28);
    \node[anchor=west, font=\ttfamily\scriptsize] at (\x+0.5,\y) {\c};
  }
\end{tikzpicture}
\end{center}

\begin{center}
\begin{tikzpicture}
  \foreach \c [count=\i from 0] in {finsrock,finspebbleA,finspebbleB,finspebbleC,finspebbleD,finschest,finsiron,finsgem,finscastle,finssnail,finssnailfoot,finsclown,finsclownbelly,finsclownblack,finstang,finstangbelly,finstangblack,finstangyellow,finsgoldfish,finsgoldfishbelly,finsgoldfishfin,finsyellowtang,finsyellowtangbelly,finsyellowtangfin,finsangel,finsangelbar,finsangelfin,finsidol,finsidolyellow,finsidolblack,finsidolsnout,finsbetta}{
    \pgfmathsetmacro\x{mod(\i,4)*4.05}
    \pgfmathsetmacro\y{-int(\i/4)*0.42}
    \filldraw[fill=\c, draw=black!40, line width=0.3pt, rounded corners=1pt]
      (\x,\y-0.14) rectangle ++(0.42,0.28);
    \node[anchor=west, font=\ttfamily\scriptsize] at (\x+0.5,\y) {\c};
  }
\end{tikzpicture}
\end{center}

\begin{center}
\begin{tikzpicture}
  \foreach \c [count=\i from 0] in {finsbettabelly,finsbettafin,finsbettaedge,finsguppy,finsguppybelly,finsguppytail,finsguppyspot,finsguppyblue,finstetra,finstetraback,finstetrablue,finstetraglow,finstetrared,finssword,finsswordbelly,finsswordfin,finsswordyellow,finsdiscus,finsdiscusbelly,finsdiscusline,finsbarb,finsbarbbelly,finsbarbblack,finsbarbred,finspuffer,finspufferbelly,finspufferspot,finspufferfin,finsseahorse,finsseahorsebelly,finsgramma,finsgrammabelly}{
    \pgfmathsetmacro\x{mod(\i,4)*4.05}
    \pgfmathsetmacro\y{-int(\i/4)*0.42}
    \filldraw[fill=\c, draw=black!40, line width=0.3pt, rounded corners=1pt]
      (\x,\y-0.14) rectangle ++(0.42,0.28);
    \node[anchor=west, font=\ttfamily\scriptsize] at (\x+0.5,\y) {\c};
  }
\end{tikzpicture}
\end{center}

\begin{center}
\begin{tikzpicture}
  \foreach \c [count=\i from 0] in {finsgrammayellow,finscory,finscorybelly,finscoryfin,finscoryiris,finscorybronze,finscorybronzebelly,finscorybronzefin,finspleco,finsplecobelly,finsplecospot,finsgourami,finsgouramibelly,finsgouramifin,finsgouramiedge,finsgouramiblue,finsbluegourami,finsbluegouramibelly,finsbluegouramispot,finsbluegouramiedge,finsdanio,finsdaniobelly,finsdaniostripe,finslion,finslionred,finsdamsel,finsdamselblack,finsshark,finssharkbelly,finssharktip,finsmystery,finsmysteryband}{
    \pgfmathsetmacro\x{mod(\i,4)*4.05}
    \pgfmathsetmacro\y{-int(\i/4)*0.42}
    \filldraw[fill=\c, draw=black!40, line width=0.3pt, rounded corners=1pt]
      (\x,\y-0.14) rectangle ++(0.42,0.28);
    \node[anchor=west, font=\ttfamily\scriptsize] at (\x+0.5,\y) {\c};
  }
\end{tikzpicture}
\end{center}

\begin{center}
\begin{tikzpicture}
  \foreach \c [count=\i from 0] in {finsnerite,finsneritestripe,finsneritefoot,finsramshorn,finsramshornfoot,finschocstar,finschocchip,finslinckia,finsshrimp,finsshrimpred,finshermitshell,finshermitband,finshermit,finsjelly,finsjellypink}{
    \pgfmathsetmacro\x{mod(\i,4)*4.05}
    \pgfmathsetmacro\y{-int(\i/4)*0.42}
    \filldraw[fill=\c, draw=black!40, line width=0.3pt, rounded corners=1pt]
      (\x,\y-0.14) rectangle ++(0.42,0.28);
    \node[anchor=west, font=\ttfamily\scriptsize] at (\x+0.5,\y) {\c};
  }
\end{tikzpicture}
\end{center}

% =========================================================================
\section{Key reference}

\begingroup
\small
\renewcommand\arraystretch{1.2}
\begin{longtable}{@{}>{\ttfamily\raggedright}p{0.21\linewidth}>{\raggedright}p{0.27\linewidth}>{\raggedright\arraybackslash}p{0.45\linewidth}@{}}
\toprule
\normalfont\bfseries Key & \bfseries Values (default) & \bfseries Notes\\
\midrule
\endhead
\bottomrule
\endfoot
\multicolumn{3}{@{}l}{\itshape Every fish and component}\\
at & coordinate (\texttt{(0,0)}) & Centre of a fish; base of a component.\\
scale & number (1) & Also scales line widths.\\
facing & \texttt{right}, \texttt{left} (\texttt{right}) & Mirrors it.\\
rotate & angle (0) & \\
body & colour & Main colour; sets \texttt{belly} and \texttt{outline}.\\
belly, outline & colour & \\
pattern, accent & colour & See the table in the colours section.\\
seed & integer (1) & A different random arrangement.\\
\midrule
\multicolumn{3}{@{}l}{\itshape Fish}\\
tail & angle (0) & Swings the tail fin.\\
belly up & \texttt{true}, \texttt{false} (\texttt{false}) & Upside down.\\
eye & name (\texttt{normal}) & See section~\ref{sec:faces}.\\
eye scale & number (1) & \\
mouth & name (\texttt{default}) & See section~\ref{sec:faces}; \texttt{chomp} opens the jaws.\\
gape & angle (110) & How wide \texttt{mouth=chomp} opens.\\
fin, iris, back & colour & \\
fin opacity & number (0.92) & Some fish have more see-through fins.\\
back opacity & number (0.14) & Shading along the back.\\
inside & colour & The bitten edge.\\
bones & 0--3 (0) & Plain \texttt{bones} means 1.\\
speed, sweat & \texttt{true}, \texttt{false} (\texttt{false}) & Speed lines; drops of sweat.\\
legs & \texttt{true}, \texttt{false} (\texttt{false}) & \\
hooked & \texttt{true}, \texttt{false} (\texttt{false}) & \\
line length & number (4) & Length of the fishing line.\\
bubbles & number (0) & Plain \texttt{bubbles} means 3.\\
says, thinks & text (empty) & Maths and \verb|\\| allowed.\\
hat & \texttt{crown}, \texttt{party}, \texttt{top}, \texttt{pirate},
  \texttt{none} (\texttt{none}) & \\
snorkel, moustache & \texttt{true}, \texttt{false} (\texttt{false}) & \\
school & number (1) & Number of fish in the school.\\
school spread & number (1) & \\
scales & \texttt{true}, \texttt{false} & Scale texture; on for the goldfish and betta.\\
puffed & \texttt{true}, \texttt{false} (\texttt{false}) & \cs{pufferfish} only.\\
type & name & \cs{corydoras}: \texttt{panda}, \texttt{bronze}. \cs{gourami}:
  \texttt{dwarf}, \texttt{blue}. \cs{snail}: \texttt{mystery}, \texttt{nerite},
  \texttt{ramshorn}. \cs{starfish}: \texttt{common}, \texttt{chocolatechip},
  \texttt{linckia}.\\
stripes & 3, 4 (3) & \cs{damselfish}.\\
arms & number (5) & \cs{starfish}.\\
face & \texttt{none}, \texttt{happy}, \texttt{sleepy} (\texttt{none}) & \cs{starfish}, \cs{jellyfish}.\\
\midrule
\multicolumn{3}{@{}l}{\itshape Components}\\
height, width & number & Size of plants, coral and bubble columns.\\
count & number & Blades, stems, leaves, tentacles, pebbles or branchings.\\
sway & angle (0) & Plants and anemones lean with the current.\\
variant & 1, 2, 3 (1) & \cs{rock}.\\
moss & \texttt{true}, \texttt{false} (\texttt{false}) & \cs{rock}.\\
radius & number & \cs{mossball}.\\
face & \texttt{none}, \texttt{happy}, \texttt{sleepy} (\texttt{none}) & \cs{mossball}.\\
open & \texttt{true}, \texttt{false} (\texttt{true}) & \cs{treasurechest}.\\
bubbles & number (0) & \cs{treasurechest}.\\
\midrule
\multicolumn{3}{@{}l}{\itshape Environments}\\
width, height & number (14, 8) & \texttt{aquarium}.\\
radius & number (1.8) & \texttt{fishbowl}.\\
water & colour & \\
water level & fraction (0.88; 0.82 for a bowl) & \\
substrate & \texttt{sand}, \texttt{gravel}, \texttt{soil}, \texttt{pebbles},
  \texttt{coral}, \texttt{none} (\texttt{sand}) & The bowl's default is \texttt{gravel}.\\
substrate height & number (1) & \texttt{aquarium}.\\
sand, frame & colour & \texttt{aquarium}.\\
light rays, backdrop, glass & \texttt{true}, \texttt{false} (\texttt{true}) & \texttt{aquarium}.\\
\end{longtable}
\endgroup

% =========================================================================
\section{Tips}

\begin{description}[style=nextline, leftmargin=1.6em]
  \item[Order matters] Ti\emph{k}Z draws in order, so draw the back of a tank
    first: tall plants and rocks at the back, then the middle ground, then
    fish, then anything in front. A clownfish placed after its anemone swims
    in front of it.
  \item[Scaling the whole picture] The package's \key{scale} key scales line
    widths with the drawing. If you scale a whole picture with Ti\emph{k}Z's
    own \key{scale} instead, the lines keep their width. For small figures,
    prefer the package key.
  \item[Compile time] A busy aquarium has a lot of small paths: a full tank
    like the one on the title page takes a few seconds. Granular substrates,
    schools and the feathery \cs{cabomba} cost the most, so while you arrange
    things, try sand and smaller schools, or externalise finished pictures.
  \item[Errors] A misspelled eye, mouth or hat stops with an error message
    that lists the valid choices.
\end{description}

% =========================================================================
\section{Change history}

\begin{description}[style=nextline, leftmargin=1.6em]
  \item[v0.3 (2026/11/04)] \texttt{mouth=chomp} now opens the fish's own head
    into toothed jaws, with a new key \texttt{gape}; full licence notices.
  \item[v0.2 (2026/10/26)] Seven new fish and five invertebrates; a truer
    moorish idol, clownfish, angelfish, blue tang and tiger barb; mouths
    \texttt{chomp} and \texttt{fangs}; keys \texttt{speed} and \texttt{sweat};
    substrates \texttt{soil}, \texttt{pebbles} and \texttt{coral}; faster
    gravel.
  \item[v0.1 (2026/10/25)] First draft: 15 fish, 12 eyes, 8 mouths, bones, legs,
    hooks, bubbles, speech, hats, snorkels, schools, 20 aquarium components and
    the \texttt{aquarium} and \texttt{fishbowl} environments.
\end{description}

% =========================================================================
\section{Licence and thanks}

Copyright \copyright\ 2026 \pkgauthor.

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} and version 1.3c or later is part
of all distributions of \LaTeX\ version 2008 or later.

This work has the LPPL maintenance status ``maintained''. The Current
Maintainer of this work is \pkgauthor.

This work consists of the files \texttt{tikzfins.sty}, \texttt{tikzfins-doc.tex}
and \texttt{README.md}, and the derived file \texttt{tikzfins-doc.pdf}.

All drawings in this work are original. They were made from scratch with
Ti\emph{k}Z paths for this package; none is traced from or based on a
photograph or on anyone else's artwork. The animals they show are real species,
named by their common names.

Many thanks to samcarter for \pkg{tikzducks} and \pkg{tikzlings}, to Florian
Sihler for \pkg{tikzpingus}, and to Till Tantau and the PGF team for
Ti\emph{k}Z itself.

\end{document}