reugenio
a7cd3894da
- Updated repository URL to include port 2222 - Added Forgejo web URL - Added references to docs/ folder documentation - Added TEAM_STANDARDS section with key files - Updated Git section to reflect completed rename (zpdf → zcatpdf) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
214 lines
6.7 KiB
Markdown
214 lines
6.7 KiB
Markdown
# zcatpdf - Generador PDF para Zig
|
|
|
|
> **Version**: v1.0 - RELEASE (FEATURE COMPLETE)
|
|
> **Ultima actualizacion**: 2025-12-09
|
|
> **Lenguaje**: Zig 0.15.2
|
|
> **Repositorio**: ssh://git@git.reugenio.com:2222/reugenio/zcatpdf.git
|
|
> **Forgejo Web**: https://git.reugenio.com/reugenio/zcatpdf
|
|
|
|
---
|
|
|
|
## Informacion para Nueva Conversacion
|
|
|
|
### Que es zcatpdf?
|
|
|
|
Libreria pura Zig para generacion de documentos PDF. Parte de la familia "zcat*" (zcatui, zcatgui, zcatpdf).
|
|
|
|
### Documentacion Disponible
|
|
|
|
| Archivo | Contenido |
|
|
|---------|-----------|
|
|
| `CLAUDE.md` | Este archivo - contexto del proyecto |
|
|
| `README.md` | **Manual de referencia completo** - API, ejemplos de codigo, tipos, archivos |
|
|
| `FUTURE_IMPROVEMENTS.md` | **Mejoras futuras detalladas** - TTF embedding, encryption integration, forms output, SVG avanzado |
|
|
| `docs/ARQUITECTURA_FPDF2.md` | Analisis de fpdf2 (Python) - arquitectura de referencia |
|
|
| `docs/ARQUITECTURA_ZPDF.md` | Diseno inicial del proyecto (historico) |
|
|
| `docs/PLAN_MAESTRO_ZPDF.md` | Plan original de implementacion (completado) |
|
|
|
|
### Normas del Equipo (TEAM_STANDARDS)
|
|
|
|
**Ubicacion**: `/mnt/cello2/arno/re/recode/TEAM_STANDARDS/`
|
|
|
|
Documentacion centralizada para todos los proyectos:
|
|
- `INFRASTRUCTURE/FORGEJO_GIT_SERVER.md` - Servidor git, tokens, API
|
|
- `INTEGRATION_GUIDE.md` - Guia de integracion de proyectos
|
|
- `NORMAS_PATRONES_DESARROLLO.md` - Patrones y normas de desarrollo
|
|
|
|
### Comandos Esenciales
|
|
|
|
```bash
|
|
# Zig path
|
|
ZIG=/mnt/cello2/arno/re/recode/zig/zig-0.15.2/zig-x86_64-linux-0.15.2/zig
|
|
|
|
# Compilar y testear
|
|
$ZIG build
|
|
$ZIG build test
|
|
|
|
# Ejecutar ejemplos
|
|
./zig-out/bin/hello
|
|
./zig-out/bin/invoice
|
|
./zig-out/bin/barcode_demo
|
|
# etc. (16 ejemplos en total)
|
|
```
|
|
|
|
### Reglas Clave para Este Proyecto
|
|
|
|
- Nombres en minusculas: `zcatpdf` (no ZcatPDF, no zCatPdf)
|
|
- Import: `@import("zcatpdf")`
|
|
- Doc comments (`///`) en funciones publicas
|
|
- Codigo idiomatico Zig (snake_case, error handling explicito)
|
|
|
|
---
|
|
|
|
## Estado del Proyecto
|
|
|
|
### FEATURE COMPLETE - v1.0
|
|
|
|
La libreria esta completa para uso en produccion. Todas las funcionalidades planificadas estan implementadas:
|
|
|
|
| Categoria | Funcionalidades |
|
|
|-----------|-----------------|
|
|
| **Documento** | PDF 1.4, metadatos, multiples paginas, compresion FlateDecode |
|
|
| **Texto** | drawText, cell, multiCell, word wrap, 14 fuentes Type1 |
|
|
| **Graficos** | Lineas, rectangulos, curvas Bezier, circulos, elipses, arcos |
|
|
| **Colores** | RGB, CMYK, Grayscale, colores predefinidos |
|
|
| **Imagenes** | JPEG, PNG (con alpha/transparencia) |
|
|
| **Tablas** | Table helper con headers, rows, footers |
|
|
| **Links** | URLs clickeables, links internos entre paginas |
|
|
| **Bookmarks** | Navegacion en sidebar del lector PDF |
|
|
| **Transformaciones** | Rotacion, escala, traslacion, skew |
|
|
| **Transparencia** | Fill y stroke opacity (0.0-1.0) |
|
|
| **Gradientes** | Lineales y radiales |
|
|
| **Barcodes** | Code128 (1D), QR Code (2D) |
|
|
| **TTF Fonts** | Parsing de TrueType (metricas, anchos de glyph) |
|
|
| **Security** | RC4 encryption module (40/128-bit) |
|
|
| **Forms** | TextField, CheckBox (structs, no output aun) |
|
|
| **SVG** | Import basico (shapes, paths) |
|
|
| **Templates** | Layouts reutilizables (invoice, letter) |
|
|
| **Markdown** | Texto con estilos (bold, italic, links, headings, lists) |
|
|
|
|
### Tests y Ejemplos
|
|
|
|
- **125+ tests** unitarios
|
|
- **16 ejemplos** funcionales en `examples/`
|
|
|
|
---
|
|
|
|
## Arquitectura de Archivos
|
|
|
|
```
|
|
zcatpdf/
|
|
├── CLAUDE.md # Este archivo
|
|
├── README.md # Manual de referencia completo
|
|
├── FUTURE_IMPROVEMENTS.md # Mejoras futuras detalladas
|
|
├── build.zig # Sistema de build
|
|
├── build.zig.zon # Dependencias (libdeflate)
|
|
├── src/
|
|
│ ├── root.zig # Exports publicos (@import("zcatpdf"))
|
|
│ ├── pdf.zig # Pdf struct - API principal
|
|
│ ├── page.zig # Page - dibujo, texto, transformaciones
|
|
│ ├── content_stream.zig # Operadores PDF de bajo nivel
|
|
│ ├── table.zig # Table helper
|
|
│ ├── pagination.zig # Numeros de pagina, headers, footers
|
|
│ ├── links.zig # Link types
|
|
│ ├── outline.zig # Bookmarks
|
|
│ ├── fonts/ # Type1 + TrueType
|
|
│ ├── graphics/ # Color, ExtGState, Gradient
|
|
│ ├── images/ # JPEG, PNG parsers
|
|
│ ├── barcodes/ # Code128, QR
|
|
│ ├── compression/ # libdeflate wrapper
|
|
│ ├── security/ # RC4, Encryption
|
|
│ ├── forms/ # TextField, CheckBox
|
|
│ ├── svg/ # SVG parser
|
|
│ ├── template/ # Template system
|
|
│ ├── markdown/ # Markdown renderer
|
|
│ ├── objects/ # PageSize, Orientation
|
|
│ └── output/ # PDF serialization
|
|
└── examples/ # 16 demos ejecutables
|
|
```
|
|
|
|
---
|
|
|
|
## Uso Rapido
|
|
|
|
```zig
|
|
const zcatpdf = @import("zcatpdf");
|
|
|
|
pub fn main() !void {
|
|
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
|
|
defer _ = gpa.deinit();
|
|
const allocator = gpa.allocator();
|
|
|
|
var pdf = zcatpdf.Pdf.init(allocator, .{});
|
|
defer pdf.deinit();
|
|
|
|
pdf.setTitle("Mi Documento");
|
|
|
|
var page = try pdf.addPage(.{});
|
|
try page.setFont(.helvetica_bold, 24);
|
|
try page.drawText(50, 750, "Hello, PDF!");
|
|
|
|
try pdf.save("output.pdf");
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Mejoras Futuras (No Criticas)
|
|
|
|
Ver `FUTURE_IMPROVEMENTS.md` para detalles completos:
|
|
|
|
1. **TTF Font Embedding** - Embeber TTF para renderizar texto (CIDFont Type 2)
|
|
2. **PDF Encryption Integration** - Integrar RC4 con OutputProducer
|
|
3. **AcroForms Output** - Generar campos de formulario en PDF final
|
|
4. **SVG Avanzado** - text, transforms, gradients en SVG
|
|
5. **Markdown Avanzado** - code blocks, tables, images
|
|
|
|
---
|
|
|
|
## Git
|
|
|
|
```bash
|
|
# Remote
|
|
origin: ssh://git@git.reugenio.com:2222/reugenio/zcatpdf.git
|
|
|
|
# Branch principal
|
|
main
|
|
|
|
# Comandos comunes
|
|
git status
|
|
git add -A && git commit -m "mensaje"
|
|
git push
|
|
```
|
|
|
|
**Nota**: El proyecto fue renombrado de `zpdf` a `zcatpdf` el 2025-12-09.
|
|
El repositorio en Forgejo y el remote local ya estan actualizados.
|
|
|
|
---
|
|
|
|
## Familia zcat*
|
|
|
|
| Proyecto | Descripcion |
|
|
|----------|-------------|
|
|
| **zcatui** | TUI library (terminal UI, como ratatui) |
|
|
| **zcatgui** | GUI library (immediate mode, SDL2 backend) |
|
|
| **zcatpdf** | PDF generation library |
|
|
|
|
Todos siguen las mismas convenciones:
|
|
- 100% Zig
|
|
- Minimas dependencias
|
|
- Nombres en minusculas
|
|
- Open source ready
|
|
|
|
---
|
|
|
|
## Referencias Externas
|
|
|
|
- [PDF Reference 1.4](https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/pdfreference1.4.pdf)
|
|
- [fpdf2 (Python)](https://github.com/py-pdf/fpdf2) - Inspiracion de la API
|
|
- [Zig Documentation](https://ziglang.org/documentation/master/)
|
|
|
|
---
|
|
|
|
**zcatpdf v1.0** - Generador PDF para Zig
|
|
*Feature Complete - 2025-12-09*
|