%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -*- Mode: Latex -*- %%%%%%%%%%%%%%%%%%%%%%%%%%
%% doc-poly.tex --- Documentation for `pst-poly' PSTricks package
%%
%% Author          : Denis GIROU (CNRS/IDRIS - France) <Denis.Girou@idris.fr>
%% Created the     : Wed Jun 11 18:50:04 1997
%% Last mod. by    : Denis GIROU (CNRS/IDRIS - France) <Denis.Girou@idris.fr>
%% Last mod. the   : Fri Jul 10 10:48:57 1998
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% If there is not `ctandir' installed (from `ltugboat' package)
\begin{filecontents}{ctandir.sty}
%% LaTeX2e file `ctandir.sty'
%% generated by the `filecontents' environment
%% from source `ltubguid' on 1997/06/12.
%%
%
% Experimental CTAN location information macros for use with Donald
% Arseneau's |url.sty|
%
% we need url.sty; we can rely on it to demand anything it needs of
% LaTeX
\IfFileExists{url.sty}%
  {\RequirePackage{url}}%
  {\PackageWarning{ctandir}{You should acquire a copy of url.sty}%
   \newcommand\urldef[3]{\def#1{\texttt{#3}}}%
   \let\url\texttt
  }
%
\newcommand\CTANdirectory[1]{\expandafter\urldef
  \csname CTAN@#1\endcsname\path}
\newcommand\CTANfile[1]{\expandafter\urldef
  \csname CTAN@#1\endcsname\path}
%
% Use the standard label-referencing mechanism to get the warning for
% an undefined label
\newcommand\CTANref[1]{\expandafter\@setref\csname CTAN@#1\endcsname
  \relax{#1}}
\end{filecontents}

\documentclass{article}

\usepackage{pstcol}                % PSTricks with the `color' extension
\usepackage{pst-poly}              % PSTricks package for polygons
\usepackage{multido}               % `multido' package
\usepackage{url}                   % `url' package
\usepackage{ctandir}               % For CTAN references
\usepackage[baw,pstricks]{fvrb-ex} % Example environments with `fancyvrb'

\fvset{numbers=left,frame=single}  % Example environments with numbers and frame

\textheight=25cm
\topmargin=-2.5cm
\addtolength{\textwidth}{5mm}

% Aligned labels in a description environment
\newenvironment{Description}[1]{%
\begin{list}{nothing}{\setlength{\leftmargin}{#1}
\setlength{\labelwidth}{\leftmargin}\setlength{\labelsep}{1mm}}}
{\end{list}}

% For macro names
\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}

% Name macros
\newcommand{\PolyPackage}{\textbf{`pst-poly'}}
\newcommand{\PstPoly}{\cs{PstPolygon}}
\newcommand{\PstPolyNode}{\cs{PstPolygonNode}}
\newcommand{\XYpic}{%
\leavevmode\hbox{\kern-.1em X\kern-.3em\lower.4ex\hbox{Y\kern-.15em}-pic}}

% Define CTAN addresses using the commands of the |ctandir| package
\CTANdirectory{pstricks}{graphics/pstricks}
\CTANdirectory{xypic}{macros/generic/diagrams/xypic}

% From ltugboat.cls
% For references
\makeatletter
\newcommand\acro[1]{\textsc{#1}\@}
\def\CTAN{\acro{CTAN}}
\let\texttub\textsl              % redefined in other situations
\def\TUB{\texttub{TUGboat}}
\def\TUG{\TeX\ \UG}
\def\tug{\acro{TUG}}
\def\UG{Users Group}
% For the bibliography 
\let\@internalcite\cite
\def\cite{\def\@citeseppen{-1000}%
    \def\@cite##1##2{(##1\if@tempswa , ##2\fi)}%
    \def\citeauthoryear##1##2##3{##1, ##3}\@internalcite}
\def\etal{et\,al.\@}
\makeatother

\begin{document}

\title{\PolyPackage\\A PSTricks package for polygons}
\author{Denis \textsc{Girou}\thanks{CNRS/IDRIS --- Centre National de la
Recherche Scientifique / Institut du D\'eveloppement et des Ressources en
Informatique Scientifique --- Orsay --- France ---
\mbox{\texttt{<Denis.Girou@idris.fr>}}.}}

\date{\shortstack{July 9, 1998 --- Version 1.4\\
                  {\small Documentation revised July 10, 1998}}}
\maketitle

\begin{center}
\psframebox[framearc=0.3,framesep=5mm,linewidth=0.7mm]{%
  \parbox{11cm}{%
  {\Large\textbf{Abstract}}: \PolyPackage{} is a PSTricks
  \cite{vanZandt:PSTricks:1993}, \cite{Girou:PSTricks:1994},
  \cite{vanZandtGirou:TB15-3-239}, \cite{LGC:1997},
  \cite{Hoenig:TU:1998} package to draw easily various kinds of polygons,
  using the macro \PstPoly.

  \hspace{5mm} It is also a good example of the great power and flexibility of
  PSTricks, as in fact it is a very short program (it body is only 100~lines
  long) but nevertheless really powerful.

  \hspace{5mm} And last, it is also a good pedagogical example of how to design
  and program \emph{high level objects} above PSTricks own ones.
}}
\end{center}

\section{Introduction}
  \PolyPackage{} offer a unique macro (plus some aliases to define some often
used polygons) with few parameters to interact on it. But we can also use all
the relevant PSTricks parameters to change the size, the characteristics of
lines, to add filling, etc.

  The polygons are always drawn counter clockwise.

  The syntax is simply: \fbox{\PstPoly\texttt{*[optional\_parameters]}}

  As for PSTricks closed objects, the \texttt{*} version use a solid style to
fill the polygon, use the line color for fill color and set the linewidth to 0.

  A preliminary version, limited to \emph{regular} polygons, was shown at
TUG'95 conference, St Petersburg, Florida, as part of my talk \emph{Building
high level objects in PSTricks} \cite{Girou:PSTricks:1995}.

  As parameters are managed by `keyval' mechanism (from David
\textsc{Carlisle}), it use a special interface between the `keyval' package
and PSTricks, done by David \textsc{Carlisle} who rewrite (better!) my
original version.

  \emph{Note}: You can take advantage to look also at the polygon feature of
the \XYpic{} package \cite{RoseMoore:XYpic:1998}, \cite{LGC:1997}.

\section{Usage}

\subsection{Parameters}

  There are \textbf{eight} specific parameters defined to change the way the
polygons are defined:

\begin{Description}{2cm}
  \item [\HLTTc{PstPicture} (boolean)\hfill :] to define or not a
  \texttt{pspicture} environment for the polygon. We have to define this
  parameter to \emph{false} if we want to mix the polygon with other PSTricks
  objects --- see examples later (\emph{Default:~true --- which is not the
  case for basic PSTricks objects}).
\end{Description}

\begin{Description}{2cm}
  \item [\HLTTc{PolyRotation} (real)\hfill :] rotation angle applied to the
  polygon (\emph{Default:~0 --- no rotation}).
\end{Description}

\begin{CenterExample}
  \PstPolygon\hfill
  \PstPolygon[§HLeµPolyRotation¶=§HLCBWzµ18¶]\hfill
  \PstPolygon[§HLeµPolyRotation¶=§HLCBWzµ36¶]\hfill
  \PstPolygon[§HLeµPolyRotation¶=§HLCBWzµ45¶]
\end{CenterExample}

\begin{Description}{2cm}
  \item [\HLTTc{PolyNbSides} (integer)\hfill :] number of sides of the
  polygon (\emph{Default:~5}).
\end{Description}

\begin{CenterExample}
  \PstPolygon
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ3¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ4¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ5¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ8¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ50¶]
\end{CenterExample}

\begin{Description}{2cm}
  \item [\HLTTc{PolyOffset} (integer)\hfill :] number of nodes to bypass to
  obtain each time the next one (\emph{Default:~1} --- no node bypassed).
\end{Description}

\begin{CenterExample}
  \PstPolygon
  \PstPolygon[§HLeµPolyOffset¶=§HLCBWzµ2¶]
  \PstPolygon[§HLeµPolyOffset¶=§HLCBWzµ3¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ7¶,§HLeµPolyOffset¶=§HLCBWzµ2¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ9¶,§HLeµPolyOffset¶=§HLCBWzµ4¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ17¶,§HLeµPolyOffset¶=§HLCBWzµ6¶]
\end{CenterExample}

\begin{Description}{2cm}
  \item [\HLTTc{PolyIntermediatePoint} (real)\hfill :] position of the
  intermediate point used to join each time the next node
  (\emph{Default:~empty} --- not used).
\end{Description}

\begin{CenterExample}
  \PstPolygon
  \PstPolygon[§HLeµPolyIntermediatePoint¶=§HLCBWzµ0.38¶]
  \PstPolygon[§HLeµPolyIntermediatePoint¶=§HLCBWzµ0.2¶]
  \PstPolygon[§HLeµPolyIntermediatePoint¶=§HLCBWzµ1.2¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ7¶,§HLeµPolyOffset¶=§HLCBWzµ2¶,§HLeµPolyIntermediatePoint¶=§HLCBWzµ0.38¶]
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ21¶,§HLeµPolyOffset¶=§HLCBWzµ2¶,
              §HLeµPolyIntermediatePoint¶=§HLCBWzµ-1.25¶]
