% by Sylwester Arabas <slayoo@igf.fuw.edu.pl>
% part of GDL -- GNU Data Language

\ProvidesPackage{gdldoc}
\NeedsTeXFormat{LaTeX2e}
\catcode`\&=12 % deactivating &

\newcommand{\gdlroutinedesc}[4]{
  % routine type (function/procedure)
  \convertchar[e]{#2}{1}{() function}
  \convertchar[q]{\thestring}{0}{ procedure}
  \let\gdlroutinetype\thestring
  % routine type prefix
  \convertchar[e]{#2}{1}{FUN}
  \convertchar[q]{\thestring}{0}{PRO}
  \let\gdlroutinetypepfx\thestring
  % routine name
  \convertchar[q]{#1}{-}{\_}
  \let\gdlroutinename\thestring
  % routine "code"
  \caseupper[q]{#1}
  \let\gdlroutinecode\thestring
  % section header

  % that's one option which gives correct references but no header information
  %\subsection{\Large\bf\gdlroutinename\gdlroutinetype}
  %\phantomsection
  %\addcontentsline{toc}{chapter}{\numberline{}\gdlroutinename\gdlroutinetype}

  \section{\gdlroutinename\gdlroutinetype}
  \label{LIB.#1.\gdlroutinetypepfx}%\label{name{LIB.#1.\gdlroutinetypepfx}}
  \begin{description}
    \item[positional\ arguments:]{\ifthenelse{\equal{#3}{0}}{none}{\ifthenelse{\equal{#3}{-1}}{any number}{#3}}}
    \item[keywords:]{
      \ifthenelse{\equal{#4}{}}{none}{
        \let\gdlkeywordname\gdlroutinetype
        \@for\gdlkeywordcode:=#4\do{% 
          \ifthenelse{\equal{\gdlkeywordname}{\gdlroutinetype}}{}{, }
          \convertchar[q]{\gdlkeywordcode}{-}{\_}%
          \let\gdlkeywordname\thestring%
          \hyperref[LIB.\gdlroutinecode.\gdlroutinetypepfx.KW.\gdlkeywordcode]{\gdlkeywordname}%
          \index{\gdlkeywordname~keyword!in \gdlroutinename\gdlroutinetype}% it would be better to place it inside \gdlkeyworddesc
                                                                           % so that the indexed page number refers to actual description
                                                                           % of the keyword but then not all keywords would be indexed automagically
        }
      }
    }
  \end{description}
  \index{\gdlroutinename\gdlroutinetype}
  \caselower[q]{#1.\gdlroutinetypepfx}
  \input{routines/\thestring.tex} % including PRO/FUN in the filename! (e.g. PYTHON() & PYTHON)
  %TODO: auto-disclaimer for IMSL_* e.g.
}

\newcommand{\gdlkeyworddesc}[1]{
  \caseupper[q]{LIB.\gdlroutinecode.\gdlroutinetypepfx.KW.#1} 
  \let\gdlkwlabel\thestring
  \convertchar[q]{#1}{-}{\_}
  \subsubsection{\thestring~keyword\label{\gdlkwlabel}}
}

\newcommand{\gdlfunref}[1]{%
  \caseupper[q]{#1}
  \let\tmp\thestring
  \convertchar[q]{\tmp}{-}{\_}%
  \index{\thestring() function}%
  \hyperref[LIB.\tmp.FUN]{\thestring()}%
}
\newcommand{\gdlproref}[1]{%
  \caseupper[q]{#1}
  \let\tmp\thestring
  \convertchar[q]{\tmp}{-}{\_}%
  \index{\thestring procedure}%
  \hyperref[LIB.\tmp.PRO]{\thestring}%
}

\newcommand{\gdlcodeexample}[3]{
  \lstset{emph={#2},emphstyle={\color{blue}}} 
  \lstinputlisting[numbers=left, numberstyle=\tiny, frame=trBL]{examples/#1/#1.pro}
  \lstset{emph={#3}} 
  \lstinputlisting[frame=trBL]{examples/#1/#1.out.txt}
  \ifx\HCode\Undef
    \input{examples/#1/#1.out.tex}
  \fi
}

\newcommand{\gdlseealso}[1]{
  \begin{description}
    \item[see also:]{#1}
  \end{description}
}

\newcommand{\gdldisclaimer}[1]{
  \begin{description}
    \item[disclaimer:]{#1}
  \end{description}
}

\newcommand{\gdlimplmtndtls}[1]{
  \begin{description}
    \item[implementation details:]{#1}
  \end{description}
}

\newcommand{\gdlimsldisclaimer}{
  \gdldisclaimer{the name of this GDL routine includes the {\bf IMSL\_} prefix for 
    compatibility with IDL, it has no ...}
}
\newcommand{\gdlidldisclaimer}{
  \gdldisclaimer{the name of this GDL routine includes the {\bf IDL\_} prefix for 
    compatibility with IDL, it has no ...}
}

\newcommand{\gdlusesopenmp}{
  \index{multithreading!in \gdlroutinename\gdlroutinetype}%
  \begin{description}
    \item[multi-threading:]{this routine uses GDL thread pool if working on large array, see the...}
  \end{description}
}

\newcommand{\gdlcallingseq}[1]{
  \begin{description}
    \item[calling sequence:]{#1}
  \end{description}
}

\catcode`\&=4
\endinput
