From 00b017753b22eaa3e2616ada9188c36f4bbe80ba Mon Sep 17 00:00:00 2001
From: Henrique Varella Ehrenfried <h.v.ehrenfried@hotmail.com>
Date: Tue, 20 Nov 2018 11:57:02 -0200
Subject: [PATCH] Create a english readme

---
 .gitmodules  |   3 --
 README-pt.md | 108 +++++++++++++++++++++++++++++++++++++
 README.md    | 147 +++++++++++++++++++++++++++++++--------------------
 3 files changed, 197 insertions(+), 61 deletions(-)
 delete mode 100644 .gitmodules
 create mode 100644 README-pt.md

diff --git a/.gitmodules b/.gitmodules
deleted file mode 100644
index 46be894..0000000
--- a/.gitmodules
+++ /dev/null
@@ -1,3 +0,0 @@
-[submodule "mapping_protocols"]
-	path = mapping_protocols
-	url = git@gitlab.c3sl.ufpr.br:simcaq/mapping_protocols.git
diff --git a/README-pt.md b/README-pt.md
new file mode 100644
index 0000000..cc0e136
--- /dev/null
+++ b/README-pt.md
@@ -0,0 +1,108 @@
+# Administrador de base de dados SimCAQ/SMPPIR #
+
+Esse repositório implementa a classe DatabaseTable e funções para verificar pareamento entre
+diferentes anos inseridos no banco de dados. A ferramenta é desenvolvida em Python 3, e usa
+como base arquivos de mapeamento em formato CSV.
+
+Para a utilização a partir da linha de comando, a CLI manage.py pode ser utilizada sem
+que se invoque manualmente as funções a partir da linha de comando Python.
+
+## Requisitos ##
+
+O utilitário foi desenvolvido em Python 3 usando a biblioteca SQLAlchemy com vistas ao banco
+de dados MonetDB. Versões futuras podem ter modificações visando a compatibilidade com outros
+bancos de dados, aproveitando as capacidades da biblioteca base.
+
+Para a instalação dos requisitos conforme usados durante o desenvolvimento, o arquivo
+requirements.txt pode ser usado como base (Recomenda-se o uso de um ambiente virtual).
+
+```bash
+(env) $ pip install -r requirements.txt
+```
+
+A CLI depende do módulo manage.py. Demais dependências serão listadas a seguir.
+
+### Requisitos para a interface com a base de dados ###
+
+* pymonetdb
+* SQLAlchemy
+* sqlalchemy-monetdb
+
+### Requisitos para geração de pareamentos ###
+
+* numpy
+* pandas
+* xlrd
+* XlsxWriter
+
+## Interface de linha de comando ##
+
+A invocação da CLI utiliza o padrão do pacote manage.py, que é:
+
+```bash
+$ python manage.py [commando] [argumentos posicionais] [argumentos opcionais com valor]
+```
+
+Os comandos já implementados são:
+
+* create: Cria a tabela conforme definido no protocolo de mapeamento.
+
+```bash
+$ python manage.py create <nome da tabela>
+```
+
+O único argumento usado é o nome da tabela. O script procurará por um protocolo de
+mapeamento com o mesmo nome para a busca do esquema das colunas.
+
+* insert: insere um arquivo de dados em formato CSV ou similar em uma tabela existente.
+
+```bash
+$ python manage.py insert <caminho para o arquivo> <nome da tabela> <ano> [--sep separador] [--null valor_nulo]
+```
+
+O caminho para o arquivo deve ser absoluto. A tabela utilizada deve existir e estar
+sincronizada com o protocolo de mapeamento correspondente. O separador padrão utilizado
+é ponto e vírgula (';'); caso outros separadores sejam utilizados pelo arquivo fonte,
+devem ser especificados com --sep (por exemplo --sep \\| para pipe). O valor nulo padrão
+é string vazia. Caso outro valor seja usado, deve ser especificado com --null.
+
+* drop: derruba uma tabela do banco de dados.
+
+```bash
+$ python manage.py drop <nome da tabela>
+```
+
+O comando não contorna chaves estrangeiras que apontem para a tabela, e o banco de dados
+pode retornar um erro caso exista alguma.
+
+* remap: sincroniza uma tabela com o protocolo de mapeamento.
+
+```bash
+$ python manage.py remap <nome da tabela>
+```
+
+Esse comando deve ser utilizado sempre que um protocolo de mapeamento for atualizado.
+
+O remapeamento permite a criação de novas colunas, derrubada de colunas existentes,
+renomeamento de colunas e mudança de tipo. Dependendo do tamanho da tabela, o uso de
+memória primária pode ser intenso.
+
+* generate_pairing_report: gera relatórios de pareamento para comparação de dados ano
+a ano.
+
+```bash
+$ python manage.py generate_pairing_report [--output xlsx|csv]
+```
+
+Os relatórios são criados na pasta pairing. Caso o formato não seja especificado,
+csv será utilizado (um arquivo será criado para cada tabela). Caso xlsx seja o formato
+utilizado, um arquivo será criado com todas as tabelas separadas em diferentes planilhas.
+
+* generate_backup: Cria/Atualiza o arquivo monitorado para o backup.
+
+```bash
+$ python manage.py generate_backup
+```
+
+O arquivo é criado ou atualizado na máquina onde o banco de dados da produção está,
+o procedimento de backup da equipe de infraestrutura o monitora para realizar o procedimento.
\ No newline at end of file
diff --git a/README.md b/README.md
index cc0e136..2e24864 100644
--- a/README.md
+++ b/README.md
@@ -1,108 +1,139 @@
-# Administrador de base de dados SimCAQ/SMPPIR #
+# HOTMapper #
 
