reugenio 5f35a12d22 CLAUDE.md: jj + NORMAS_ESENCIALES

2025-12-25 19:24:22 +01:00

6.8 KiB

Raw Blame History

zcatpdf - Generador PDF para Zig

VCS: jj (no git). Ver /mnt/cello2/arno/re/recode/teamdocs/NORMAS_ESENCIALES.md

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 (teamdocs)

Ubicacion: /mnt/cello2/arno/re/recode/teamdocs/

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

# 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

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:

TTF Font Embedding - Embeber TTF para renderizar texto (CIDFont Type 2)
PDF Encryption Integration - Integrar RC4 con OutputProducer
AcroForms Output - Generar campos de formulario en PDF final
SVG Avanzado - text, transforms, gradients en SVG
Markdown Avanzado - code blocks, tables, images

Git

# 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

zcatpdf v1.0 - Generador PDF para Zig Feature Complete - 2025-12-09

6.8 KiB Raw Blame History