\end{CenterExample}

\begin{Description}{2cm}
  \item [\HLTTc{PolyCurves} (boolean)\hfill :] boolean value to choose
  between straight line and curve to join each time the next node
  (\emph{Default:~false} --- straight lines).
\end{Description}

\begin{CenterExample}
  \psset{§HLCBWzµPolyCurves¶}
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ7¶,§HLeµPolyIntermediatePoint¶=§HLCBWzµ0.38¶]\hfill
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ11¶,§HLeµPolyIntermediatePoint¶=§HLCBWzµ0.6¶]\hfill
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ7¶,§HLeµPolyIntermediatePoint¶=§HLCBWzµ0.2¶,
              §HLeµPolyOffset¶=§HLCBWzµ2¶]\hfill
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ9¶,§HLeµPolyIntermediatePoint¶=§HLCBWzµ0.1¶]\hfill
  \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ15¶,§HLeµPolyIntermediatePoint¶=§HLCBWzµ1.2¶]
\end{CenterExample}

\begin{Description}{2cm}
  \item [\HLTTc{PolyEpicycloid} (boolean)\hfill :] boolean value to choose
  between polygon and epicycloid (\emph{Default:~false} --- polygon).
\end{Description}

\begin{CenterExample}
  \psset{linewidth=0.001,§HLeµPolyNbSides¶=§HLCBWzµ72¶,§HLCBWzµPolyEpicycloid¶}
  % §HLbµEpicycloid of factor 1 is cardioid and of factor 2 nephroid¶
  \multido{\i=2+1}{4}{\PstPolygon[§HLeµPolyOffset¶=§HLCBWzµ\i¶]\hfill}
  \PstPolygon[§HLeµPolyOffset¶=§HLCBWzµ72¶]\hfill % §HLbµEpicycloid of factor 71¶
  \PstPolygon[§HLeµPolyOffset¶=§HLCBWzµ73¶]       % §HLbµEpicycloid of factor 72¶
\end{CenterExample}

\begin{Description}{2cm}
  \item [\HLTTc{PolyName} (string)\hfill :] name of the polygon, useful to
  have different names for the nodes of different polygons
  (\emph{Default:~empty --- no name}).
\end{Description}

  The center of the polygon has name \texttt{PolyName0} and the nodes
(vertices) have names \texttt{PolyName1} to \texttt{PolyNameN}.

{\fvset{xrightmargin=3cm}     % Reserved space for the result
  With this parameter, we can connect as we want nodes of different polygons:

\vspace{2mm}
\begin{SideBySideExample}
  \psset{PstPicture=false}
  \begin{pspicture}(-1,-1)(1,1)
    \PstPolygon[unit=0.8,PolyName=A,PolyNbSides=6]
    \PstPolygon[unit=1.2,PolyName=B,PolyNbSides=12]
  \end{pspicture}
  \multido{\i=1+2}{6}{%
    \ncline{A\the\multidocount}{B\i}}
\end{SideBySideExample}

\clearpage
  It is also a way (limited in fact...) to define three dimensional objects in
perspective (this was used first in \cite{RoseMoore:XYpic:1998}):

\vspace{2mm}
\begin{SideBySideExample}
  \psset{unit=0.8}
  \begin{pspicture}(3,2.5)
    % §HLbµ\PstSquare is described later¶
    \rput[lb](0,0){\PstSquare[PolyName=A]}
    \rput[lb](2.5,2){\PstSquare[unit=0.5,PolyName=B]}
    \multido{\i=1+1}{4}{\ncline{A\i}{B\i}}
  \end{pspicture}
\end{SideBySideExample}
}

