\documentclass{article}
\usepackage[latin1]{inputenc}
\usepackage{t1enc}
\usepackage{verbatimfiles}
\begin{document}

\title{\texttt{XML::DT} -- a PERL down translation module}
\author{José João Dias de Almeida \and José Carlos Ramalho}
\maketitle
\begin{abstract}
In this paper we present a perl module \texttt{XML::DT} that can be
used to translate and transform XML documents.

Meanwhile it is good if we have simple tools to do simple tasks, easy to develop and maintain.
That is what we propose with this paper: to show a simple tool that will enable the user to 
speed up his work and to maintain it.

\texttt{XML::DT} includes some 
down translation features common to products like
\texttt{omnimark}\cite{omnimark} or \texttt{balise}\cite{balise}, and some 
features to deal with input and output of Unicode character sets.
There are some syntax resemblances to omnimark or balise but  adapted to the
usual PERL notation. 

\texttt{XML::DT} uses \texttt{XML::Parser}\cite{xmlparser} and provides a 
down translation 
function that receives a document file and a mapping between element names
and translation function, and returns a string (the translated document).

\texttt{XML::Parser} is built upon James Clark's expat C-library\cite{expat}, that is
very fast and robust.

Each element translation function receives the element contents and the 
attribute values and returns a string. The functions are written in PERL; 
they can call all the perl functions, use external modules, save values in 
databases, do all kind of nasty side effects... The idea was to build a simple 
interface to XML processing with open doors so the user can have all the
freedom he wants to hack.
Who might thinks this is a dangerous approach think about those complex problems
you had to solve and the tool you were using did not provide the necessary
operators or the necessary data structures.

Here we have a simple tool but whenever necessary you can open the door and grab all
the power of PERL data structures or PERL operators and combine those in your 
environment.

Instead of describing all the implemented features, we present a set of case
studies where the use of this module has proven useful.

\end{abstract}

\section{Introduction}
%XML is still changing a lot. This freezes commercial products, nobody wants to spend money
%and time to develop a product that becomes obsolete in the next day.
%Coming from the last XML conference we heard that 1999 will be the year.

\section{A flavor of XML::DT use}

The basic function of the module is called \texttt{dt}. The parameters
of \texttt{dt} are the document filename and a mapping of elements to
anonymous functions (perl sub). The mapping may include a "-default" function
defining a default translation function (to be used for elements out of the
mapping domain).

In order to make the code simpler to write, every function associated with an 
element name, can use the global variables
\texttt{\$c} -- contents, \texttt{\$v\{atrName\}} -- the attributes, and 
\texttt{\$q} -- the element name.

