% \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.