ailessonio/open-source-skills

Habilidad PDF

Cuándo usarla

• Leer o revisar contenido PDF donde el diseño y los elementos visuales importan.
• Crear PDFs programáticamente con formato confiable.
• Validar el renderizado final antes de la entrega.

Flujo de trabajo

1. Preferir la revisión visual: renderizar las páginas PDF a PNG e inspeccionarlas.
   • Usar pdftoppm si está disponible.
   • Si no está disponible, instalar Poppler o pedir al usuario que revise la salida localmente.
2. Usar reportlab para generar PDFs al crear nuevos documentos.
3. Usar pdfplumber (o pypdf) para extracción de texto y verificaciones rápidas; no confiar en él para la fidelidad del diseño.
4. Después de cada actualización significativa, volver a renderizar las páginas y verificar alineación, espaciado y legibilidad.

Convenciones de archivos temporales y de salida

• Usar tmp/pdfs/ para archivos intermedios; eliminarlos al terminar.
• Escribir los artefactos finales en output/pdf/ cuando se trabaje en este repositorio.
• Mantener los nombres de archivo estables y descriptivos.

Dependencias (instalar si faltan)

Preferir uv para la gestión de dependencias.

Paquetes de Python:

uv pip install reportlab pdfplumber pypdf

Si uv no está disponible:

python3 -m pip install reportlab pdfplumber pypdf

Herramientas del sistema (para renderizado):

# macOS (Homebrew)
brew install poppler

# Ubuntu/Debian
sudo apt-get install -y poppler-utils

Si la instalación no es posible en este entorno, informar al usuario qué dependencia falta y cómo instalarla localmente.

Entorno

No se requieren variables de entorno.

Comando de renderizado

pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX

Expectativas de calidad

• Mantener un diseño visual pulido: tipografía, espaciado, márgenes y jerarquía de secciones consistentes.
• Evitar problemas de renderizado: texto recortado, elementos superpuestos, tablas rotas, cuadrados negros o glifos ilegibles.
• Los gráficos, tablas e imágenes deben ser nítidos, alineados y claramente etiquetados.
• Usar solo guiones ASCII. Evitar U+2011 (guión de no separación) y otros guiones Unicode.
• Las citas y referencias deben ser legibles para humanos; nunca dejar tokens de herramienta o cadenas de marcador de posición.

Verificaciones finales

• No entregar hasta que la última inspección PNG muestre cero defectos visuales o de formato.
• Confirmar que encabezados/pies de página, numeración de páginas y transiciones de secciones se vean pulidos.
• Mantener los archivos intermedios organizados o eliminarlos después de la aprobación final.