-Esse repositório implementa a classe DatabaseTable e funções para verificar pareamento entre
-diferentes anos inseridos no banco de dados. A ferramenta é desenvolvida em Python 3, e usa
-como base arquivos de mapeamento em formato CSV.
+This repository implements the HOTMapper, a tool that allows the user to manage his historical data using a mapping protocol
 
-Para a utilização a partir da linha de comando, a CLI manage.py pode ser utilizada sem
-que se invoque manualmente as funções a partir da linha de comando Python.
+## Requirements ##
 
-## Requisitos ##
+* Python 3 (It's recommended that you use a virtual environment, such as virtualenv)
+* MonetDB (We plan to make other databases to work with HOTMapper in the future)
 
-O utilitário foi desenvolvido em Python 3 usando a biblioteca SQLAlchemy com vistas ao banco
-de dados MonetDB. Versões futuras podem ter modificações visando a compatibilidade com outros
-bancos de dados, aproveitando as capacidades da biblioteca base.
+## Installation ##
 
-Para a instalação dos requisitos conforme usados durante o desenvolvimento, o arquivo
-requirements.txt pode ser usado como base (Recomenda-se o uso de um ambiente virtual).
+----
+**NOTICE:**
+We suppose that you already have Python 3.x installed in you computer and that all the following commands that use Python will use the Python 3.x
+--
+
+1) Install virtualenv
+
+1a) On Linux/macOS
 
 ```bash
-(env) $ pip install -r requirements.txt
+$ sudo -H pip install virtualenv
 ```
 
-A CLI depende do módulo manage.py. Demais dependências serão listadas a seguir.
+1b) On Windows (with administrator privilleges)
 
-### Requisitos para a interface com a base de dados ###
+```cmd
+$ pip install virtualenv
+```
 
-* pymonetdb
-* SQLAlchemy
-* sqlalchemy-monetdb
 
-### Requisitos para geração de pareamentos ###
+2) Clone this repository
+```bash
+$ git clone git@gitlab.c3sl.ufpr.br:tools/hotmapper.git
+```
 
-* numpy
-* pandas
-* xlrd
-* XlsxWriter
+3) Go to the repository
 
-## Interface de linha de comando ##
+```bash
+$ cd hotmapper
+```
+
+4) Create a virtual environment
+ 
+```bash
+$ virtualenv env
+```
+
+5) Start the virtual environment
 
-A invocação da CLI utiliza o padrão do pacote manage.py, que é:
+5a) On Linux/macOS
+
+```bash
+$ source env/bin/activate
+```
+
+5b) On Windows (with administrator privilleges)
+
+```cmd
+$ .\env\Scripts/activate
+```
 
+6) Install dependencies
+ 
 ```bash
-$ python manage.py [commando] [argumentos posicionais] [argumentos opcionais com valor]
+$ pip install -r requirements.txt
 ```
 
-Os comandos já implementados são:
+## Interface de linha de comando ##
 