One important feature of Perl, expat and XML::Parser is that "they are all 
Unicode-aware; that is, they read encoding declarations and perform necessary
conversions into Unicode, a system for 'the interchange, processing, and 
display of the written texts of the diverse languages of the modern world'
(http://www.unicode.org). Thus a single XML document written in Perl can now
contain Greek, Hebrew, Chinese and Russian in their proper scripts."
(http://www.perl.com). 

Unfortunately many other tools and environment are not. In XML::DT a 
output encoding option ("-outputenc") is possible (but should be used just in 
special cases).

In a similar way, "-inputenc" (implemented in XML::Parser module) makes it
possible to force a input encoding type. Whenever that is
possible, user should define the input encoding in the XML file:

\begin{verbatim}
   <?xml version='1.0' encoding='ISO-8859-1'?>
\end{verbatim}

Following some examples are going to be discussed with increasing complexity.

\subsection{Extracting meta information from a paper}


Let's consider the following xml example of a simplified paper to be submitted
to a workshop:
\verbatimfile{ex/art0.xml}

The following perl program (using XML::DT) can be used to extract some
meta-information in order to build a bibliography reference in HTML like
markup:

\verbatimfile{ex/nl1}

The functions defined in lines 7 to 9 just add HTML markup to the contents
(\texttt{\$c}). Many problems can be solved with functions so simple as the
ones presented.

In line 6 we defined a general function saying that by default, each element's
content should be suppressed.

Line 5 -- forces output in ISOlatin1 (this emergency option was used to
process our names in a environment that is not totally Unicode aware. Whenever 
possible it should be avoid...). 

In line 11 \texttt{dt} translates \texttt{\$filename} based on
\texttt{\%handler} functions.

The obtained result will be:

\verbatimfile{ex/out1}

\subsection{A program to generate XML::DT processors}

In order to simplify the task of making XML::DT processors the following
"mkskel.pl" program generates the skeleton of a XML::DT processor.

The default action (actually the only one defined) makes a side-effect: it 
computes the list of elements used in a xml file.

In the end \texttt{mkskel.pl} program  writes a program associating a simple 
action to each element name found.

\verbatimfile{ex/nl2}

The default function in line 4 is called for each element in the XML file.
This default action, just stores the element name \verb!$q! in the
\verb!element! associative array. In fact a very simple perl statement.

Whenever necessary, much more complex actions can be included in the 
processing functions.

In lines 6 to 20 a perl XML::DT program is written to the output.
In lines 14 to 16 a simple processing line is written for each name 
in the \verb!element!  associative array. This simple processing line,
is suppose to be changed by the user. 

The output of \verb!mkskel.pl art.xml! is:

\verbatimfile{ex/out2}

\subsection{Making proceedings end-page}

Suppose that we have a set of papers. A proceedings book could be defined
as:

\verbatimfile{ex/proc.xml}

Now we can generate the proceedings by writing a proceedings' processor.

In order to make the example shorter we are going to discuss just the case
of making proceeding end page with the titles and the table of the 
included papers..

Note that the papers are not copied in this document; the article empty element 
just contains an attribute named "file" with the name of the XML paper document. 

The proceedings processor calls a paper's processor to do the job.

\verbatimfile{ex/nl3}

The default action (line 5) is just return the contents. Abstract of the
proceedings is ignored (line 7), and some syntactic sugar is added (lines 6 and
9).

In line 8, \verb!$v{file}! is used to obtain the value of the attribute "file". 
When an element "article" is found \texttt{dt} function is called with the
filename (from the attribute "file") and a paper's processor \verb!%p_art!
similar to the example previously presented.

The generated output was

\verbatimfile{ex/out3}

\subsection{Example 4: making keyword index}

In previous example, each paper had "keyword" tags.
In this example we will compute a richer proceedings end-page by adding a
keyword index:

\verbatimfile{ex/nl4.1}

In line 13 a side-effect was added to save the title in \verb!$tit! variable.

In line 16 we build a keyword index as an association of keyword to a string
containing the titles separated with new lines.

in line 6, we concatenate the previous solution with the result of a function
\verb!mkKeyInd()! defined in lines 19 to 22.
\verb!mkKeyInd()! returns a string containing the index text.

In this example we can see that is easy to mix simple side-effects in the 
processors in order to build other views of the document. This approach is
similar to the attributed grammars view.

The generated output was

\verbatimfile{ex/out4}

\subsection{Context}

Processing XML elements is often context dependent: the actions to do are
dependent of the parent element. In order to be possible to write context
dependent processing, two functiona are provided:

\begin{verbatim}
  ctxt(number)
  inctxt(pattern)
\end{verbatim}

\verb!ctxt(1)! returns the name of the father element;
\verb!ctxt(2)! returns the name of the grand-father element.

\verb!inctxt(pattern)! returns true if the pattern matches the context path 
  string. 

Suppose that the papers have sections with titles and contents. In order to
have the correct end-page generation, some changes are necessary.
Just the titles with parent "article" should be saved.

\begin{verbatim}
     ...
     title => sub { if(inctxt('article'))
                       {$tit=$c; "  $c";}
                    else
                       {""}
                  }
     ...
\end{verbatim}
or
\begin{verbatim}
     title => sub { if(ctxt(1) eq 'article')
     ...
\end{verbatim}

\section{The main algorithm}

The algorithm that is presented in this section is a simplification of 
real one in order to be easier to read. A Haskell like notion is used.

\verb!dt! function processes the tree resulting from parsing the file received
as an argument.

\begin{verbatim}
   dt(filename,processor)=
     let tree=Parse(filename)
     in process(tree,processor)
\end{verbatim}


\begin{verbatim}
   process(PCDATA(p), process)       = p
   process(element(e,sons), process) =
      let args = concatenate( [ process(x) | x <- sons] )
      in if(e in dom(process)) then  process[e](args)
                               else  process["-default"](args)
\end{verbatim}

Processing a PCDATA text returns the text.

Processing an element is done by:
\begin{itemize}
\item  processing its sons 
\item  concatenating their results 
\item  aplying the corresponding processor function to the previous result
\end{itemize}

\section{Conclusions and future work}

XML::DT was design to do simple tasks.
   Our experience with using and teaching XML::DT was good: it follows the 
natural structure of the documents.
 It is possible to write a XML processor with a very small perl program. 

The ability of putting a XML processor in a single perl variable is 
powerful and enables natural sub-document processing through the coexistence of
several processors in the same specification.

In this version DT returns a string. Some examples needed a different type of
result which can be done with side-effects.
Work is being done in including primitives for computing non atomic (string)
results based on DTD information.

\end{document}
