% eigo.tex - Documentation for the eigo package
\documentclass[a4paper,11pt]{article}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{xcolor}
\usepackage{array}
\usepackage{longtable}
\usepackage{booktabs}
\usepackage{geometry}
\geometry{margin=2.5cm}
\usepackage{doc}

% Load the eigo package
\usepackage[color,frame,coords]{eigo}

% Metadata
\title{The \textsf{eigo} Package\\
{\large Enhanced Go Diagrams for \LaTeX}}
\author{Marc Levivier\\
{\small (developed with AI assistance)}}
\date{Version 1.0 -- \today}

% Custom commands for documentation - check if they exist first
\providecommand{\cs}[1]{\texttt{\textbackslash#1}}
\providecommand{\pkg}[1]{\textsf{#1}}
\providecommand{\opt}[1]{\texttt{#1}}
\providecommand{\meta}[1]{\textit{#1}}

\begin{document}

\maketitle

\begin{abstract}
The \pkg{eigo} package provides comprehensive tools for creating professional Go (Weiqi/Baduk) game diagrams in \LaTeX\ documents. It offers enhanced features including multiple customizable stone colors, automatic numbering systems, geometric transformations, flexible board display options with enhanced borders, and full LuaLaTeX compatibility.
\end{abstract}

\tableofcontents

\section{Introduction}

Go is an ancient board game played on a grid of lines. Creating clear, professional diagrams for Go positions is essential for books, articles, and educational materials. The \pkg{eigo} package (Enhanced Igo) provides a modern, feature-rich solution for typesetting Go diagrams in \LaTeX.

\subsection{Features}

\begin{itemize}
\item Full and partial board displays with automatic zone detection and enhanced borders
\item Multiple stone colors (black, white, red, blue, green) with full customization
\item Two additional custom colors (customone, customtwo) with dedicated commands
\item Stone numbering with flexible automatic sequences
\item Symbol placement (geometric shapes and custom text)
\item Geometric transformations (rotations, mirrors, color swapping)
\item Flexible sizing from tiny to massive boards with validation
\item Coordinate display with customizable formatting
\item Multiple board support for variations
\item LuaLaTeX compatibility with proper UTF-8 handling
\item Enhanced border display for complete board diagrams
\end{itemize}

\subsection{Requirements}

\begin{itemize}
\item Modern \LaTeX\ distribution (TeX Live 2020+ recommended)
\item TikZ package (for graphics)
\item xcolor package (for colors)
\item Optional: LuaLaTeX for best UTF-8 support
\end{itemize}

\section{Package Options}

The \pkg{eigo} package accepts several options to customize its behavior:

\begin{longtable}{ll}
\toprule
\textbf{Option} & \textbf{Description} \\
\midrule
\opt{color} & Enable colored stones and backgrounds (default) \\
\opt{bw} & Black and white mode only \\
\opt{frame} & Show board frame and background with enhanced borders \\
\opt{noframe} & Hide board frame and background (default) \\
\opt{coords} & Show coordinate labels \\
\opt{nocoords} & Hide coordinate labels (default) \\
\opt{debug} & Enable debug output \\
\bottomrule
\end{longtable}

Example usage:
\begin{verbatim}
\usepackage[frame,coords]{eigo}
\end{verbatim}

\section{Basic Usage}

\subsection{Board Setup}

The default board size is 19×19, but you can change it:

\begin{verbatim}
\gobansize{19}  % Standard board
\gobansize{13}  % Smaller board
\gobansize{9}   % Beginner board
\end{verbatim}

\subsection{Placing Stones}

Basic stone placement uses coordinate notation (letter + number):

\begin{verbatim}
\blackstones{d4,k10,q16}
\whitestones{d16,k4,q4}
\end{verbatim}

\cleargoban
\blackstones{d4,k10,q16}
\whitestones{d16,k4,q4}

\begin{center}
\showgoban[a1,s10]
\end{center}

\subsection{Displaying Boards}

Show the complete board with enhanced borders:
\begin{verbatim}
\showfullgoban
\end{verbatim}

Show a specific zone:
\begin{verbatim}
\showgoban[c3,m11]    % Rectangle from c3 to m11
\showgoban[k10]       % 5x5 area around k10
\end{verbatim}

\section{Stone Colors and Customization}

\subsection{Available Colors}

The package supports seven stone colors:
\begin{itemize}
\item \cs{blackstones}\{positions\}
\item \cs{whitestones}\{positions\}
\item \cs{redstones}\{positions\}
\item \cs{bluestones}\{positions\}
\item \cs{greenstones}\{positions\}
\item \cs{customonestones}\{positions\} -- Custom color 1 (default: purple)
\item \cs{customtwostones}\{positions\} -- Custom color 2 (default: orange)
\end{itemize}

\subsection{Color Customization}

You can customize all stone colors using RGB values:

\begin{verbatim}
\eigoblackcolor{0,0,0}          % Standard black
\eigowhitecolor{255,255,255}    % Standard white
\eigoredcolor{200,0,0}          % Dark red
\eigobluecolor{0,0,200}         % Dark blue
\eigogreencolor{0,150,0}        % Dark green
\eigocustomonecolor{128,0,128}  % Purple (default)
\eigocustomtwocolor{255,165,0}  % Orange (default)
\end{verbatim}

Example with custom colors:
\begin{verbatim}
\eigocustomonecolor{255,0,255}  % Bright magenta
\eigocustomtwocolor{0,255,255}  % Cyan
\customonestones{d4,d5}
\customtwostones{e4,e5}
\end{verbatim}

\cleargoban
\eigocustomonecolor{255,0,255}
\eigocustomtwocolor{0,255,255}
\customonestones{d4,d5}
\customtwostones{e4,e5}

\begin{center}
\showgoban[c3,f6]
\end{center}

\subsection{Manual Numbering}

Add numbers to stones using optional parameter:

\begin{verbatim}
\blackstones[1]{d4}
\whitestones[2]{d5}
\blackstones[3]{e4}
\end{verbatim}

\cleargoban
\blackstones[1]{d4}
\whitestones[2]{d5}
\blackstones[3]{e4}

\begin{center}
\showgoban[d4]
\end{center}

\subsection{Automatic Numbering}

\subsubsection{Alternating Colors}

\cs{autoblackfirst}[n]\{positions\} starts with black stone numbered n, then alternates:

\begin{verbatim}
\autoblackfirst[1]{d4,d5,e4,e5,f4}
\end{verbatim}

\cleargoban
\autoblackfirst[1]{d4,d5,e4,e5,f4}

\begin{center}
\showgoban[d4]
\end{center}

The automatic numbering system supports skipping positions by using dashes:
\begin{verbatim}
\autoblackfirst[1]{d4,-,e4,e5}  % Skip d5, continues numbering
\end{verbatim}

\cleargoban
\autoblackfirst[1]{d4,-,e4,e5}

\begin{center}
\showgoban[d4]
\end{center}

\subsubsection{Monochrome Sequences}

For same-color sequences with increment of 2:

\begin{verbatim}
\blackn[1]{d4,e4,f4}      % Numbers: 1,3,5
\whiten[2]{d5,e5,f5}      % Numbers: 2,4,6
\end{verbatim}

\cleargoban
\blackn[1]{d4,e4,f4}
\whiten[2]{d5,e5,f5}

\begin{center}
\showgoban[d4]
\end{center}

\section{Symbols and Markup}

\subsection{Geometric Symbols}

Place symbols on empty intersections:

\begin{verbatim}
\gobansymbol{d4,k10}{\eigotriangle}
\gobansymbol{d16,k4}{\eigosquare}
\gobansymbol{q4,q16}{\eigocircle}
\gobansymbol{k16}{\eigocross}
\end{verbatim}

Available symbols:
\begin{itemize}
\item \cs{eigotriangle} -- Triangle
\item \cs{eigosquare} -- Square  
\item \cs{eigocircle} -- Circle
\item \cs{eigocross} -- Cross
\end{itemize}

\cleargoban
\gobansymbol{d4,k10}{\eigotriangle}
\gobansymbol{d16,k4}{\eigosquare}
\gobansymbol{q4,q16}{\eigocircle}
\gobansymbol{k16}{\eigocross}

\begin{center}
\showgoban[a1,s19]
\end{center}

\subsection{Text Labels}

Use custom text as symbols:
\begin{verbatim}
\gobansymbol{d4,e5}{A}
\gobansymbol{k10}{X}
\end{verbatim}

\section{Board Transformations}

\subsection{Rotations}

Rotate the current board position:

\begin{verbatim}
\eigorotate{90}   % 90 degrees clockwise
\eigorotate{180}  % 180 degrees  
\eigorotate{270}  % 270 degrees clockwise
\end{verbatim}

\subsection{Mirrors}

Mirror the board along different axes:

\begin{verbatim}
\eigomirrorh       % Horizontal mirror
\eigomirrorv       % Vertical mirror  
\eigomirrordiag    % Diagonal mirror
\end{verbatim}

\subsection{Color Operations}

\begin{verbatim}
\eigoswapcolors    % Swap black and white stones
\end{verbatim}

\subsection{Example: Transformation Chain}

\cleargoban
\blackstones{d4,k10}
\whitestones{k4,d10}

Original position:
\begin{center}
\showgoban[a1,n11]
\end{center}

\eigorotate{90}

After 90° rotation:
\begin{center}
\showgoban[a1,n11]
\end{center}

\section{Board Sizing}

\subsection{Predefined Sizes}

\textbf{ENHANCED:} Extended range of predefined sizes with validation:

\begin{verbatim}
\tinygoban        % 4mm per intersection
\smallgoban       % 6mm per intersection  
\normalgoban      % 8mm per intersection (default)
\largegoban       % 12mm per intersection
\hugegoban        % 16mm per intersection
\massivegoban     % 20mm per intersection
\end{verbatim}

\subsection{Custom Sizing with Validation}

Set exact unit size with automatic validation:
\begin{verbatim}
\eigounitsize{10mm}
\end{verbatim}

The package will issue warnings for very small (<2mm) or very large (>20mm) unit sizes.

Get current size information:
\begin{verbatim}
Current unit size: \theeigountisize
Size information: \eigosizeinfo
\end{verbatim}

Current unit size: \theeigountisize

\eigosizeinfo

\section{Multiple Boards}

Work with multiple board positions simultaneously:

\begin{verbatim}
\usegoban{1}
\blackstones{d4,k10}

\usegoban{2}  
\blackstones{d4,k10,q16}
\whitestones{d16}

\usegoban{1}  % Switch back to board 1
\showgoban[d4]

\usegoban{2}  % Switch to board 2  
\showgoban[d4]
\end{verbatim}

Current board number: \theeigobnum

\section{Complete Feature Overview}

\subsection{All Stone Colors with Numbering}

\begin{verbatim}
\cleargoban
\blackstones[1]{d4}
\whitestones[2]{e4}
\redstones[3]{f4}
\bluestones[4]{g4}
\greenstones[5]{h4}
\customonestones[6]{j4}
\customtwostones[7]{k4}
\gobansymbol{d5,e5,f5,g5}{\eigotriangle}
\gobansymbol{h5,j5,k5}{\eigosquare}
\end{verbatim}

\cleargoban
\blackstones[1]{d4}
\whitestones[2]{e4}
\redstones[3]{f4}
\bluestones[4]{g4}
\greenstones[5]{h4}
\customonestones[6]{j4}
\customtwostones[7]{k4}
\gobansymbol{d5,e5,f5,g5}{\eigotriangle}
\gobansymbol{h5,j5,k5}{\eigosquare}

\begin{center}
\showgoban[c3,l7]
\end{center}

This example demonstrates all seven stone colors with numbering and symbols.

\subsection{Size and Frame Combinations}

\subsubsection{Small + Frame}

\cleargoban
\smallgoban
\eigoframe
\blackstones{d4,k10}
\whitestones{k4,d10}

\begin{center}
\showfullgoban
\end{center}

\subsubsection{Large + No Frame}

\cleargoban
\largegoban
\eigonoframe
\blackstones{d4,k10}
\whitestones{k4,d10}

\begin{center}
\showgoban[c3,l11]
\end{center}

\normalgoban  % Reset to normal
\eigonoframe  % Reset frame

\section{Coordinate System}

\subsection{Position Format}

Positions use standard Go notation:
\begin{itemize}
\item Columns: a--t (skipping 'i')  
\item Rows: 1--19 (or board size)
\item Examples: \texttt{d4}, \texttt{k10}, \texttt{q16}
\end{itemize}

\subsection{Coordinate Display}

Enable coordinates with package option or commands:
\begin{verbatim}
\eigocoords        % Enable coordinate display
\eigonocoords      % Disable coordinate display
\end{verbatim}

Customize coordinate appearance:
\begin{verbatim}
\eigocoordscale{0.8}      % Scale factor
\eigocoorddistance{0.7}   % Distance from board
\end{verbatim}

\section{Enhanced Board Display}

\subsection{Border Enhancement}

Complete board diagrams feature enhanced borders for better visual definition:

\begin{verbatim}
\eigoframe         % Enable enhanced frame display
\eigonoframe       % Disable frame display
\end{verbatim}

When frame display is enabled, complete boards show:
\begin{itemize}
\item Thick border (2pt width) around the entire board
\item Colored background in color mode
\item Professional appearance suitable for publication
\end{itemize}

\subsection{Frame vs No-Frame Comparison}

\cleargoban
\blackstones{d4,q16}
\whitestones{d16,q4}

No frame (partial view):
\begin{center}
\eigonoframe
\showgoban[a1,s10]
\end{center}

With enhanced frame (same area):
\begin{center}
\eigoframe
\showgoban[a1,s19]
\end{center}

\section{Board Management}

\subsection{Clearing Positions}

Clear entire board:
\begin{verbatim}
\cleargoban
\end{verbatim}

Clear specific zone:
\begin{verbatim}
\cleargoban[d4,k10]  % Clear rectangle
\cleargoban[k10]     % Clear 5x5 around k10
\end{verbatim}

Clear specific positions:
\begin{verbatim}
\eigoclear{d4,e5,k10}
\end{verbatim}

\subsection{Information Commands}

Get board information:
\begin{verbatim}
Board size: \theeigobsize
Current board: \theeigobnum  
Unit size: \theeigountisize
\end{verbatim}

Board size: \theeigobsize, Current board: \theeigobnum

\section{Advanced Examples}

\subsection{Game Sequence with Custom Colors}

\begin{verbatim}
\cleargoban
\gobansize{19}
\normalgoban

% Customize colors for this example
\eigoblackcolor{50,50,50}      % Dark gray instead of black
\eigoredcolor{180,0,0}         % Deep red

% Opening moves
\blackstones{d4,q16}
\whitestones{d16,q4}

% Approach and response with custom color
\redstones[1]{k4}
\autoblackfirst[2]{k3,k5}

\showgoban[h1,n7]
\end{verbatim}

\cleargoban
\eigoblackcolor{50,50,50}
\eigoredcolor{180,0,0}
\blackstones{d4,q16}
\whitestones{d16,q4}
\redstones[1]{k4}
\autoblackfirst[2]{k3,k5}

\begin{center}
\showgoban[h1,n7]
\end{center}

\subsection{Problem Diagram with Enhanced Display}

\begin{verbatim}
\cleargoban
\eigoframe  % Enable enhanced borders
\blackstones{f3,g3,h3,g4,h4,g5}
\whitestones{f4,f5,g6,h5,h6}
\gobansymbol{f6}{A}
\gobansymbol{h7}{B}

\showgoban[e2,j8]
\end{verbatim}

\cleargoban
\eigoframe
\blackstones{f3,g3,h3,g4,h4,g5}
\whitestones{f4,f5,g6,h5,h6}
\gobansymbol{f6}{A}
\gobansymbol{h7}{B}

\begin{center}
\showgoban[e2,j8]
\end{center}

\subsection{Variation Analysis with Custom Stone Colors}

Using multiple boards and custom colors for clear differentiation:

\begin{verbatim}
% Main line
\usegoban{1}
\eigocustomonecolor{0,100,0}    % Dark green
\blackstones{d4,k10}
\whitestones{d10,k4}
\customonestones[1]{k16}        % Main line move

% Variation  
\usegoban{2}
\eigocustomtwocolor{100,0,100}  % Dark purple  
\blackstones{d4,k10}
\whitestones{d10,k4}
\customtwostones[1]{q4}         % Variation move
\end{verbatim}

\section{Package Implementation}

\subsection{Internal Storage}

The package uses a sophisticated storage system to handle:
\begin{itemize}
\item Stone colors and positions with full customization support
\item Stone numbers  
\item Symbols and markup
\item Multiple board states with independent color settings
\end{itemize}

\subsection{Enhanced Border System}

The enhanced border system provides:
\begin{itemize}
\item Configurable border width (\cs{eigo@border@width}, default 2pt)
\item Automatic detection of full vs partial board display
\item Smart background color management based on frame and color options
\item Professional appearance for publication-quality diagrams
\end{itemize}

\subsection{Color Management}

The color system includes:
\begin{itemize}
\item Seven distinct stone colors with full RGB customization
\item Dynamic color redefinition during document processing
\item Color mode switching (color/bw) with proper fallbacks
\item Default color palettes optimized for readability
\end{itemize}

\subsection{LuaLaTeX Compatibility}

The package includes enhanced LuaLaTeX support:
\begin{itemize}
\item UTF-8 character definitions with \cs{newunicodechar}
\item Proper font encoding detection and handling
\item Compatibility with luatex85 for older LuaTeX versions
\item Robust handling of special characters in all engines
\end{itemize}

\section{Troubleshooting}

\subsection{Common Issues}

\textbf{Stones not appearing:} Check position notation (no 'i' in columns).

\textbf{Colors not changing:} Ensure color commands are called before stone placement.

\textbf{Board too large/small:} Use size commands or \cs{eigounitsize} with validation.

\textbf{Borders not showing:} Enable frame mode with \cs{eigoframe} and use full board display.

\textbf{Custom colors reverting:} Color changes affect subsequent stone placements only.

\textbf{UTF-8 errors:} Use LuaLaTeX for best compatibility or ensure proper input encoding.

\subsection{Debug Mode}

Enable debug output for troubleshooting:
\begin{verbatim}
\usepackage[debug]{eigo}
\end{verbatim}

This provides detailed console output about:
\begin{itemize}
\item Position parsing and validation
\item Board operations and transformations
\item Color definitions and changes
\item Size validation warnings
\item Zone detection and rendering
\end{itemize}

\section{Comparison with Other Packages}

\begin{longtable}{p{2cm}p{5cm}p{7cm}}
\toprule
\textbf{Package} & \textbf{Features} & \textbf{Advantages of eigo} \\
\midrule
igo & Black \& White Go diagrams & Multiple customizable colors, enhanced borders \\
\bottomrule
\end{longtable}

\section{License and Acknowledgments}

The \pkg{eigo} package is released under the \LaTeX\ Project Public License v1.3c or later.

Inspired by the \pkg{igo} package and enhanced with modern \LaTeX\ techniques and comprehensive Go diagram requirements for professional publication.

\textbf{Development note:} This package was developed by Marc Levivier with AI assistance for code generation, documentation, and testing. The design decisions, feature requirements, and final implementation remain under human authorship.

\section{Version History}

\begin{description}
\item[v1.0 (2025-09-06)] Complete feature set with enhanced borders, full color customization, extended size options, improved LuaLaTeX support, and comprehensive validation
\end{description}

\end{document}