% vim:tw=74:
\section{Ferramentas Auxiliares}
Para a realização deste projecto foram necessárias algumas ferramentas
auxiliares. Na sua maioria são simples scripts \ac{Perl} pelo que
dispensa-se a sua apresentação. Contudo, foi criada uma ferramenta relevante para o trabalho -- \textbf{chron\_extract} -- apresentando-se de
seguida a sua explicação.

\subsection{Chron Extract}\label{chronExtract}
Um dos problemas que surge após a implementação de um sistema qualquer, é
arranjar dados que o façam adequar à realidade. Muitas
vezes, este processo de inserção de dados é feito de uma forma parcial 
ou totalmente manual (sempre que a informação se encontra em formatos não
digitais, por exemplo). Contudo, tirando partido das potencialidades que a
Web nos oferece, já é possível obter um grande volume de dados em
formato digital. 

Como já foi dito na secção \ref{teoriaExtraccao}, a extracção de informação não é uma
tarefa simples devido ao estado que se encontra a maioria das páginas
Web. Contudo, ainda que não se consiga extrair toda a informação
disponível, pode-se sempre extrair alguma, completando-se os
restantes dados de uma forma manual.

Foi a pensar nos historiadores e outros potenciais utilizadores da
linguagem \emph{chronl} que se decidiu desenvolver esta ferramenta a fim
de que facilite a extracção de cronologias já disponíveis na Web.

\subsubsection{Descrição}
Chron\_extract é uma script feita em \ac{Perl} para extrair cronologias 
a partir de páginas web. Utilizando o módulo \texttt{Template::Extract}, 
esta script reconhece informação presente em documentos \ac{HTML}, gerando
ficheiros \emph{chronL} que são interpretados pelo módulo Chronology. A sua
utilização passa apenas por etiquetar o documento \ac{HTML} que contém a
informação e escrever um ficheiro de configuração onde são indicados os
blocos de informação a extrair.

\subsubsection{Invocação}
A invocação desta script processa-se da seguinte forma:

\begin{verbatim}
chron_extract.pl [OPTIONS] ficheiro.html
\end{verbatim}

A secção \textbf{OPTIONS} é do tipo ``chave valor'' em que as chaves e
valores possíveis são:

\begin{itemize}
\item \textbf{debug 1|2|3|4}
Permite especificar o nível de debug que se pretende. Existem 4 níveis de
debug (de 1 a 4). A secção \ref{debug}, explica em detalhe, cada um destes
níveis.

\item \textbf{config conf\_file}
Permite indicar o \emph{path} para o ficheiro de configuração. Omitindo
esta opção, é utilizado  o ficheiro ./config\_extract para leitura das
configurações. 

\item \textbf{year yyyy}
Permite indicar o ano da cronologia. Esta opção é útil sempre que todos os
eventos a extrair ocorreram num mesmo ano.

\item \textbf{month mm}
Permite indicar o mês - em formato numérico - da cronologia. Esta opção
é útil sempre que todos os eventos a extrair ocorreram num mesmo mês.

\item \textbf{outfile file.cl}
Permite especificar um ficheiro chronL para guardar a informação gerada.
Por omissão, a saída do programa é enviada para a \emph{stdout}.

\item \textbf{validate true|false}
Permite fazer uma validação final do código chronl gerado. Por omissão, o
valor é true.
\end{itemize}

Notas em relação à invocação da script:

\begin{enumerate}
\renewcommand{\labelenumi}{\roman{enumi}}
\item A ordem pela qual são especificadas as várias \emph{OPTIONS} é
irrelevante. Contudo, o path para o ficheiro deverá ser sempre o último
argumento. Nunca poderá vir no bloco de \emph{OPTIONS}.

\item As opções \emph{year} e \emph{month}, sendo especificadas, têm
prioridade sobre uma string para captar o mês ou o ano no meio do texto.
Dada a facilidade com que são passadas estas opções, recomenda-se
fortemente a sua utilização no caso de todos os eventos da cronologia
extraída terem ocorrido num mesmo ano e/ou mês.
\end{enumerate}

\subsubsection{Ficheiro de Configuração}
É composto por um conjunto de blocos separados por uma linha tracejada
(\verb+-------+). Cada bloco é constituído necessariamente por 3 campos:
\textbf{block} (nome do bloco), \textbf{type} (tipo do bloco) e
\textbf{format} (formato do bloco).

\begin{itemize}
\item \textbf{block}
Nome do bloco a extrair. É especialmente importante porque vai permitir
identificar um dado bloco no documento \ac{HTML}. 

Existem vários blocos possíveis:

\begin{enumerate}
\renewcommand{\labelenumi}{\roman{enumi}}
\item \textbf{NAME (tipo String)}
nome da cronologia 

\item \textbf{IDCHRON (tipo String)}
identificador da cronologia 

\item \textbf{EVENTS (tipo Array)}
bloco de eventos que compõem a cronologia. Em cada evento, podem-se
utilizar os campos \emph{year}, \emph{month}, \emph{day}, \emph{name}, 
\emph{id} e \emph{description} referentes a
um evento. 

\item \textbf{KEYWORDS (tipo String)}
conjunto de palavras-chave da cronologia 
\end{enumerate}