\vspace{2mm}
  Of course, we can mix specific \PolyPackage{} parameters with relevant
PSTricks ones and combine it with other generic macros (for repetitions,
projection in the 3d space, etc.)

\begin{CenterExample}
  \PstPolygon[unit=§HLCBWzµ1.5¶,linestyle=§HLCBWzµdashed¶]
  \PstPolygon[linewidth=§HLCBWzµ1mm¶]
  \PstPolygon[fillstyle=§HLCBWzµcrosshatch¶,§HLeµPolyNbSides¶=§HLCBWzµ6¶]
  \PstPolygon[linecolor=§HLCBWzµred¶,fillstyle=§HLCBWzµsolid¶,fillcolor=§HLCBWzµyellow¶,
              §HLeµPolyRotation¶=§HLCBWzµ18¶,§HLeµPolyOffset¶=§HLCBWzµ2¶]
  \PstPolygon*[linecolor=§HLCBWzµcyan¶,§HLeµPolyNbSides¶=§HLCBWzµ7¶,§HLeµPolyOffset¶=§HLCBWzµ2¶]
\end{CenterExample}

\begin{CenterExample}
  \multido{\i=5+2}{6}{%
    \PstPolygon[§HLeµPolyNbSides¶=§HLCBWzµ\i¶,§HLCBWzµPolyCurves¶,
                §HLeµPolyIntermediatePoint¶=§HLCBWzµ0.1¶,§HLeµPolyOffset¶=§HLCBWzµ3¶]}
\end{CenterExample}

\subsection{Pre-defined polygons}

  Some often used polygons and other related geometric objects are
pre-defined, for immediate usage :

\begin{CenterExample}
  \PstTriangle
  \PstSquare
  \PstPentagon[unit=0.5,linestyle=dotted]
  \PstHexagon[fillstyle=hlines,hatchangle=90]
  \PstHeptagon[fillstyle=vlines]
  \PstOctogon*[unit=0.8,linecolor=red]
  \PstNonagon[unit=0.5]
  \PstDecagon
  \PstDodecagon[linecolor=green]
  \PstStarFiveLines
  \PstStarFive
\end{CenterExample}

\subsection{Non regular polygons}

  Until now, we have described only the so-called \emph{regular} polygons,
which are from far the most useful ones (all of them have equal edges and
angles). Nevertheless, it is not so difficult to extend these polygon to
\emph{non regular} ones, using a different value for horizontal and vertical
units (nevertheless, the code is more tricky, as we must do all the
trigonometry explicitely...)

\begin{CenterExample}
  \PstPentagon[xunit=§HLCBWzµ0.5¶]\hfill
  \PstHexagon[yunit=§HLCBWzµ0.5¶]\hfill
  \PstStarFive[xunit=§HLCBWzµ0.5¶,yunit=§HLCBWzµ1.5¶]\hfill
  \PstPolygon[xunit=§HLCBWzµ0.8¶,yunit=§HLCBWzµ1.5¶,PolyNbSides=9,PolyOffset=2,
              PolyIntermediatePoint=0.1,PolyCurves]
\end{CenterExample}

\subsection{Nodes (vertices)}

  And another powerful possibility is to define a command \PstPolyNode{} which
  will be excuted at each node (\emph{Default:~empty} --- nothing executed).
The counter name for nodes is \cs{INode}, starting from 0. The
\cs{multidocount} counter, from the \cs{multido} command, start itself from 1.
\vspace{5mm}

