%
% \GetFileInfo{gmiflink.sty}
% \title{The \pk{gmiflink} Package\thfileinfo}
% \author{Grzegorz `Natror' Murzynowski}
% \maketitle
%
%
% \begin{copyrnote}
%
%%   Written by Grzegorz `Natror' Murzynowski,
%%   natror at o2 dot pl
%%
%% \copyright\,2005, 2006 by Grzegorz `Natror' Murzynowski.
%%
%% This program is subject to the \LaTeX\ Project Public License.
%% See ^^A
%% \url{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html} ^^A
%% for the details of that license.
%%
%% LPPL status: "author-maintained".\par
%
%\end{copyrnote}
%
% \CheckSum{61}
%% 

\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{gmiflink}
     [2006/08/16 v0.97 Conditionally hyperlinking package (GM)]

%%
%% \division{Introduction, usage}
%%
%% This package protects you against an error when a link is
%% dangling and typesets some plain text instead of a hyperlink then. It
%% is intended for use with the \pk{hyperref} package. Needs
%% \emph{two} \LaTeX\ runs.
%
% I used it for typesetting the names of the objects in
% a~documentation of a~computer program. If the object had been
% defined a \cs{hyperlink} to its definition was made, otherwise a
% plain object's name was typeset.  I also use this package in
% authomatic making of hyperlinking indexes.
% \dekmedskip
%
% The package provides the macros \cs{gmiflink}, \cs{gmifref} and
% \cs{gmhypertarget} for conditional making of hyperlinks in your
% document.
%
% \newcommand*\aName{\gmiflink[@name]{\hskip-1.5pt @name}}
% \TextUsage\gmhypertarget\oarg{name}\marg{\gmiflink{text}} makes
% a~\cs{hypertarget\marg{\aName}\marg{text}} and \possfil
% a~\cs{label\marg{\aName}}.
%
% \TextUsage\gmiflink\oarg{name}\marg{text} makes
% a~\cs{hyperlink\marg{\aName}\marg{text}} to a~proper hypertarget if
% the corresponding \emph{label} exists, otherwise it typesets
% \<text>.
%
% \TextUsage\gmifref\oarg{name}\marg{text} makes a~(hyper-)
% \cs{ref\marg{\aName}} to the given label if the label exists,
% otherwise it typesets \<text>.
%
% The \raisebox{1em}[0pt]{\gmhypertarget[@name]{}}\<\hskip-1.5pt @name>
% ^^A~raisebox 'cause Acrobat sets the hypertarget at the baseline
% argument is just \<name> if the \<name>
% is given, otherwise it's \<text> in all three macros.
%
% For the example(s) of use, examine the \pk{gmiflink.sty} file, lines
% 45--58.
%
% \begin{gmlonely}
%   \subdivision{Installation}
%
%   Unpack the \file{gmiflink-tds.zip} (this is an archive conforming
%   the \acro{TDS} standard, see \file{CTAN/tds/tds.pdf}) in
%   a~\file{texmf} directory or put the \pk{gmiflink.sty} somewhere in
%   the \file{texmf/\:tex/\:latex} branch on your own. (Creating
%   a~\file{texmf/\:tex/\:latex/\:gm} directory may be advisable if
%   you consider using other packages written by me.)
%
%   Then you should refresh your \TeX\ distribution's files' database
%   most probably. 
% \end{gmlonely}
%
%
% \subdivision{Contents of the \pk{gmiflink.zip} archive}
%
% The distribution of the \pk{gmiflink} package consists of the
% following four files and a~\acro{TDS}-compliant archive.
% \begin{verse}
%   \pk{gmiflink.sty}\\
%   \pk{README}\\
%   \pk{gmiflinkDoc.tex}\\
%   \pk{gmiflinkDoc.pdf}\\
%   \pk{gmiflink.tds.zip}
% \end{verse}
%
%
% \begin{gmlonely}
%   \subdivision{Compiling the Documentation}
%
%   The last of the above files (the \pk{.pdf}, i.e., \emph{this
%     file}) is a~documentation compiled from the \pk{.sty} file by
%   running \LaTeX\ on the \pk{gmiflinkDoc.tex} file.
%   Compiling the documentation requires the packages: \pk{gmdoc}
%   (\pk{gmdoc.sty} and \pk{gmdocc.cls}), \pk{gmverb.sty},
%   \pk{gmutils.sty}, \pk{gmiflink.sty} and also some standard
%   packages: \pk{hyperref.sty}, \pk{color.sty}, \pk{geometry.sty},
%   \pk{multicol.sty}, \pk{lmodern.sty}, \pk{fontenc.sty} that should
%   be installed on your computer by default.
%
%   If you had not installed the \pk{mwcls} classes (available on
%   CTAN and present in \TeX\ Live e.g.), the result of your
%   compilation might differ a~bit from the \pk{.pdf} provided in this
%   \pk{.zip} archive in formatting: If you had not installed
%   \pk{mwcls}, the standard \pk{article.cls} class would be used.
% \end{gmlonely}
%
% \StopEventually{\NoEOF}
%
% 
% \division{The Code}

\@ifpackageloaded{hyperref}{}{\message {^^J^^J gmiflink package:
    There's no use of me without hyperref package, I end my input.^^J}\endinput}

\providecommand\empty{} 
% A~new counter, just in case
\newcounter{GMhlabel}
\setcounter{GMhlabel}{0}

% The macro given below creates both hypertarget and hyperlabel, 
% so that you may reference both ways: via |\hyperlink| and via |\ref|.
% It's pattern is the |\label| macro, see \LaTeX\ Source2e, file x, line 32.
%
% But we don't want to gobble spaces before and after.
% First argument will be a~name of the hypertarget,
% by default the same as typeset text, i.e., argument |#2|.
% \Define\gmhypertarget
\DeclareRobustCommand*\gmhypertarget{%
  \@ifnextchar{[}{\gm@hypertarget}{\@dblarg{\gm@hypertarget}}}
%^^A]

\def\gm@hypertarget[#1]#2{% ^^A
  % If argument |#1|\equals|\empty|, then we'll use |#2|, i.e., the same as
  % name of hypertarget.
  \refstepcounter{GMhlabel}% ^^A
  % we |\label{\gmht@firstpar}|
  \hypertarget{#1}{#2}%
  \protected@write\@auxout{}{%
    \string\newlabel{#1}{{#2}{\thepage}{\relax}{GMhlabel.\arabic{GMhlabel}}{}}}%
}% end of |\gm@hypertartget|.

% We define a~macro such that if the target exists, it makes
% |\ref|, else it typesets ordinary text.
% \Define\gmifref
\DeclareRobustCommand*\gmifref{\@ifnextchar{[}{\gm@ifref}{%]
    \@dblarg{\gm@ifref}}}

\def\gm@ifref[#1]#2{%
  \expandafter\ifx\csname r@#1\endcsname\relax\relax%
  #2\else\ref{#1}\fi%
}%  end of |\gm@ifref|

% \Define\gmiflink
\DeclareRobustCommand*\gmiflink{\@ifnextchar{[}{\gm@iflink}{%^^A]
    \@dblarg{\gm@iflink}}}

\def\gm@iflink[#1]#2{%
  \expandafter\ifx\csname r@#1\endcsname\relax\relax%
  #2\else\hyperlink{#1}{#2}\fi%
}% end of |\gm@iflink|
%
% It's robust because when just |\newcommand*|ed, use of |\gmiflink| in an
% indexing macro resulted in errors: |\@ifnextchar| has to be
% |\noexpand|ed in |\edef|s.

\endinput

% The old version --- all three were this way primarily.
%\begin{verbatim}
\newcommand*\gmiflink[2][\empty]{{%
  \def\gmht@test{\empty}\def\gmht@firstpar{#1}%
  \ifx\gmht@test\gmht@firstpar\def\gmht@firstpar{#2}\fi%
  \expandafter\ifx\csname r@\gmht@firstpar\endcsname\relax\relax%
  #2\else\hyperlink{\gmht@firstpar}{#2}\fi%
}}
% \end{verbatim}
% \Finale

% (For my GNU Emacs:)
%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: "../../../../LaTeX/TeXGuru/gmiflink/gmiflinkDoc"
%%% End: