\documentclass[11pt]{article}
\usepackage{geometry}
\geometry{letterpaper}
\usepackage[utf8]{inputenc}
\usepackage{graphicx}
\usepackage{amssymb}
\usepackage{epstopdf}
\usepackage[portuges]{babel}
\DeclareGraphicsRule{.tif}{png}{.png}{`convert #1 `dirname #1`/`basename #1 .tif`.png}

\title{Corpora-Forge}
\author{José João Almeida ({\tt jj@di.uminho.pt})\\
Alberto Simões ({\tt ambs@di.uminho.pt})\\
Joana Vilas Boas ({\tt joana.vboas@gmail.com})}
\date{\today}

\begin{document}
\maketitle
\section{Arquitectura}
A arquitectura da ferramenta que estamos a desenvolver
pode ser descrita por fases. Todas as fases vão, aqui, 
ser descritas, assim como todas as {\it scripts} envolvidas
no processo de desenvolvimento da ferramenta. \\

O objectivo deste projecto consiste, essencialmente, na 
implementação de uma CGI que permita uma mais fácil e 
intuitiva forma de fazer pesquisas em {\it corpora} 
simples e paralelo. Para chegarmos ao ponto de implementação 
dessa mesma CGI, teremos de analisar e preparar cada 
{\it corpus} para ser correctamente pesquisado. \\

Vamos, então, formalizar as fases por que cada {\it corpus} 
terá de passar até ao ponto de ser devidamente pesquisado. \\

O consenso a que chegamos foi no sentido de se implementar 
um conjunto de {\it scripts} que no seu conjunto, formassem 
uma ferramenta. O que é suposto que esta ferramenta faça é 
o seguinte:
\begin{itemize}
   \item Dado um ficheiro em qualquer formato, por exemplo, 
{\tt txt}, {\tt xml} ou até {\tt pdf}, o seu conteúdo 
deverá ser atomizado ou segmentado, ou seja, cada palavra 
do ficheiro deve ser colocada por linha. Para tal, deve 
ser usada a função {\tt fsentences}, que se encontra 
no módulo {\tt Lingua::PT::PLNbase}.
   \item Depois do texto segmentado, todos os segmentos devem 
ser anotados com o lema e as características morfológicas 
de cada segmento. Para tal, deve ser usada a função 
{\tt addradical} do {\tt jspell}.
   \item Finalmente, o passo seguinte é transformar o resultado 
do passo anterior em linguagem CQP, para que, com a 
ferramenta CQP, possam ser feitas {\it queries} ao {\it corpus}.
\end{itemize}

~\\

Feita uma descrição do que queremos que a nossa ferramenta 
realize, é tempo de fazer uma breve descrição de cada 
{\it script} implementada até ao momento. \\

\subsection{\texttt{canIinstallCGI}}
\subsubsection{Objectivos da implementação}
Esta {\it script} foi desenvolvida com o intuito de 
analisar se o local onde uma determinada CGI deverá 
ser instalada está, ou não, preparado para a sua 
instalação. São objectivos desta {\it script} 
verificar se o {\it software} que ela necessita para funcionar 
correctamente está instalado e se as permissões que a 
mesma deverá ter estão a ser garantidas. 

\subsubsection{Parâmetros a receber e a devolver}
Os parâmetros que esta {\it script} deverá receber são 
dois:
\begin{description}
   \item[caminho da CGI] : este argumento é o caminho do 
local em que a CGI que queremos instalar se encontra.
   \item[caminho de directoria] : este é o segundo argumento 
e denota o caminho da directoria onde queremos instalar 
a CGI. \\
\end{description}

A forma de invocar esta {\it script} é, então, a
seguinte:\\ 

{\tt canIinstallCGI <cgiToInstall> <whereToInstall>} \\
Durante a execução da {\it script}, a mesma vai-nos 
dando um estado da situação, dando-nos informação sobre 
como está a correr a sua execução. \\

\subsection{\texttt{mkCorpus}}
\subsubsection{Objectivos da implementação}
Esta {\it script} foi desenvolvida com o intuito de 
fazer todos os passos necessários para preparar o 
{\it corpus} para ser devidamente pesquisado. Os passos 
que a {\it script} executa são o de segmentação, o de 
anotação e o de preparação para a consulta com o CQP.

\subsubsection{Parâmetros a receber e a devolver}
Os parâmetros que esta {\it script} receberá podem ser 
um ou dois. 

\begin{description}
   \item[opções] : este parâmetro é facultativo de ser 
passado. Indica quais os passos que queremos que sejam 
executados sobre o {\it corpus} a preparar. Mais tarde, 
mostraremos as opções em pormenor.
   \item[ficheiro de metainformação] : este parâmetro é 
obrigatório e contém metainformação sobre um determinado 
{\it corpus}, como sejam o nome, os ficheiros que o compõem, 
os atributos que ao mesmo dizem respeito e tags que 
serão contempladas no {\it corpus}. Mais tarde, mostraremos 
estrutura que um ficheiro deste tipo terá de ter.
\end{description}

\subsubsection{Opções a serem passadas à {\it script}}
O primeiro parâmetro que podemos, não obrigatoriamente, 
passar à {\it script} diz respeito às opções que indicam 
quais as etapas por que queremos que o {\it corpus} em 
questão passe. As possíveis opções são as seguintes: 

\begin{description}
   \item[{\tt addradical}] : com esta opção, estamos a ordenar 
a {\it script} para executar o passo de anotação de cada 
palavra contida no {\it corpus}. Esta opção usa a função 
{\tt addradical} definida no {\tt jspell}.
   \item[{\tt tokenize}] : com esta opção, estamos a ordenar 
a {\it script} para executar o passo de tokenização/segmentação, 
colocando cada palavra do {\it corpus} numa linha. Esta opção 
usa a função {\tt sentences} definida no módulo 
{\tt Lingua::PT::PLNbase}.
   \item[{\tt cqpcode}] : com esta opção, estamos a ordenar 
a {\it script} para executar o passo de preparação para a 
consulta pelo CQP. Esta opção usa a {\it script} 
{\tt tokens2cqp}, definida por nós durante o desenvolvimento 
deste projecto. 
   \item[{\it all}] : com esta opção, estamos a ordenar 
a {\it script} para executar todos os passos possíveis para 
a preparação do {\it corpus}. 
\end{description}

De notar que, dando uma destas opções à {\it script}, a mesma 
vai ignorar tudo o que o ficheiro com metainformação lhe 
indicar sobre quais os passos que deverão ser executados. \\


A forma de invocar esta {\it script} é, então, a seguinte:\\ 
{\tt mkCorpus [-addradical|-tokenize|-cqpcode|-all] <metafile>} \\

\section{Comandos auxiliares}
São várias as {\it scripts} que nos auxiliam no tratamento 
de um determinado {\it corpus}. São, elas, as descritas de 
seguida:
\begin{description}
   \item[{\tt xmlclean}] : {\it script} de limpeza de um 
{\it corpus} codificado em XML. É fundamental num ficheiro 
em XML a não existência de sinais como > e < pelo meio das 
tags. 
   \item[{\tt tokens2cqp.pl}] : {\it script} que executa a 
codificação de um ficheiro para CQP. É a responsável pelo 
processo de tranformação para CQP.
   \item[{\tt sentences}] : {\it script} que efectua a 
segmentação de um {\it corpus}. É a responsável pelo processo 
de tokenização da ferramenta. Esta {\it script} está 
implementada no módulo {\tt Lingua::PT::PLNbase}.
   \item[{\tt addradical}] : {\it script} que efectua a 
anotação de um {\it corpus}. É a responsável pelo processo 
de anotação da ferramenta. Esta {\it script} está 
implementada no módulo {\tt jspell}.
\end{description}

\section{Ficheiro YAML de metadata}
O ficheiro que contém metainformação sobre o {\it corpus} 
e que deve ser obrigatoriamente passado à {\it script} tem 
uma sintaxe muito própria, que deve ser seguida com cuidado. \\

Por cada linha do ficheiro, devemos passar pseudo-parâmetros 
à {\it script} para que a mesma funcione em conformidade com 
o que desejamos. Vamos, então, descrever cada uma das linhas 
que devemos colocar no ficheiro. 

\begin{description}
   \item[{\tt CORPUS}] : trata-se de uma espécie de macro 
que indica o nome que queremos que o {\it corpus} tenha 
quando terminar o processo de tratamento do mesmo. 
Seguido desta marca, está o nome do {\it corpus}.
   \item[{\tt FILES}] : trata-se de uma espécie de macro 
que indica os ficheiro que constituem o {\it corpus}. 
Seguido desta marca, está o conjunto dos ficheiros 
em que se dividem o {\it corpus}.
   \item[{\tt ATTRIBUTES}] : trata-se de uma espécie de 
macro que indica os atributos com que queremos que o 
{\tt jspell} muna o {\it corpus}. Seguido desta marca, 
está o conjunto dos atributos que pretendemos. 
   \item[{\tt TAGS S}] : trata-se de uma espécie de macro 
que indica as tags XML S presentes no nosso {\it corpus}. 
Seguido desta marca, está o conjunto das tags S 
presentes no {\it corpus}.
   \item[{\tt TAGS P}] : trata-se de uma espécie de macro 
que indica as tags XML P presentes no nosso {\it corpus}. 
Seguido desta marca, está o conjunto das tags P 
presentes no {\it corpus}.
\end{description}

Eis um exemplo so conteúdo que deverá aparecer num 
ficheiro com metainformação:
{\tt CORPUS: name-of-the-corpus}\\
{\tt FILES: f1,f2,f3}\\
{\tt ATTRIBUTES: alema,apos}\\
{\tt TAGS S: }\\
{\tt TAGS P: p,s,text}\\
Existe um pequeno pormenor que pode fazer toda diferença, 
em relação aos passos que serão executados sobre o 
{\it corpus}. A extensão que os ficheiros contiverem ditará 
os passos que serão realizados. Sendo assim, vamos explicar 
quais as extensões que os ficheiros devem ter para realizarmos 
este, aquele ou todos os passos. \\
Se os ficheiros tiverem a extensão {\tt token}, o passo que será 
realizado será o de anotação. Se os ficheiros tiverem a 
extensão {\tt cor}, o passo que será realizado será o de 
segmentação. Se os ficheiros tiverem a extensão {\tt rad}, o 
passo que será realizado será o de codificação em CQP. Qualquer 
outra extensão, levará a serem realizados todos os passos, pela 
sequência correcta. \\

De notar que estas extensões vão ser analisadas, apenas se 
não forem passadas opções à {\it script}. \\

É importante salientar que de todas estas macros, apenas algumas 
são obrigatórias num ficheiro deste tipo. As duas primeiras fazem 
parte dos conjunto das obrigatórias já que é fundamental que o 
{\it corpus} tenha um nome e que saibamos quais os ficheiros 
que o compõem. A macro ``ATTRIBUTES'' apesar de não ser obrigatória 
é fundamental quando fazemos a anotação do {\it corpus}. As listas 
de tags são importantes quando queremos fazer uma limpeza dos 
sinais < e > entre o XML. \\

\section{CGI}
Actualmente, a CGI implementada está, ainda, muito básica, sendo 
que é possível escolher um de vários {\it corpora} que tenhamos 
disponíveis, fazer uma pesquisa, escolhendo quantos resultados 
pretendemos que sejam devolvidos e escolhendo em que atributos 
queremos que a pesquisa assente. Está a ser devolvido o número 
total de ocorrências e as ocorrências em número escolhido 
previamente. 

\end{document}