% \iffalse                                                 -*- mode: LaTeX -*-
%
% fink.dtx --- Doc file for the FiNK package (code and documentation)
%
% Copyright (C) 1999, 2000, 2001, 2002, 2007 Didier Verna.
%
% Author:        Didier Verna <didier@lrde.epita.fr>
% Maintainer:    Didier Verna <didier@lrde.epita.fr>
% Created:       Thu Sep 23 18:23:48 1999
% Last Revision: Mon Jun 11 10:59:19 2007
%
% This file is part of FiNK.
%
% FiNK may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.1
% of this license or (at your option) any later version.
% The latest version of this license is in
% http://www.latex-project.org/lppl.txt
% and version 1.1 or later is part of all distributions of LaTeX
% version 1999/06/01 or later.
%
% FiNK consists of all files listed in the file `README'.
%
%
% Commentary:
%
% Contents management by FCM version 0.1.
%
%
% Code:
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
% \OnlyDescription
% \CodelineIndex
% \RecordChanges
\newcommand{\fink}{%
  \mbox{\fontfamily{ptm}\fontseries{b}\fontshape{it}\selectfont%
    F\hspace{-.4ex}\protect\raisebox{-.5ex}{\textmd{i}}\hspace{0.2ex}NK}%
  }
\begin{document}
\DocInput{fink.dtx}
\end{document}
%</driver>
%
% \fi
%
% \catcode`\¡=14
% \CheckSum{153}
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
% \newcommand\version{2.1.1}
% \newcommand\releasedate{2008/02/27}
% \newcommand\packagecopyright{Copyright \copyright{} 1999, 2000, 2001, 2002,
%   2007, 2008 Didier Verna}
% \newcommand\auctex{AUC-\TeX}
% \MakeShortVerb{\|}
% \date{\today}
% \title{\fink{} -- the \LaTeXe{} \textbf{Fi}le \textbf{N}ame
%   \textbf{K}eeper\thanks{This document describes \fink{} \version, release
%     date \releasedate.}}
% \author{Didier Verna\\
%   \texttt{mailto:didier@lrde.epita.fr}\\
%   \texttt{http://www.lrde.epita.fr/\~{}didier/}}
% \maketitle
%
% \section{Description}
% This package is a real fink indeed: it looks over your shoulder and keeps
% track of files |\input|'ed (the \LaTeX{} way) or |\include|'ed in your
% document. You then have a permanent access to the directory, name and
% extension of the file currently being processed through several macros. Dis
% packache fas orichinally a hack dat I used somefere elss, but since it might
% be off a cheneral interest, I'fe decided to make it a separate
% fink\ldots\par
% The \fink{} package is \packagecopyright{}, and distributed under the terms
% of the LPPL license.
%
% \section{User Interface}
% To use the package, simply say |\usepackage[|\meta{options}|]{fink}| in the
% preamble of your document. This will do everything for you. Available
% options will be described when appropriate.
%
% \subsection{Retrieving the current file's name components}
% \begin{macro}{\finkdir}
%   \begin{macro}{\finkbase}
%     \begin{macro}{\finkext}
%       The file currently being processed is described by the macros
%       |\finkdir|, |\finkbase| and |\finkext| which expand (as you may have
%       guessed) to the directory, base name (sans extension), and extension
%       of the file.
%     \end{macro}
%   \end{macro}
% \end{macro}
% \begin{macro}{\finkfile}
%   \begin{macro}{\finkpath}
%     Additionally, the macro |\finkfile| is defined to be
%     |\finkbase|.|\finkext| (as in previous versions), and the macro
%     |\finkpath| (new in version 2.0) is defined to be |\finkdir\finkfile|.
%     Feel free to use these macros in your sources.
%   \end{macro}
% \end{macro}
%
% \subsection{Main file's name components}
% \begin{macro}{maindir}
%   \begin{macro}{mainext}
%     Because there's no way \TeX{} can give you back information about the
%     file being processed (apart from its base name), \fink{} provides the
%     options |maindir| (defaults to |./|) and |mainext| (defaults to |tex|)
%     for changing the directory and the extension of the main source file.
%     For instance, suppose your source file is in |src/foo.ltx| and you are
%     compiling in |pdf/|. You can then use the package as follows:
% \begin{verbatim}
% \usepackage[maindir=../src,mainext=ltx]{fink}
% \end{verbatim}
%   \end{macro}
% \end{macro}
%
% \section{\auctex{} support}
% \auctex{} is a powerful major mode for editing \TeX{} documents in
% \textsf{Emacs} or \textsf{XEmacs}. In particular, it provides automatic
% completion of macro names once they are known. \fink{} supports \auctex{}
% by providing a style file named \texttt{fink.el} which contains \auctex{}
% definitions for the relevant macros. This file should be installed to a
% location where \auctex{} can find it (usually in a subdirectory of your
% \LaTeX{} styles directory). Please refer to the \auctex{} documentation for
% more information on this.
%
% \section{Caveat}
% \fink{} cannot follow files included with the \TeX{} |\input| primitive.
% That's because \TeX{} has a very insensible way of defining primitives whose
% argument parsing syntax is not available for macros. As a consequence, it's
% almost impossible to redefine the |\input| primitive without breaking its
% syntax (one would have to parse the characters one by one, and I'm not ready
% to do so\ldots). \fink{} currently does not follow auxiliary files either.
%
% \section{Hints, Tricks, Tips}
%
% \subsection{File names with special characters}
% Here, ``special'' is to be taken in the \LaTeX{} sense, for instance, a
% directory or file name containing an underscore. If this situation occurs,
% you're likely to face problems with \fink{} macros because they don't try to
% properly escape those characters. So for instance, an underscore alone will
% make \LaTeX{} think that you forgot the math mode |$| sign before it. There
% are actually two problems that you may encounter:
% \begin{description}
% \item[Characters not displayed properly] Try to change your font encoding by
%   putting this in your document's preamble: |\usepackage[T1]{fontenc}|.
% \item[Compilation breakage] The |url| package might be of some help here.
%   Put |\usepackage{url}| in your document's preamble first. Then (assuming
%   that |\finkfile| is the culprit), instead of using |\finkfile| directly,
%   use this instead: |\expandafter\url\expandafter{\finkfile}|. You might
%   also want to play with |\urlstyle| to have your file name displayed in
%   the font you prefer.
% \end{description}
%
% \section{Changes}
% \begin{itemize}
% \item[v2.1.1] Fix trailing whitespace in |\fink@restore|, reported by
%   Maverick Woo\\
%   Added some hints about filenames with special characters, suggested by
%   David P. Goodall
% \item[v2.1] Fix bug preventing expansion in math mode, reported by Alain
%   Schremmer, fixed by Morten Hoegholm before I could even raise my little
%   finger.
% \item[v2.0] New macros |\finkdir|, |\finkbase|, |\finkext| and |\finkpath|
%   suggested by Alain Schremmer\\
%   New options |mainext| and |maindir|, use |kvoptions| for options
%   management
% \item[v1.2] Fixed conflict with |\includegraphics|, reported by Jim Crumley
% \item[v1.1] Fixed missing 3rd arg to |\PackageError| call from
%   |\finkextension|
% \end{itemize}
%
% \StopEventually{\par Well, I think that's it. Enjoy using \fink{}!
%   \vfill\hfill\small \packagecopyright{}.}
%
% \section{The Code}
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{fink}[2008/02/27 v2.1.1
                       Keep track of the current filename]

\RequirePackage{kvoptions}
\SetupKeyvalOptions{family=fnk,prefix=fnk@}

%    \end{macrocode}
%
% \subsection{Main file initial settings}
% \DescribeEnv{maindir}
% \DescribeEnv{mainext}
%    \begin{macrocode}
\DeclareStringOption[\@currdir]{maindir}
\DeclareStringOption[tex]{mainext}

%    \end{macrocode}
% The following is for backward compatibility only (not documented anymore).
% It provides support for the old |tex| and |ltx| options (still functionnal),
% and for the |\finkextension| macro. However, this macro is now defined to
% trigger an error, begging the user to use the new option instead.
%    \begin{macrocode}
\newcommand*\@fink@mainext[1]{\setkeys{fnk}{mainext={#1}}}
\newcommand*\fink@mainext{%
  \expandafter\@fink@mainext\expandafter{\CurrentOption}}
\DeclareVoidOption{tex}{\fink@mainext}
\DeclareVoidOption{ltx}{\fink@mainext}

\newcommand*\finkextension[1]{%
  \PackageError{FiNK}{%
    \protect\finkextension\space shouldn't be used anymore.\MessageBreak
    Please use the `mainext' package option instead.}{%
    No big deal right ?\MessageBreak
    Type X to quit and modify your source.}}
\@onlypreamble\finkextension

\ProcessKeyvalOptions*

%    \end{macrocode}
%
% \subsection{File's name components macros}
% \begin{macro}{\finkdir}
%   \begin{macro}{\finkbase}
%     \begin{macro}{\finkext}
%       \begin{macro}{\finkfile}
%         \begin{macro}{\finkpath}
%           We declare the user-level macros here. |\fink@file| is used to
%           compute file names, possibly with no extension.
%       \end{macro}
%       \end{macro}
%     \end{macro}
%   \end{macro}
% \end{macro}
%    \begin{macrocode}
\newcommand*\finkdir{\fnk@maindir}
\newcommand*\finkbase{\jobname}
\newcommand*\finkext{\fnk@mainext}

\newcommand*\finkfile{}
\newcommand*\fink@file[2]{#1\ifx\\#2\\\else.#2\fi}
\xdef\finkfile{\fink@file{\jobname}{\fnk@mainext}}

\newcommand*\finkpath{}
\xdef\finkpath{\finkdir\finkfile}

\PackageInfo{FiNK}{main file set to "\finkpath"}

%    \end{macrocode}
%
% \subsection{Commands overriding}
% \begin{macro}{\fink@prepare}
%   This macro prepares the name of next file to be input. We arrange to setup
%   a complete filename, including directory and extension.
%
%   As of version 1.2, this macro performs in a group of its own. This fixes a
%   problem that appeared when using |\includegraphics| with a filename with an
%   explicit extension. |\includegraphics| calls |\filename@parse| itself, so
%   it is important that the same call in |\fink@prepare| only have a local
%   effect, just the time to compute the new values for the |\fink@next*|
%   macros.
% \end{macro}
%    \begin{macrocode}
\newcommand*\fink@prepare[1]{%
  \begingroup%
    \filename@parse{#1}%
    \xdef\fink@nextdir{%
      \ifx\filename@area\@empty%
        \fnk@maindir%
      \else%
        \fnk@maindir\filename@area%
      \fi}%
    \xdef\fink@nextbase{\filename@base}%
    \xdef\fink@nextext{\ifx\filename@ext\relax tex\else\filename@ext\fi}%
    \xdef\fink@nextfile{\fink@file{\fink@nextbase}{\fink@nextext}}%
    \xdef\fink@nextpath{\fink@nextdir\fink@nextfile}%
  \endgroup}

%    \end{macrocode}
% \begin{macro}{\fink@input}
%   \begin{macro}{\fink@restore}
%     These macros are defined for a convenient use of |\expandafter|. They
%     save and restore the current filename. Remember that |\@@input| is
%     \LaTeX's redefinition of the \TeX{} input primitive.
%   \end{macro}
% \end{macro}
%    \begin{macrocode}
\newcommand*\fink@input{%
  \xdef\finkdir{\fink@nextdir}%
  \xdef\finkbase{\fink@nextbase}%
  \xdef\finkext{\fink@nextext}%
  \xdef\finkfile{\fink@nextfile}%
  \xdef\finkpath{\fink@nextpath}%
  \@@input\@filef@und}
\newcommand*\fink@restore[1]{%
  \begingroup%
    \filename@parse{#1}%
    \xdef\finkdir{\filename@area}%
    \xdef\finkbase{\filename@base}%
    \xdef\finkext{\filename@ext}%
    \xdef\finkfile{\fink@file{\finkbase}{\finkext}}%
    \xdef\finkpath{\finkdir\finkfile}%
  \endgroup}

%    \end{macrocode}
% Note: in earlier versions, we redefined |\IfFileExists| to prepare the
% name of the next file, but this is bad because it can be used outside of
% \fink{}'s scope. We also redefined |\@input|, but neither |\include| nor
% |\input| use it.
% \begin{macro}{\InputIfFileExists}
%   \LaTeX's |\input| and |\include| commands use |\InputIfFileExists|, so
%   let's redefine it here:
% \end{macro}
%    \begin{macrocode}
\long\def\InputIfFileExists#1#2{%
  \IfFileExists{#1}{%
    #2\@addtofilelist{#1}%
    \fink@prepare{#1}%
    \expandafter\fink@input%
    \expandafter\fink@restore\expandafter{\finkpath}}}

%    \end{macrocode}
%
% ^^A \PrintChanges
% ^^A \PrintIndex
% \Finale
%
% ^^A fink.dtx ends here.