\item \textbf{type}
Tipo de um bloco. Pode ser uma string se for para extrair uma frase ou um
\emph{array} se se pretender extrair um conjunto de linhas que seguem um dado
formato.

\item \textbf{format}
Formato de um bloco. Segue a sintaxe do \texttt{Template::Extract} pelo
que recomenda-se a leitura da documentação deste módulo\footnote{Consultar
página~\pageref{www}.}. Convém saber que sempre que se pretende extrair um
campo \verb+c1+ de uma frase, é necessário colocar a string \verb+[% c1 %]+
no template. Recomenda-se também que, entre dois blocos onde possa haver
espaços no documento \ac{HTML}, se inclua a etiqueta \verb+[% /\s*/ %]+. 
\end{itemize}

No caso das strings, só é admissível um campo: a própria string. O nome do
campo deverá ser igual ao do bloco mas em minúsculas. 
Nos blocos \emph{EVENTS}, existem vários campos que se podem utilizar.

Convém perceber que cada bloco é constituído por vários campos no caso dos
\emph{arrays} ou de um só campo no caso das strings. Todos os campos seguem o
seguinte esquema: \verb+[% c %]+ em que ``c'' é o nome do campo.

Na Tabela~\ref{tab:blocos} apresentam-se os campos que se podem utilizar    
em cada bloco.

\begin{table}[!hbtp]
\begin{center}
\begin{tabular}{|c|c|c|}
\hline
Bloco & Campos disponíveis & Descrição \\
\hline
\hline
NAME & name & Nome da cronologia \\
\hline
IDCRON & idcron & Identificador da cronologia \\
\hline
EVENTS & year, month, day, name, id e description & Dados referentes a um evento\\
\hline
KEYWORDS & keywords & palavras-chave associadas \\
& & a uma cronologia \\ 
\hline
\end{tabular}
\caption{Campos disponíveis em cada bloco}
\end{center}
\label{tab:blocos}
\end{table}

Convém também lembrar que, para os blocos \emph{EVENTS}, o formato
fornecido refere-se apenas a uma evento e não à cronologia inteira.


Exemplo de um ficheiro de configuração:

\VerbatimInput{config}

\subsubsection{Etiquetagem}

A etiquetagem do documento \ac{HTML} é muito simples. Basta colocar
\verb+<!--BEGIN nome_bloco-->+ e \verb+<!--END nome_bloco-->+ no início e
fim de cada bloco.

Recomenda-se que, no caso de blocos do tipo \emph{String} a etiqueta 
\textbf{BEGIN} e \textbf{END} seja colocada imediatamente antes e depois
do texto a extrair. No caso do tipo \emph{Array}, recomenda-se que se crie
uma nova linha quer para a etiqueta BEGIN quer para a etiqueta END. 

A etiqueta BEGIN como a END, estão em comentário HTML pelo que a sua
colocação nos documentos não altera a forma como eles são visualizados
pelos browsers. 

\subsubsection{Debug}
\label{debug}

Através da opção \emph{debug}, é possível obter informação adicional sobre
o comportamento da script. Pode ser muito útil no caso da ocorrência de erros.

Existem 4 níveis de debug:

\begin{enumerate}
\item nível mínimo de debug (valor por omissão)

\item é feito um \emph{dump} da estrutura que armazena a informação extraída

\item além do que é feito nos níveis anteriores, são mostradas todas as
expressões regulares utilizadas na processo de extracção. Note-se que esta
informação é gerada pelo módulo Template::Extract.

\item mostra apenas o ficheiro html normalizado (antes de ser processado)
\end{enumerate}

Toda a informação de debug é enviada para a \emph{stderr}.

Aconselha-se que quando se utilize a opção \emph{debug}, seja também utilizada a
opção \emph{outfile} para se poder distinguir a informação de debug com o código
chronL gerado.

\subsubsection{Validação}

O chron\_extract não garante que o ficheiro gerado esteja de acordo com a
gramática do chronL. Em muitos casos, o código gerado constitui apenas uma
aproximação que deverá ser revista e completada pelo utilizador. Assim,
existe uma opção validate que por omissão está activada e que valida o
ficheiro gerado. Desta forma, o utilizador fica com uma ideia do estado da
cronologia gerada.

\subsubsection{Exemplo}

Como exemplo, está disponível um documento Html contendo uma cronologia
das invasões francesas em 1807 (\verb+inv1807.html+) e o ficheiro de configuração
(\verb+config\_extract\_1807+).

Invocando:
\begin{verbatim}
$./chron_extract.pl config config_extract_1807 outfile inv1807.cl year \
1807 inv1807.html
\end{verbatim}

produziria o seguinte output

\begin{verbatim}
Block NAME is correctly extracted
Block KEYWORDS is correctly extracted
Block EVENTS is correctly extracted

Examinating the generated file...
The file is valid with the chronl grammatic
\end{verbatim}

Uma nota final para dizer que a script chron\_extract está documentada sob
a forma de \ac{POD}. Para obter uma versão \ac{HTML} da documentação basta
invocar o \emph{pod2html}

\begin{verbatim}
pod2html chron_extract.pl > pod.html
\end{verbatim}

e consultar o ficheiro \emph{pod.html} gerado.