{\fvset{xrightmargin=3cm}        % Reserved space for the result
\begin{SideBySideExample}
  \providecommand{\PstPolygonNode}{%
    §HLCBWzµ\psdots[dotsize=0.2,linecolor=cyan](1;\INode)¶}
  \PstPentagon
\end{SideBySideExample}

\begin{SideBySideExample}
  \newcounter{Letter}
  \providecommand{\PstPolygonNode}{%
    §HLCBWzµ\setcounter{Letter}{\the\multidocount}¶%
    §HLCBWzµ\rput*{*0}(1;\INode){\small\Alph{Letter}}¶}
  \PstHeptagon[PolyOffset=3]
\end{SideBySideExample}

\begin{SideBySideExample}
  \providecommand{\PstPolygonNode}{%
    §HLCBWzµ\psdots[dotstyle=o,dotsize=0.2](1;\INode)¶
    §HLCBWzµ\psline[linecolor=red]{->}(0.9;\INode)¶}
  \PstPolygon[PolyNbSides=8]
\end{SideBySideExample}

\clearpage
  It is also a way to nest polygons:
\vspace{5mm}

\begin{SideBySideExample}
  \newbox{\Star}
  \savebox{\Star}{%
    \PstStarFive*[unit=0.15,linecolor=red]}
  \providecommand{\PstPolygonNode}{%
    §HLCBWzµ\rput{*0}(1;\INode){\usebox{\Star}}¶}
  \shortstack{\PstNonagon\\[5mm]
              \PstDodecagon[linestyle=none]}
\end{SideBySideExample}
}

\vspace{5mm}
  Here we redraw one of the polygon examples built with the \XYpic{} package
in \cite[example 5-5-34, page 203]{LGC:1997}:

\begin{CenterExample}
  \psset{unit=2,PstPicture=false}
  \begin{pspicture}(-1.6,-1.6)(1.6,1.6)
    %§HLbµ Just to name the nodes, to be able to join some of them.¶
    %§HLbµ by solid curves. We can't draw the polygons now,¶
    %§HLbµ as the node numbers must erase the solid curves...¶
    \PstHexagon[unit=0.8,linestyle=none,PolyName=H]
    \PstDodecagon[unit=1.2,linestyle=none,PolyName=D]
    {\SpecialCoor
     \psset{linewidth=0.4pt,border=2pt,nodesep=0.45}
     \psccurve(H1)(H4)(D8)([angle=-30]D9)(D11)
     \psccurve(D3)(H3)(H6)(D12)([angle=90]D1)
     \psccurve(D4)(H2)(H5)(D7)([angle=90]D6)}
    \psset{linestyle=dotted,framesep=1pt}
    \PstTriangle[unit=0.23]
    \providecommand{\PstPolygonNode}{%
      \rput*{*0}(1;\INode){\small\the\multidocount}}
    \PstHexagon[unit=0.8]
    \PstDodecagon[unit=1.2]
    \PstDodecagon[unit=1.6]
  \end{pspicture}
\end{CenterExample}

\clearpage
\subsection{Implementation}

\RecustomVerbatimEnvironment{Verbatim}{Verbatim}{commandchars=§µ¶}

  As it is a general and very powerful way to build \emph{high level graphic
objects} above PSTricks own ones, we will comment main parts of the
code. Nevertheless, we restrict here to the case of \emph{regular} polygons,
which is enough to show all useful major technics. In fact, all real
difficulties in the code of \PolyPackage{} are for the \emph{non regular}
case, which involve some trigonometry. For this, you must refer to the code in
the file itself.

  First we define the parameters specific to the polygons:

  \begin{itemize}
    \item \texttt{PstPicture} will define if the polygon must be set inside a
    \texttt{pspicture} environment or not. It is a \emph{boolean} value, so we
    define a new \cs{if} \TeX{} variable. The \texttt{true} value specified
    will give the default to used when no value is affected to this parameter
    (so \texttt{PstPicture} will be equivalent to \texttt{PstPicture=true}).
    Take care that it is not the default value for the parameter itself (we
    will see later that here we choose \texttt{false} as default value...)
    We don't prefix this parameter name by \texttt{Poly} because it is not
    specific to polygons. Note also that \texttt{psset} is the generic name
    for all PSTricks parameters.
  \end{itemize}

\fvset{gobble=0,numbersep=3pt}

\begin{Verbatim}
\newif\ifPst@PstPicture
\define@key{psset}{§HLCBWzµPstPicture¶}[true]{%
\@nameuse{Pst@PstPicture#1}}
\end{Verbatim}

  \begin{itemize}
    \item \texttt{PolyRotation} will be the rotation angle to applied to the
    polygon. It is a \emph{real} value used as an \emph{angle}.
  \end{itemize}

\fvset{firstnumber=last}
\begin{Verbatim}
\define@key{psset}{§HLCBWzµPolyRotation¶}{%
\edef\psk@PolyRotation{#1}}
\end{Verbatim}

  \begin{itemize}
    \item \texttt{PolyNbSides} will be the number of sides (edges) of the
    polygon. It is an \emph{integer} value and we store it into a \TeX{}
    macro (in this way, we can define a lot of integer parameters without
    having the risk to exhaust \TeX{} limitations of numbers of counters).
  \end{itemize}

\begin{Verbatim}
\define@key{psset}{§HLCBWzµPolyNbSides¶}{%
\pst@cntg=#1\relax
\edef\psk@PolyNbSides{\the\pst@cntg}}
\end{Verbatim}

  \begin{itemize}
    \item \texttt{PolyOffset} will be the offset to obtain the next vertice to
    connect, for each one of the polygon. It is an \emph{integer} value.
  \end{itemize}

\begin{Verbatim}
\define@key{psset}{§HLCBWzµPolyOffset¶}{%
\pst@cntg=#1\relax
\edef\psk@PolyOffset{\the\pst@cntg}}
\end{Verbatim}

  \begin{itemize}
    \item \texttt{PolyIntermediatePoint} will be the position of an
    intermediate point to used between current vertice and the next one,
    for each edge. It will defined a \emph{relative} position, which will be
    the same for each edge. As it is a \emph{real} value, we use here a
    dimension register.
  \end{itemize}

\begin{Verbatim}
\newdimen\psl@PolyIntermediatePoint
\define@key{psset}{§HLCBWzµPolyIntermediatePoint¶}{%
\edef\psk@PolyIntermediatePoint{#1}}
\end{Verbatim}

  \begin{itemize}
    \item \texttt{PolyName} will be the name assign to the polygon, which will 
    be useful if we would like to connect edges of different polygons. It is a 
    \texttt{string} that we store in a macro.
  \end{itemize}

\begin{Verbatim}
\define@key{psset}{§HLCBWzµPolyName¶}{%
\edef\ps@PolyName{#1}}
\end{Verbatim}

  \begin{itemize}
    \item \texttt{PolyCurves} will define if the edges are lines or curves. It 
    is a \emph{boolean value}. And logically, there will be no effect if there 
    is no intermediate point defined.
  \end{itemize}

\begin{Verbatim}
\newif\ifPst@PolyCurves
\define@key{psset}{§HLCBWzµPolyCurves¶}[true]{%
\@nameuse{Pst@PolyCurves#1}}
\end{Verbatim}

  \begin{itemize}
    \item \texttt{PolyEpicycloid} will define if we will draw a polygon or an
    epicycloid (which is not a polygon, but this was a functionality very easy
    to add to this package!) It is a \emph{boolean} value.
  \end{itemize}

\begin{Verbatim}
\newif\ifPst@PolyEpicycloid
\define@key{psset}{§HLCBWzµPolyEpicycloid¶}[true]{%
\@nameuse{Pst@PolyEpicycloid#1}}
\end{Verbatim}

  \begin{itemize}
    \item Next, we position the default values for all these new
    parameters. We choose to have no rotation, five sides, no offset (so a
    value of 1), no intermediate point, no name, connections by lines (so no
    curved ones) and polygon (so no epicycloid).
  \end{itemize}

\begin{Verbatim}
\setkeys{psset}{%
PstPicture=§HLCBWzµtrue¶,PolyRotation=§HLCBWzµ0¶,PolyNbSides=§HLCBWzµ5¶,PolyOffset=§HLCBWzµ1¶,
PolyIntermediatePoint=,PolyName=,PolyCurves=§HLCBWzµfalse¶,
PolyEpicycloid=§HLCBWzµfalse¶}
\end{Verbatim}

  \begin{itemize}
    \item Now, we define the main \cs{PstPolygon} macro. First we look if the
    \texttt{*} convention is used, as for many PSTricks macros, to fill the
    graphic object using the color of the line.
  \end{itemize}

\begin{Verbatim}
\def§HLCBWzµ\PstPolygon¶{%
\pst@ifstar{\@ifnextchar[\@PstPolygon{\@PstPolygon[]}}}
\end{Verbatim}

  \begin{itemize}
    \item Then we define the auxiliary macro which will handle the parameters
    if some are used. Note also the usage of the double \verb+{{+ to have
    only changes of parameter values for this specific object, as
    redefinitions of them must be local.
  \end{itemize}

\begin{Verbatim}
\def\@PstPolygon§HLCBWzµ[#1]¶{{%
\end{Verbatim}

  \begin{itemize}
    \item After that, we can affect the value of local parameters if defined
    and take account of the \texttt{*} convention if used.
  \end{itemize}

\begin{Verbatim}
\setkeys{§HLCBWzµpsset¶}{#1}%
\if@star§HLCBWzµ\solid@star¶\fi
\end{Verbatim}

  \begin{itemize}
    \item For security, we can make various checks on the validity of the
    parameters.
  \end{itemize}

\begin{Verbatim}
\ifnum\psk@PolyNbSides<§HLCBWzµ3¶
{\@pstrickserr{PolyNbSides must be greater than
   2 (and not `\psk@PolyNbSides')}\@eha}%
\fi
\ifnum\psk@PolyNbSides>§HLCBWzµ200¶
{\@pstrickserr{PolyNbSides must be less than
   201 (and not `\psk@PolyNbSides')}\@eha}%
\fi
\ifnum\psk@PolyOffset<§HLCBWzµ1¶
{\@pstrickserr{PolyOffset must be greater than
   0 (and not `\psk@PolyOffset')}\@eha}%
\fi
\end{Verbatim}

  \begin{itemize}
    \item And now, we can start the \emph{real} code... First we affect a
    special value for the case where an offset will be used. There are only
    two cases, when the offset will be \emph{odd} or \emph{even}.
  \end{itemize}

\begin{Verbatim}
§HLCBWzµ\ifodd¶\psk@PolyOffset
  \def\Pst@PolyDecimal{§HLCBWzµ.5¶}%
\else
  \def\Pst@PolyDecimal{}%
\fi
\end{Verbatim}

  \begin{itemize}
    \item We must say to use non cartesian coordinates (we will used polar
    ones --- and special ones computed by trigonometry and defined in
    PostScript for \emph{non} regular polygons).
  \end{itemize}

\begin{Verbatim}
§HLCBWzµ\SpecialCoor¶
\end{Verbatim}

  \begin{itemize}
    \item We look at the definition of a \texttt{pspicture} environment or not.
  \end{itemize}

\begin{Verbatim}
\ifPst@PstPicture§HLCBWzµ\pspicture(-1,-1)(1,1)¶\fi
\end{Verbatim}

  \begin{itemize}
    \item We rotate the polygon if necessary (if not we will use a rotation
    of angle 0, which will have of course no effect).
  \end{itemize}

\begin{Verbatim}
\rput{\psk@PolyRotation}(0,0){%
\end{Verbatim}

  \begin{itemize}
    \item We will used polar coordinates, with a unit given by the number of
    sides of the polygon.
  \end{itemize}

\begin{Verbatim}
  \degrees[§HLCBWzµ\psk@PolyNbSides¶]
\end{Verbatim}

  \begin{itemize}
    \item If there is a name for this polygon, we assigne this name followed
    by 0 to the center of it, and different names to all vertices, indexed by
    the number of the vertice.
  \end{itemize}

\begin{Verbatim}
  \ifx\ps@PolyName\@empty
  \else
    \pnode(0,0){§HLCBWzµ\ps@PolyName 0¶} % Center of the polygon
    \multido{\i=0+1}{\psk@PolyNbSides}{%
      \pnode(1;\i){§HLCBWzµ\ps@PolyName\the\multidocount¶}}
  \fi
\end{Verbatim}

  \begin{itemize}
    \item Now we are ready to draw the polygon. We use a \cs{pscustom}
    environment.
  \end{itemize}

\begin{Verbatim}
  §HLCBWzµ\pscustom¶{%
\end{Verbatim}

  \begin{itemize}
    \item First, the case of epicycloids. We must only join each vertice to
    the opposite one, using the defined offset as gap.
  \end{itemize}

\begin{Verbatim}
    \ifPst@PolyEpicycloid % Code for epicycloids
      \pst@cnta=\psk@PolyNbSides
      \divide\pst@cnta\tw@
      \multido{\i=0+1}{\psk@PolyNbSides}{%
        \moveto(1;§HLCBWzµ\i¶)
        \lineto(1;§HLCBWzµ\the\pst@cnta¶)
        \advance\pst@cnta\psk@PolyOffset}
\end{Verbatim}

  \begin{itemize}
    \item Now, we can see the case of polygons. First, we move to the starting 
    point.
  \end{itemize}

\begin{Verbatim}
    \else % Code for polygons
      \moveto(1,§HLCBWzµ0¶)
\end{Verbatim}

  \begin{itemize}
    \item If there is no intermediate point, we must only have a loop to join
    all vertices, according to the number of edges. And we use each time the
    defined value of the offset to obtain the next vertice.
  \end{itemize}

\begin{Verbatim}
      \ifx\psk@PolyIntermediatePoint\@empty
        \multido{\i=\psk@PolyOffset+§HLCBWzµ\psk@PolyOffset¶}
                {§HLCBWzµ\psk@PolyNbSides¶}{%
          \lineto(1;§HLCBWzµ\i¶)}
\end{Verbatim}

  \begin{itemize}
    \item If there is an intermediate point, first we see if vertices will be
    join by lines or curves.
  \end{itemize}

\begin{Verbatim}
      \else % Intermediate points
        \ifPst@PolyCurves
          \let\Pst@PolyJunctionType§HLCBWzµ\pscurve¶
        \else
          \let\Pst@PolyJunctionType§HLCBWzµ\psline¶
        \fi
\end{Verbatim}

  \begin{itemize}
    \item We compute half of the value of the offset. We use a counter for
    that, which is an integer, so we will add the value of the
    \cs{Pst@PolyDecimal} macro defined above, which has value 0.5 if the
    offset is an odd number.
  \end{itemize}

\begin{Verbatim}
        \pst@cnta=\psk@PolyOffset
        \divide\pst@cnta\tw@
\end{Verbatim}

  \begin{itemize}
    \item Now, we can execute the main loop: for each vertice we join the
    current one to the next, using each time the intermediate point defined.
  \end{itemize}

\begin{Verbatim}
        \multido{\i=\psk@PolyOffset+§HLCBWzµ\psk@PolyOffset¶}%
                {§HLCBWzµ\psk@PolyNbSides¶}{%
          §HLCBWzµ\Pst@PolyJunctionType¶%
            (§HLCBWzµ\psl@PolyIntermediatePoint¶;%
             §HLCBWzµ\the\pst@cnta\Pst@PolyDecimal¶)(1;§HLCBWzµ\i¶)
          \advance\pst@cnta\psk@PolyOffset}
\end{Verbatim}

  \begin{itemize}
    \item Now, we can close the opened \emph{if} structures and the
    \texttt{pscustom} environment.
  \end{itemize}

\begin{Verbatim}
      \fi % End \ifx\psk@PolyIntermediatePoint
    \fi}  % End \ifPst@PolyEpicycloid and \pscustom
\end{Verbatim}

  \begin{itemize}
    \item In the case where there is a special macro of name
    \cs{PstPolygonNode} defined, we execute it at each node, and we close the 
    rotation command. The counter used is \cs{INode}.
  \end{itemize}

\begin{Verbatim}
    \ifx\PstPolygonNode\@undefined
    \else
      \multido{\INode=0+\psk@PolyOffset}{\psk@PolyNbSides}{%
        §HLCBWzµ\PstPolygonNode¶} % Command to execute at each node
    \fi}                  % End \rput
\end{Verbatim}

  \begin{itemize}
    \item And to finish we close the \texttt{pspicture} environment if
    required.
  \end{itemize}

\begin{Verbatim}
\ifPst@PstPicture§HLCBWzµ\endpspicture¶\fi}}
\end{Verbatim}

% Bibliography
\begin{raggedright}
  \bibliography{doc-poly}
\end{raggedright}

\end{document}