-* create: Cria a tabela conforme definido no protocolo de mapeamento.
+The CLI (Command Line Interface) uses the standart of the manage.py package, which means that to invoke a command you should use the following pattern:
 
 ```bash
-$ python manage.py create <nome da tabela>
+$ python manage.py [COMMAND] [POSITIONAL ARGUMENTS] [OPTIONAL ARGUMENTS]
 ```
 
-O único argumento usado é o nome da tabela. O script procurará por um protocolo de
-mapeamento com o mesmo nome para a busca do esquema das colunas.
+Where COMMAND can be:
 
-* insert: insere um arquivo de dados em formato CSV ou similar em uma tabela existente.
+* create: Create a table using the mapping protocol.
 
 ```bash
-$ python manage.py insert <caminho para o arquivo> <nome da tabela> <ano> [--sep separador] [--null valor_nulo]
+$ python manage.py create <table_name>
 ```
 
-O caminho para o arquivo deve ser absoluto. A tabela utilizada deve existir e estar
-sincronizada com o protocolo de mapeamento correspondente. O separador padrão utilizado
-é ponto e vírgula (';'); caso outros separadores sejam utilizados pelo arquivo fonte,
-devem ser especificados com --sep (por exemplo --sep \\| para pipe). O valor nulo padrão
-é string vazia. Caso outro valor seja usado, deve ser especificado com --null.
+**Notice** that the HOTMapper will use the name of the protocol as the name of the table.
+
 
-* drop: derruba uma tabela do banco de dados.
+* insert: Insert a CSV file in an existing table.
 
 ```bash
-$ python manage.py drop <nome da tabela>
+$ python manage.py insert <full/path/for/the/file> <table_name> <year> [--sep separator] [--null null_value]
+```
+
+```
+<full/path/for/the/file> : The absolute file path
+
+<table_name>: The name of the table where the file will be inserted
+
+<year>: The column of the mapping protocol that the HOTMapper should use to insert data
+
+[--sep separator]: The custom separtor of the CSV. To change it you should just replace 'separator' with the token your file uses
+
+[--null null_value]: Define what will replace the null value. Replace the 'null_value' with what you wish to do.
+
 ```
 
-O comando não contorna chaves estrangeiras que apontem para a tabela, e o banco de dados
-pode retornar um erro caso exista alguma.
 
-* remap: sincroniza uma tabela com o protocolo de mapeamento.
+
+* drop: Delete a table from the database
 
 ```bash
-$ python manage.py remap <nome da tabela>
+$ python manage.py drop <table_name>
 ```
 
-Esse comando deve ser utilizado sempre que um protocolo de mapeamento for atualizado.
+**NOTICE:** The command does not take care of foreign keys that points to the table that are being deleted. Therefore, the database can produce errors.
+
+* remap: syncronize a table with the mapping protocol.
 
-O remapeamento permite a criação de novas colunas, derrubada de colunas existentes,
-renomeamento de colunas e mudança de tipo. Dependendo do tamanho da tabela, o uso de
-memória primária pode ser intenso.
+```bash
+$ python manage.py remap <table_name>
+```
+You should use this command everytime a mapping protocol is updated.
 
-* generate_pairing_report: gera relatórios de pareamento para comparação de dados ano
-a ano.
+The remap allows the creation of new columns, the drop of existent columns, the renaming of columns and the change of type of columns. Be aware that the bigger the table the bigger the usegae of RAM memory.
+
+* generate_pairing_report: generate reports to compare data from diferent years.
 
 ```bash
 $ python manage.py generate_pairing_report [--output xlsx|csv]
 ```
 
-Os relatórios são criados na pasta pairing. Caso o formato não seja especificado,
-csv será utilizado (um arquivo será criado para cada tabela). Caso xlsx seja o formato
-utilizado, um arquivo será criado com todas as tabelas separadas em diferentes planilhas.
+The reports will be created in the folder "pairing" 
+
 
-* generate_backup: Cria/Atualiza o arquivo monitorado para o backup.
+* generate_backup: Create/Update a file to backup the database.
 
 ```bash
 $ python manage.py generate_backup
-```
-
-O arquivo é criado ou atualizado na máquina onde o banco de dados da produção está,
-o procedimento de backup da equipe de infraestrutura o monitora para realizar o procedimento.
\ No newline at end of file
+```
\ No newline at end of file
-- 
GitLab