Initial commit: Padre Matos Soares (1932) Bible corpus and pms CLIHEADmaster

1 files changed, 255 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..92a34a1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,255 @@
+# pms — Bíblia Sagrada (Padre Matos Soares, 1932) no Terminal
+
+`pms` é uma ferramenta de linha de comando (CLI) escrita em C, inspirada no [`layeh/kjv`](https://github.com/layeh/kjv), para leitura e pesquisa da **Bíblia Sagrada traduzida da Vulgata Latina e comentada pelo Padre Manuel de Matos Soares (edição de 1932)**.
+
+Todo o texto bíblico (**73 livros do cânon católico**, **1.334 capítulos** e **35.528 versículos**) e as **3.071 notas de comentário** do Padre Matos Soares são compilados diretamente dentro do executável `pms`, sem necessidade de ficheiros externos em tempo de execução.
+
+---
+
+## Funcionalidades
+
+- **Cânon Católico Completo (73 livros)**: Inclui todos os livros protocanónicos e deuterocanónicos segundo a ordem e nomenclatura da Vulgata Sixto-Clementina, preservando fielmente a grafia da edição original.
+- **Nomenclatura da Vulgata + Aliases Modernos**: Aceita tanto os títulos tradicionais da Vulgata (`1Rs`–`4Rs`, `1Par`–`2Par`, `1Esd`, `2Esd`) como as siglas modernas (`1Sm`, `2Sm`, `1Cr`, `2Cr`, `Ne`, `Sl`/`Ps`, `Eclo`/`Sir`, etc.), sem distinção de maiúsculas/minúsculas ou acentos.
+- **Notas e Comentários (`-c`)**: Permite exibir as notas de rodapé explicativas do Padre Matos Soares associadas aos versículos consultados.
+- **Pesquisa por Expressões Regulares (`/termo`)**: Pesquisa insensível a maiúsculas/minúsculas e a acentos/diacríticos em toda a Bíblia, num livro específico ou num capítulo específico, com realce ANSI (`-e`).
+- **Paginação Automática e Modo Interativo (REPL)**: Integração automática com `less` (ou `$PAGER`) quando executado num terminal interativo, além de um prompt interativo (`pms> `) quando invocado sem argumentos.
+
+---
+
+## Compilação e Instalação
+
+### Requisitos
+
+- Compilador C compatível com C99/POSIX (`gcc` ou `clang`)
+- `make`
+- `python3` (apenas para regenerar `src/pms_data.c` a partir de `data/*.tsv`; para reextrair diretamente do `pms.pdf`, são também necessários `pdftotext` do pacote `poppler-utils` e `python3-lxml`)
+
+### Compilar
+
+```bash
+make
+```
+
+O binário autónomo `./pms` será gerado na raiz do repositório.
+
+### Instalar no sistema (opcional)
+
+```bash
+sudo make install          # Instala em /usr/local/bin/pms
+# ou num diretório personalizado:
+make install PREFIX=$HOME/.local
+```
+
+Para desinstalar:
+
+```bash
+sudo make uninstall
+```
+
+---
+
+## Utilização
+
+```text
+usage: pms [flags] [reference...]
+```
+
+### Opções (Flags)
+
+| Flag | Descrição |
+| :--- | :--- |
+| `-A num` | Mostra `num` versículos de contexto **após** os versículos encontrados. |
+| `-B num` | Mostra `num` versículos de contexto **antes** dos versículos encontrados. |
+| `-C` | Mostra os versículos encontrados no contexto do **capítulo inteiro**. |
+| `-c` (ou `-n`) | Mostra os **comentários / notas de rodapé** do Padre Matos Soares para os versículos exibidos. |
+| `-e` | Ativa o realce ANSI de capítulos, números de versículos e termos pesquisados (ativo por omissão em TTY). |
+| `-p` | Formata a saída com agrupamento por capítulo, indentação, espaçamento e paginação via `less` (ativo por omissão em TTY). |
+| `-W` (ou `-w`) | Desativa a quebra automática de linha (*line wrap*). |
+| `-l` | Lista todos os 73 livros e as suas abreviaturas canónicas. |
+| `-h` | Mostra a mensagem de ajuda. |
+
+---
+
+### Sintaxe de Referências
+
+| Formato | Descrição | Exemplos |
+| :--- | :--- | :--- |
+| `<Livro>` | Livro inteiro | `pms Gn`, `pms Abd`, `pms 2Jo` |
+| `<Livro>:<Cap>` ou `<Livro> <Cap>` | Capítulo inteiro | `pms Gn:1`, `pms Sl 22`, `pms Jo 1` |
+| `<Livro>:<Cap>:<Vers>` | Versículo único | `pms Jo 3:16`, `pms Gn:1:1` |
+| `<Livro>:<Cap>:<V1>[,<V2>]...` | Conjunto de versículos (ou intervalos) separados por vírgula | `pms Gn 1:1,3,5`, `pms Gn 1:1-3,6,9-10` |
+| `<Livro>:<Cap1>-<Cap2>` | Intervalo de capítulos | `pms Gn 1-3`, `pms Sl 22-23` |
+| `<Livro>:<Cap>:<V1>-<V2>` | Intervalo de versículos num capítulo | `pms Gn 1:1-5`, `pms Rm 8:31-39` |
+| `<Livro>:<Cap1>:<V1>-<Cap2>:<V2>` | Intervalo de versículos entre capítulos diferentes | `pms Gn 1:26-2:3` |
+| `/<Padrao>` | Pesquisa regex em toda a Bíblia (sem distinção de acentos/maiúsculas) | `pms /principio`, `pms "/verbo se fez carne"` |
+| `<Livro>/<Padrao>` | Pesquisa regex restrita a um livro | `pms Jo/luz`, `pms Sl /pastor` |
+| `<Livro>:<Cap>/<Padrao>` | Pesquisa regex restrita a um capítulo | `pms Jo:1/luz`, `pms Gn 1 /firmamento` |
+
+---
+
+### Exemplos Práticos
+
+```bash
+# Ler Génesis 1:1-5 com as notas do Padre Matos Soares
+./pms -p -c Gn 1:1-5
+
+# Consultar usando siglas da Vulgata ou equivalentes modernos
+./pms 1Rs 3:9       # 1 Reis (= 1 Samuel)
+./pms 1Sm 3:9       # Mesmo livro usando a sigla moderna 1Sm
+./pms 1Par 1:1      # 1 Paralipómenos (= 1 Crónicas)
+./pms 1Cr 1:1       # Mesmo livro usando a sigla moderna 1Cr
+./pms 2Esd 1:1      # 2 Esdras (= Neemias)
+./pms Ne 1:1        # Mesmo livro usando a sigla moderna Ne
+
+# Mostrar 1 versículo antes e 1 depois de Génesis 1:3
+./pms -B 1 -A 1 Gn 1:3
+
+# Pesquisar "espírito de deus" (sem precisar de acentos) com notas
+./pms -p -c "/espirito de deus"
+
+# Saída simples em texto corrido sem quebra de linha (ideal para scripts/pipes)
+./pms -W Gn 1:1-5
+```
+
+---
+
+### Modo Interativo (REPL)
+
+Executando `./pms` sem argumentos de referência num terminal, abre-se o modo interativo:
+
+```text
+$ ./pms
+pms> Jo 1:1-5
+pms> :c
+Comentários: activados
+pms> Gn 1:1-5
+pms> :l
+pms> q
+```
+
+Comandos especiais dentro do REPL:
+- `:c` ou `-c`: alterna (ativa/desativa) a exibição dos comentários do Padre Matos Soares.
+- `:l` ou `-l`: lista os 73 livros.
+- `:h`, `-h` ou `help`: mostra a ajuda.
+- `q`, `quit`, `exit`, `sair` ou `Ctrl-D`: encerra o programa.
+
+---
+
+## Lista dos 73 Livros e Aliases Suportados
+
+> **Nota sobre os Salmos**: Tal como na Vulgata Latina, os Salmos 9 a 146 seguem a numeração greco-latina (por exemplo, o célebre *"O Senhor me governa"* corresponde ao **Salmo 22** na Vulgata / Salmo 23 no hebraico).
+
+| # | Título Canónico (Vulgata) | Sigla | Outros Aliases Aceites |
+| :-: | :--- | :---: | :--- |
+| **Antigo Testamento** | | | |
+| 1 | Génesis | `Gn` | `gen`, `genesis` |
+| 2 | Êxodo | `Ex` | `exo`, `exodo` |
+| 3 | Levítico | `Lv` | `lev`, `levitico` |
+| 4 | Números | `Nm` | `num`, `numeros` |
+| 5 | Deuteronómio | `Dt` | `deut`, `deuteronomio` |
+| 6 | Josué | `Js` | `jos`, `josue` |
+| 7 | Juízes | `Jz` | `juiz`, `juizes` |
+| 8 | Rut | `Rt` | `rut`, `rute` |
+| 9 | 1 Reis | `1Rs` | `1reis`, `1sm`, `1sam`, `1samuel` |
+| 10 | 2 Reis | `2Rs` | `2reis`, `2sm`, `2sam`, `2samuel` |
+| 11 | 3 Reis | `3Rs` | `3reis`, `iiireis` |
+| 12 | 4 Reis | `4Rs` | `4reis`, `ivreis` |
+| 13 | 1 Paralipómenos | `1Par` | `1paralipomenos`, `1cr`, `1cron`, `1cronicas` |
+| 14 | 2 Paralipómenos | `2Par` | `2paralipomenos`, `2cr`, `2cron`, `2cronicas` |
+| 15 | 1 Esdras | `1Esd` | `1esdras`, `esd`, `esdras` |
+| 16 | 2 Esdras (Neemias) | `2Esd` | `2esdras`, `ne`, `nee`, `neemias` |
+| 17 | Tobias | `Tb` | `tob`, `tobias` |
+| 18 | Judit | `Jt` | `jdt`, `judit`, `judite` |
+| 19 | Ester | `Est` | `ester` |
+| 20 | Job | `Job` | `job` |
+| 21 | Salmos | `Sl` | `sal`, `salmo`, `salmos`, `ps`, `psalmos` |
+| 22 | Provérbios | `Pr` | `prov`, `proverbios` |
+| 23 | Eclesiastes | `Ecl` | `eclesiastes`, `qo`, `coelet` |
+| 24 | Cântico dos Cânticos | `Ct` | `cant`, `cantico`, `canticos` |
+| 25 | Sabedoria | `Sb` | `sab`, `sabedoria` |
+| 26 | Eclesiástico | `Eclo` | `eclesiastico`, `sir`, `siracide`, `bensira` |
+| 27 | Isaías | `Is` | `isa`, `isaias` |
+| 28 | Jeremias | `Jr` | `jer`, `jeremias` |
+| 29 | Lamentações | `Lm` | `lam`, `lamentacoes` |
+| 30 | Baruc | `Br` | `bar`, `baruc` |
+| 31 | Ezequiel | `Ez` | `eze`, `ezeq`, `ezequiel` |
+| 32 | Daniel | `Dn` | `dan`, `daniel` |
+| 33 | Oséas | `Os` | `ose`, `oseas`, `oseias` |
+| 34 | Joel | `Jl` | `joel` |
+| 35 | Amós | `Am` | `amos` |
+| 36 | Abdias | `Abd` | `ab`, `abdias`, `ob`, `obadias` |
+| 37 | Jonas | `Jn` | `jon`, `jonas` |
+| 38 | Miquéas | `Mq` | `miq`, `miqueas`, `miqueias` |
+| 39 | Naum | `Na` | `nau`, `naum` |
+| 40 | Habacuc | `Hab` | `hc`, `habacuc`, `habacuque` |
+| 41 | Sofonias | `Sf` | `sof`, `sofonias` |
+| 42 | Ageu | `Ag` | `ageu` |
+| 43 | Zacarias | `Zc` | `zac`, `zacarias` |
+| 44 | Malaquias | `Ml` | `mal`, `malaquias` |
+| 45 | 1 Macabeus | `1Mc` | `1mac`, `1macabeus` |
+| 46 | 2 Macabeus | `2Mc` | `2mac`, `2macabeus` |
+| **Novo Testamento** | | | |
+| 47 | S. Mateus | `Mt` | `mat`, `mateus`, `smateus` |
+| 48 | S. Marcos | `Mc` | `mar`, `marcos`, `smarcos` |
+| 49 | S. Lucas | `Lc` | `luc`, `lucas`, `slucas` |
+| 50 | S. João | `Jo` | `joao`, `sjoao` |
+| 51 | Actos dos Apóstolos | `At` | `act`, `atos`, `actos` |
+| 52 | Romanos | `Rm` | `rom`, `romanos` |
+| 53 | 1 Coríntios | `1Cor` | `1co`, `1corintios` |
+| 54 | 2 Coríntios | `2Cor` | `2co`, `2corintios` |
+| 55 | Gálatas | `Gl` | `gal`, `galatas` |
+| 56 | Efésios | `Ef` | `efe`, `efesios` |
+| 57 | Filipenses | `Fp` | `flp`, `fil`, `filipenses` |
+| 58 | Colossenses | `Cl` | `col`, `colossenses` |
+| 59 | 1 Tessalonicenses | `1Ts` | `1tes`, `1tessalonicenses` |
+| 60 | 2 Tessalonicenses | `2Ts` | `2tes`, `2tessalonicenses` |
+| 61 | 1 Timóteo | `1Tm` | `1tim`, `1timoteo` |
+| 62 | 2 Timóteo | `2Tm` | `2tim`, `2timoteo` |
+| 63 | Tito | `Tt` | `tit`, `tito` |
+| 64 | Filémon | `Fm` | `flm`, `filemon` |
+| 65 | Hebreus | `Hb` | `heb`, `hebreus` |
+| 66 | S. Tiago | `Tg` | `tiago`, `stiago` |
+| 67 | 1 S. Pedro | `1Pd` | `1pe`, `1ped`, `1pedro` |
+| 68 | 2 S. Pedro | `2Pd` | `2pe`, `2ped`, `2pedro` |
+| 69 | 1 S. João | `1Jo` | `1joao`, `1sjoao` |
+| 70 | 2 S. João | `2Jo` | `2joao`, `2sjoao` |
+| 71 | 3 S. João | `3Jo` | `3joao`, `3sjoao` |
+| 72 | S. Judas | `Jd` | `jud`, `judas`, `sjudas` |
+| 73 | Apocalipse | `Ap` | `apoc`, `apocalipse` |
+
+---
+
+## Estrutura do Repositório
+
+```text
+.
+├── Makefile                    # Regras de compilação, extração e instalação
+├── README.md                   # Documentação do projeto
+├── pms.pdf                     # Digitalização original (4 volumes, 2.572 páginas, 1932)
+├── pms.txt                     # Texto completo formatado e limpo (73 livros + notas)
+├── pms                         # Binário CLI autónomo compilado
+├── data/
+│   ├── pms.tsv                 # Versículos tabulados (BookName, BookAbbr, BookNum, Chapter, Verse, Text)
+│   └── pms_notes.tsv           # Comentários tabulados (BookNum, Chapter, VerseStart, VerseEnd, Label, NoteText)
+├── scripts/
+│   ├── extract_pms.py          # Extrator geométrico (pdftotext -bbox) de pms.pdf -> data/*.tsv e pms.txt
+│   └── generate_c_data.py      # Gerador de código C (data/*.tsv -> src/pms_data.c)
+└── src/
+    ├── pms_config.h            # Configuração de execução e opções CLI
+    ├── pms_data.h              # Estruturas de dados de livros, versículos e notas
+    ├── pms_data.c              # Corpus embutido (gerado automaticamente)
+    ├── pms_main.c              # Ponto de entrada, flags, pager e REPL
+    ├── pms_match.h / .c        # Motor de filtragem de versículos e expansão de contexto (-A, -B, -C)
+    ├── pms_ref.h / .c          # Parser de referências bíblicas e resolução de nomes/aliases
+    ├── pms_render.h / .c       # Formatação de saída, word-wrap UTF-8, realce ANSI e notas
+    └── pms_util.h / .c         # Utilitários UTF-8 e normalização insensível a acentos
+```
+
+### Reextrair os Dados do PDF
+
+Caso deseje modificar o processamento de texto e regenerar `pms.txt`, `data/pms.tsv`, `data/pms_notes.tsv` e `src/pms_data.c` a partir de `pms.pdf`:
+
+```bash
+make extract
+make
+```