summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex')
-rw-r--r--Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex325
1 files changed, 0 insertions, 325 deletions
diff --git a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex
index 59484968382..91234d2b73c 100644
--- a/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex
+++ b/Master/texmf-dist/doc/latex/nicetext/docsrc/fifinddo.tex
@@ -1,650 +1,325 @@
\ProvidesFile{fifinddo.tex}[2010/03/23 documentation for `fifinddo']
-
\title{\textsf{fifinddo}\\---\\Filtering \TeX(t) Files by \TeX}
-
\author{Uwe L\"uck\,---\,{\tt http://contact-ednotes.sty.de.vu}}
-
% \listfiles
-
\documentclass{article}
-
\usepackage{makedoc}
-
% \usepackage{substr} %% for failure examples TODO 2010/03/17
-
\input{makedoc.cfg}
-
\begin{document}
-
\maketitle
-
-
\begin{flushright}\small\it FIDO, FIND!\\or:\\FIND FIDO!\\oder:\\FIFI,
-
SUCH!\end{flushright}
-
\begin{abstract}\noindent\hspace{1sp}%% for niceverb-apostrophe
-
'fifinddo' starts implementing parsing of plain text or \TeX\ files
-
using \TeX, generalizing the philosophy behind 'docstrip',
-
based on how \TeX\ reads macro arguments.
-
Rather than typsetting the edited input stream immediately,
-
results are written to another file,
-
in the first instance as input for \TeX.
-
Rather than presenting a ``complete study" of a computer-scientific
-
idea, it aims at practical applications.
-
The main one at present is '\mbox{makedoc}' which removes certain comment
-
marks from package files and inserts listing commands.
-
Parsing macros are not defined anew at every input chunk,
-
but once before a file is processed.
-
This also allows for \emph{expandable} sequences of replacements,
-
e.g., with `txt'$\to$\TeX\ functionality.
-
The method of testing for substrings is carefully discussed,
-
revealing an earlier mistake (then) shared with 'substr.sty'
-
and \LaTeX's internal `\in@'.
-
\end{abstract}
-
\tableofcontents
-
-
\section{Introduction: The Gnome of the Aim}
-
\subsection{Parsing by \TeX---are you mad?}
-
The package name 'fifinddo' is a &\listfiles-compatible abbreviation
-
of \lq file-find-do\rq\footnote{\lq file\rq\ possibly for ``searching
-
\TeX(t) files" (I don't remember my thoughts!),
-
while there were requests for doing replacements on
-
\LaTeX\ \emph{environments} on 'texhax'. However, the package might
-
be enhanced in this direction $\dots$ so the name may be wrong
-
$\dots$ but now I like it so much .\,.\,. Or the reason was that
-
results are written to a \emph{separate file}, not typeset
-
immediately.---Let me also mention that \emph{\lq Fifi\rq} (as the
-
package name starts) is a kind of German equivalent to the
-
``English" \emph{\lq Fido\rq}, or may have been.}
-
(or think of \lq if found do\rq).
-
'fifinddo' implements (or aims at) general parsing
-
(extracting, replacing [converting], expanding, \dots)
-
using \TeX\ where 'texhax' posters strongly urge to use 'sed',
-
'awk', or 'Perl'.
-
'fifinddo''s opposed rationales are:
-
\begin{itemize}
-
\item It works instantly on any \TeX\ installation.
-
(\emph{Restrictions:} Some \TeX\ versions &\write certain hex
-
codes for certain characters, cf.\ \TeX book p.~45,
-
I have seen this with PC\TeX. However, some applications of
-
'fifinddo' are nothing but technical steps where you will read
-
the result files rarely anyway.
-
%% And I have not yet explored extended encodings.)
-
%% <- done meanwhile 2010/03/22
-
\item You can apply and customize it like any \TeX\ macros, knowing
-
just \TeX\ (or even only the documentation of some user-friendly
-
extension of 'fifinddo'), without the need of learning any
-
additional script language.
-
\item The syntax of usual utilities (e.g., ``wildcards")
-
is sometimes difficult with \emph{\TeX} files
-
with all their backslashes, square brackets, stars,
-
question marks \dots
-
\end{itemize}
-
%
-
At least the first item is just the philosophy of the 'docstrip' program,
-
standard for installing \TeX\ packages;
-
and while I am typing this, I find at least 14 other similar packages
-
in J\"urgen Fenn's \emph{Topic Index} of the \emph{\TeX\ Catalogue:}
-
% \begin{quote}\small
-
\[\texttt{%
-
% \hbox\bgroup\url{% %% \url impossible!? 2010/03/19
-
http://mirror.ctan.org/help/Catalogue/bytopic.html\string#parsingfiles}%
-
\footnotemark
-
% \egroup\]
-
\]
-
\footnotetext{%
-
\href{http://mirror.ctan.org/help/Catalogue/bytopic.html\string#parsingfiles}%
-
{Click here!}}
-
% \end{quote}
-
(Some of them may have been \emph{reactance} to 'texhax' and other
-
postings urging not to try something like this; some seem just to be
-
celebrations of the power of \TeX---yes, celebrate!)
-
-
Actually, \TeX's mechanism of collecting macro arguments is hard-wired
-
parsing at quite a high level. \LaTeX\ hides this from
-
``simple-minded" users by a convention \emph{not} to use that full
-
power of \TeX\ for \emph{end-user macros}.
-
\emph{Internally}, \LaTeX\ \emph{does} use it in reading
-
lists of options and file dates as well as to implement certain
-
`FOR'- and `WHILE'-like loop programming structures.
-
\LaTeX's `\in@'/`\ifin@' construction is an implementation of a
-
``<string1> occurs in <string2>" test. More packages seem to use
-
this idea for extracting file informations, like
-
'texshade'.\footnote{\url{http://ctan.org/pkg/texshade}}
-
-
-
However, such packages don't make much ado about parsing,
-
there seems to be no general setup mechanism as are presented by
-
'fifinddo'. Indeed, tayloring parsing macros to specific applications
-
may often be more efficient than a general approach.
-
-
\subsection{Useful for \dots}
-
My main application of 'fifinddo' at present is typesetting
-
documentations of packages using 'makedoc' which removes certain
-
percent marks and inserts listing commands, so you edit a package file
-
with as little documentation markup as possible.
-
This may be extended to other kinds of documents as an alternative
-
to 'easylatex' or 'wiki' (the approach of which is dangerous and
-
incompatible with certain other things).
-
-
I have used a similar own package 'txtproc' successfully,
-
where more features were implemented for practical purposes
-
than are here so far, yet I don't like its implementation, want to
-
improve it here. This package also \emph{created batch files}, e.g.,
-
to remove temporary files.
-
This could be used for package handling:
-
typset the documentation at the desired place in the tree,
-
write the packages to another, write a batch file to remove
-
files that are not needed any more after installation
-
(cf.\ 'make'). %%% !? cf. Wiki `Make (software) 2009/04/11
-
-
I used 'txtproc' also for \emph{large-scale substitutions}
-
(it had been decided to change the orthography in a part of a book).
-
Other large-scale substitutions may be:
-
\begin{itemize}
-
\item inserting &\index commands;
-
\item inserting (soft) hyphenation commands near accents;
-
\item manual umlaut-conversion.\footnote{If you know the ``names"
-
of the encodings, Heiko Oberdiek's
-
\ctanpkgref{stringenc}
-
may be preferable.}
-
\item typographical (or even orthographical) corrections (same mistake
-
many times on each of hundreds of pages).
-
You may turn `...' into `$\dots$' and `etc.' into `etc.\'
-
etc.\footnote{But what when a new sentence is starting indeed?
-
Well, `cf.' is an easier example.---`etc.' even showed
-
a problem in 'niceverb'. 'mdoccorr.cfg' replaces `etc. '
-
only, so you can keep the extra space by a code line break.}
-
This could replace packages like
-
'easylatex',\footnote{\url{http://ctan.org/pkg/easylatex}}
-
'txt2latex',\footnote{\url{http://ctan.org/pkg/txt2latex}}
-
'txt2tex'\footnote{\url{http://ctan.org/pkg/txt2tex}}
-
in a customizable way, using, e.g., the ``correct"
-
hook from 'makedoc.sty' as exemplified in 'mdoccorr.cfg'
-
(see examples section of 'makedoc.pdf').
-
You should find 'fdtxttex.tpl', a 'fifinddo' script
-
to try or apply `\MakeDocCorrectHook' from 'mdoccorr.cfg',
-
as well as 'fdtxttex.tex' that runs a dialogue for the
-
same purpose if you can manage to run it ('WinShell'?).
-
You can then try to create your own `\MakeDocCorrectHook'.
-
Section~\ref{sec:replchain} provides setup for macros
-
of this kind.
-
\item as to 'easylatex' again, \emph{lists} could be detected and
-
transformed into \LaTeX\ list commands. This could re-implement
-
the lists functionality of 'wiki.sty' that is somewhat
-
dangerous. %% TODO 2009/04/15
-
\item introduce your own \emph{shorthands} to be expanded not as \TeX\ macros,
-
but by text substitution;
-
\end{itemize}
-
%% % <- TODO present macros/"jobs" doing this.
-
%% %% <- TOOD single quote tests could be used for
-
%% double quote character as well
-
%% to turn it into left quotes if ... 2010/03/19
-
%
-
In certain cases, insertions deteriorate readability, hyphenation
-
corrections even make text search difficult.
-
It is therefore suggested to
-
\begin{enumerate}
-
\item keep editing the file without the insertions,
-
\item run the script (commands based on 'fifinddo') for insertions
-
in the preamble of the main file
-
(```\jobname.tex'", maybe &\input the script file) and
-
\item &\input the result file within the `document' environment.
-
\end{enumerate}
-
-
In general, differences to ``manual" replacing by the substitution
-
function of your \emph{text editor} is that
-
\begin{itemize}
-
\item you first keep the original version,
-
\item you can check the resulting file before you replace the original
-
file by it,
-
\item you can store the replacement script in order to check for
-
mistakes at a later stage of your work,
-
\item you can do \emph{all} the replacements in \emph{one run}
-
(by \emph{one} script to check for mistakes),
-
\item you can store replacement scripts for future applications,
-
so you needn't type the patterns and replacement strings anew.
-
\end{itemize}
-
-
-
\subsubsection{Comparisons} %% was `Missing' 2010/03/18
-
% \subsection{To implement or not to implement \dots} %% TODO!? 2009/04/13
-
% Actually, 'fifinddo' doesn't implement very much, and this possibly
-
% won't change, even if I am lucky. ``Practical applications" tend to
-
% show (in my view) that there is a very complex space of possibilities
-
% what parsing macros could do. If I try to ``attack" 'Perl' or so,
-
% cf.\ 'CPAN'\@. If I am lucky and become famous, 'fifinddo' will get many
-
% extensions in separate packages, cf.\ 'pstricks'. I also like it when
-
% you can choose among packages for similar purposes, and this may apply
-
% to extensions of 'fifinddo' as well.
-
%
-
% What \emph{really} is missing very badly at present is matching
-
% \emph{sequences} of strings. However, 'makedoc' contains a practical
-
% application of this for the case that both strings appear \emph{in the same
-
% line}. A better algorithm would have to read more lines from the input
-
% file etc.
-
%
-
% As it just comes to my frightened mind, there is even a problem with
-
% ``strings"/``patterns" that are \emph{phrases} of words, containing
-
% spaces \dots
-
%
-
% Clearly much comfort concerning \emph{routine} jobs is missing now,
-
% 'txtproc' has more. Please sponsor (or otherwise support) the work for
-
% improving this.
-
%
-
It should be noted (perhaps here) that the present approach to parsing
-
is a quite \emph{simple} one and in this respect much different to the
-
string handling mechanisms of
-
'stringstrings',\footnote{\url{http://ctan.org/pkg/stringstrings}}
-
'ted',\footnote{\url{http://ctan.org/pkg/ted}}
-
'xstrings'\footnote{\url{http://ctan.org/pkg/xstrings}}
-
(as I understand them, perhaps also
-
'coolstr'\footnote{\url{http://ctan.org/pkg/coolstr}})
-
which are \emph{much more powerful} than what is offered here---but
-
perhaps slow and for practical applications possibly replaceable by
-
the present approach.
-
\emph{Expandable replacement} seems not to exist outside 'fifinddo'
-
(2009/04/13).
-
-
Much is missing, I know.\footnote{There
-
is more in my badly implemented 'txtproc.sty'.}
-
I am just implementing what I actually need
-
and what could show that this approach is worth being pursued.
-
%% removed 2010/03/18:
-
% It may need being sponsored or otherwise supported.
-
-
\subsection{For insiders}
-
-
\emph{Warning:} You may (at least at the present state of the work)
-
have little success with this package, if you don't know about
-
\TeX's category codes and how \TeX\ macros are defined.
-
The package rather provides tools for package writers.
-
You may, however, be able to run other packages which just load
-
'fifinddo' as required background.
-
-
That 'fifinddo' acts on ``\TeX(t)" files or so means that
-
(at present) I think of applications on ``plain text" files which
-
will usually be \TeX\ input files. ``At present" they are read
-
without ``special characters," so essentially category codes of input
-
characters are either 11 (``letter") or 12 (``other").
-
This way some things are easier than with usual \TeX\ applications:
-
\begin{enumerate}
-
\item You can ``look into" curly braces and ``behind" comment characters.
-
\item There are exact or safe tests especially of \emph{empty macro arguments}
-
that are ``expandable," i.e., they are ``robust,"
-
don't need assignments, can be executed in `\write'ing and in
-
`\edef' definitions. ``Usually," the safe way to test emptiness
-
is storing a macro argument as a macro, say `\tempo', in order
-
to test `\ifx\tempo\empty' where `\empty' has been defined
-
by `\def\empty{}' in the format. But this requires some
-
`\def\tempo{#<n>}' which breaks in ``mere expanding"
-
(\TeX\ \emph{evaluates} `\tempo' instead of defining it).
-
An \emph{expandable} test on emptiness is, e.g. `\ifx$#<n>$',
-
where we hope that it becomes `\iftrue' just if macro argument
-
`#<n>' is empty indeed. However, ``usually" it may \emph{also}
-
become `\iftrue' when `#<n>' starts with `$'---if the latter
-
has category code 3 (``math shift"). But 'fifinddo' does
-
not assign category code 3 to any character from the input file!
-
Therefore `\ifx$#<n>$' is `\iftrue' \emph{exactly} if `#<n>' is
-
empty.
-
\item You can avoid interference with packages that are needed for
-
typesetting. You can do the ``preprocessing" in one run with
-
typesetting, but you should do the preprocessing before you
-
load packages needed for typesetting. One may even try to keep
-
the macros and settings for preprocessing local to a group.
-
\end{enumerate}
-
%
-
Once there may be an option to read input with some usual \TeX\
-
category codes as well, it may be useful to (some of)
-
\begin{itemize}
-
\item avoid matching substrings of control words,
-
\item skip blank spaces as \TeX\ does it usually,
-
\item catch \emph{balanced} input pieces,
-
\item ignore comments,
-
\item ignore certain characters.
-
\end{itemize}
-
-
The essential approach of 'fifinddo' to looking for single strings is
-
described in some detail in section~\ref{sec:theory}.
-
-
The implementation of 'fifinddo' is as follows.
-
User commands are specially highlighted (boxed\slash coloured),
-
together with their syntax description.
-
-
% \end{document}
-
-
\section{Preliminaries}
-
\subsection{Head of file (Legalese)}
-
\sloppy
-
\ProcessLineMessage{}
-
\MakeInputJobDoc{23}{\SectionLevelTwoParseInput}
-
\end{document}
-
-
TODO cf. Kastrup 'makematch' and others 2009/04/09
-
-
2009/04/10: title break, by -> with(!?); `boxed/coloured'
-
2009/04/12: useful: own shorthands
-
2009/04/13: substr.sty, \emph{expandable}, w/o `implement'!?
-
2009/04/15: same with \in@
-
2010/03/08: EPS application removed
-
2010/03/17: use \MakeInputJobDoc
-
2010/03/18: `Missing' -> `Comparisons' etc.; \Require...
-
2010/03/19: Catalogue \url; '' -> "
-
2010/03/20: \ctanpkgref
-
2010/03/22: debugging; done ...
-
2010/03/23: more URLs; abstract "then shared";
-
removed dates from 2009, fdtxttex.tex/tpl
-