La bibliothèque, sur votre propre machine

De quoi il s'agit

Vous connaissez le fichier PDF : c'est celui qui garde exactement la même allure partout. Vous l'ouvrez sur votre ordinateur, votre voisin l'ouvre sur un téléphone, l'imprimeur le sort sur sa machine, et c'est la même page au millimètre près. C'est pour ça que les factures, les contrats et les bulletins de paie voyagent sous cette forme.

HQF Development fabrique le moteur qui écrit ces fichiers. Pas un logiciel que vous ouvrez et dans lequel vous cliquez : un moteur, que la personne qui écrit vos logiciels pose à l'intérieur des siens.

Ce qu'est une bibliothèque

En informatique, une bibliothèque est un jeu de pièces toutes faites. Pensez au moteur d'une voiture. Le constructeur n'en refabrique pas un pour chaque modèle : il prend un moteur qui existe, il le pose dans la carrosserie qu'il a dessinée, et il branche la pédale dessus. Le moteur fait tourner les roues ; la voiture reste la sienne.

Une bibliothèque, c'est ce moteur. La personne qui écrit votre logiciel de facturation garde son logiciel, ses écrans, ses habitudes, sa manière de travailler. Elle y glisse notre moteur, elle lui dit voilà les lignes de la facture, voilà le logo, voilà le total, et le moteur lui rend le fichier PDF.

L'autre façon de faire, et ce qui change

Il existe une autre façon de faire : envoyer les informations à un ordinateur ailleurs sur internet, qui fabrique le document et le renvoie. C'est comme confier votre courrier à un imprimeur à l'autre bout de la ville. Ça marche très bien, et l'équipe le propose aussi. Mais il faut porter le pli là-bas, attendre, et revenir le chercher.

Avec la bibliothèque, l'imprimeur est dans la pièce d'à côté. Trois choses changent, et les trois se sentent tout de suite.

• C'est immédiat. Le document est fabriqué sur votre propre machine, dans le même souffle que le clic qui l'a demandé. Rien ne part, rien ne revient. Une facture de cent pages sort en une fraction de seconde.
• Vos informations restent chez vous. Les noms de vos clients, leurs adresses, leurs montants : tout cela reste sur votre machine, du début à la fin. La bibliothèque travaille entièrement sur place, avec ce qu'elle porte dans son propre paquet. C'est la réponse la plus simple à la question de savoir où vont vos données : elles ne vont nulle part.
• Ça tient tout seul. Votre logiciel fabrique ses documents même si la connexion est coupée, même sur un site isolé, même à trois heures du matin. Il n'y a rien d'autre à surveiller que votre propre machine.

Ce que ça fabrique

Des factures, des confirmations de commande, des bons de livraison, des bulletins de paie, des contrats, des relevés, des planches d'étiquettes, des catalogues, des diplômes, des cartes d'embarquement, des livres entiers. Avec les tableaux qui se poursuivent d'une page à l'autre, les logos, les photos, les petits carrés qu'un téléphone lit pour payer, les cases qu'on remplit à l'écran, et le mot de passe qui verrouille le tout si vous le demandez.

À qui cette page est destinée

La suite de cette page est écrite pour la personne qui développe vos logiciels. Si ce n'est pas vous, la meilleure chose à faire est de lui donner l'adresse de cette page : elle y trouvera, plus bas, tout ce qu'il lui faut pour juger en dix minutes.

Deux faces

Le moteur est écrit en Rust et s'utilise depuis Rust directement, comme une dépendance ordinaire de votre projet.

La face Python est une extension compilée livrée déjà construite : rien à compiler sur la cible, aucune bibliothèque système à installer, aucune chaîne d'outils PDF sur la machine. Elle est bâtie sur l'ABI stable de CPython, si bien qu'une seule roue Python sert toutes les versions de l'interpréteur sur une plateforme. CPython 3.9 et plus, sur Linux, Windows et macOS.

Une façade en C, pour les langages qui appellent par là, est prévue pour une version future.

Ce qu'il écrit

• Texte : TrueType, OpenType et Type 1 lues et embarquées, réduites aux glyphes réellement dessinés ; ligatures, petites capitales, chiffres elzéviriens, crénage ; une police de secours derrière une autre ; les quatorze fontes que tout lecteur porte déjà ; les fontes de type 3 dont les glyphes sont des dessins ; écriture verticale.
• Mise en page : paragraphes coupés à une largeur, colonnes, listes, tabulations et points de conduite, styles qui changent à l'intérieur d'un paragraphe, tableaux paginés sur autant de pages qu'il faut, blocs empilés sans une seule ordonnée écrite à la main.
• Dessin : chemins, courbes, arcs, coins arrondis, découpes, dégradés axiaux et radiaux, motifs répétés, transparence et modes de fusion, masques doux, dessins de forme posés autant de fois qu'on veut pour le poids d'un seul.
• Images : JPEG, PNG et données brutes ; gris, RVB, CMJN, palette ; couche de transparence, masques au pochoir, chemins de détourage, profils ICC, orientation.
• Couleur : RVB, CMJN, gris, espaces calibrés, L*a*b*, profils ICC, ton direct, plusieurs encres nommées à la fois, tables indexées.
• Codes : Code 128, EAN-13, EAN-8, UPC-A, QR code, Data Matrix, PDF417, Aztec.
• Parties interactives : champs de saisie, cases à cocher, listes déroulantes, groupes de boutons radio, boutons d'action, champs de signature, liens, signets, étiquettes de page, fils d'articles, calques, transitions de page.
• Normes : PDF/A pour l'archivage, PDF/X pour la presse, PDF/UA pour l'accessibilité, Factur-X pour la facture électronique, métadonnées XMP avec des schémas à vous, balisage complet des pages.
• Protection : chiffrement AES-256, mot de passe utilisateur et mot de passe propriétaire, droits par action.
• Lecture : ouvrir un PDF écrit par un autre outil et en lire les pages, les métadonnées, les liens, les champs de formulaire, les signets, les calques et la structure ; en reprendre une page entière dans le document qu'on écrit.
• Poids et premier affichage : niveau de compression, flux d'objets, sortie linéarisée.

L'obtenir, et le poser dans une construction

Les deux livrables viennent avec la licence : la roue Python pour la face Python et la caisse Rust pour la face Rust, chacune figée à une version. L'équipe donne le lien à l'inscription, en même temps que la clé, si bien qu'une machine de construction les récupère comme n'importe quelle autre dépendance figée.

La roue se pose dans un environnement virtuel telle quelle, et la caisse se déclare dans votre manifeste à la version qu'on vous a donnée. Rien n'a à être construit sur la machine, et rien n'a à atteindre internet à l'exécution.

Ce qu'il demande à la machine qui l'exécute

Il travaille sur place. Tout ce dont il a besoin est dans le paquet : les mesures des quatorze polices standard, les profils de couleur, les tables des codes. Un contrôle d'intégration examine l'objet compilé à chaque envoi pour confirmer que le moteur n'atteint rien par le réseau. Vos données restent sur la machine qui l'exécute.

Il s'ouvre sur une clé signée, que l'équipe remet à l'achat. La clé se lit d'un fichier, d'une variable d'environnement ou d'un coffre à secrets, et se donne au document en un appel. Avant qu'une clé soit donnée, le moteur écrit une copie d'évaluation, marquée sur chaque page qu'il dessine : le document est complet et lisible, et la marque dit ce qu'il est. C'est la façon de l'essayer avant de l'acheter.

Comment un document se monte

Une seule forme, toujours : on crée un document, on y ajoute des ressources — une police, une image, un dessin, un dégradé — qui rendent chacune une poignée, on remplit un flux de contenu avec des opérateurs de dessin, on en fait une page, on ajoute la page au document, on demande les octets.

Trois moteurs de mise en page se tiennent au-dessus de ce socle et vous épargnent toute coordonnée : le flux de texte coupe un paragraphe à une largeur, le tableau mesure ses lignes sur ce qu'elles portent et se pagine tout seul, l'empilement pose les blocs les uns sous les autres. À côté : couleur, images, formulaires, navigation, métadonnées, conformité, protection, et lecture d'un PDF existant.

La surface publique en un coup d'œil

La version 1.107.0 expose 42 modules publics et 177 noms à la racine de la caisse Rust ; la face Python déclare 237 classes. 94 exemples complets sont livrés avec, chacun en deux exemplaires jumeaux, un en Rust et un en Python, et chacun rejoué à chaque envoi pour qu'aucun ne vieillisse en silence.

Le plus court document utile

use hqf_pdf::content::Content;
use hqf_pdf::cos::Name;
use hqf_pdf::{Document, License, Page};

let mut c = Content::new();
c.set_fill_rgb(0.20, 0.40, 0.80)?;
c.rect(50.0, 700.0, 495.0, 90.0)?;
c.fill();

let mut page = Page::a4();
page.content = c.into_bytes();

let mut doc = Document::new();
doc.set_license(License::from_key(key)?);
doc.set_info(Name::new("Title"), "hqf-pdf sample invoice");
doc.add_page(page)?;

let bytes = doc.to_bytes()?;

import hqf_pdf

content = hqf_pdf.Content()
content.set_fill(hqf_pdf.Rgb(0.20, 0.40, 0.80))
content.rect(50.0, 700.0, 495.0, 90.0)
content.fill()

page = hqf_pdf.Page.a4()
page.set_content(content)

document = hqf_pdf.Document()
document.set_license(hqf_pdf.License.from_key(key))
document.set_info("Title", "hqf-pdf sample invoice")
document.add_page(page)

data = document.to_bytes()

Du texte dans une police embarquée

Seuls les glyphes que le document dessine entrent dans le fichier : une page qui porte une ligne porte une ligne de police, pas la fonte entière. La mesure passe par la même poignée que le dessin, ce qui garde le texte dans sa boîte.

let font = Font::parse(fs::read(&font_path)?)?;
let handle = doc.add_font(font);

let mut c = Content::new();
c.begin_text();
c.set_font(handle.name(), 14.0)?;
c.text_position(60.0, 760.0)?;
for line in &lines {
    c.show_glyphs(&handle.glyphs(line));
    c.text_position(0.0, -28.0)?;
}
c.end_text();

let width = handle.measure(lines.last().map_or("", String::as_str), 14.0);

font = hqf_pdf.Font.from_path(font_path)
handle = document.add_font(font)

content = hqf_pdf.Content()
content.begin_text()
content.set_font(handle, 14.0)
content.text_position(60.0, 760.0)
for line in lines:
    content.show_glyphs(handle.glyphs(line))
    content.text_position(0.0, -28.0)
content.end_text()

width = handle.measure(lines[-1], 14.0)

Un paragraphe qui se coupe tout seul

let flow = TextFlow::new(&handle, 11.0).align(align).leading(15.0);
let lines = flow.break_lines(words.paragraph, box_width);
flow.draw(&mut c, &lines, x, top, box_width)?;

flow = hqf_pdf.TextFlow(handle, 11.0, align=align, leading=15.0)
lines = flow.break_lines(words.paragraph, box_width)
flow.draw(content, lines, x, top, box_width)

Un tableau qui se poursuit page après page

Une hauteur de ligne ne se donne jamais : elle se mesure sur le texte que la ligne porte, une fois les largeurs de colonnes connues. C'est ce qui permet au tableau de décider, ligne après ligne, si la suivante tient encore. L'ajustement ne dessine rien — il rend la géométrie, donc un tableau se mesure avant qu'on décide où le poser — et un seul appel fait le tour complet et rend un placement par page.

let columns = Columns::new(
    vec![
        ColumnWidth::Fraction(1.0),
        ColumnWidth::Points(46.0),
        ColumnWidth::Points(94.0),
        ColumnWidth::Points(94.0),
    ],
    TABLE_WIDTH,
)?;

let mut table = Table::new(columns);
table.header(1);
table
    .rule(Rule::Frame, Stroke::black(0.8))
    .rule(Rule::HorizontalOther, Stroke::new(0.25, Rgb::gray(0.75)));

let pad = Padding::symmetric(5.0, 4.0);
table.push(
    Row::new()
        .cell(Cell::new(text, 9.0, label).padding(pad))
        .cell(Cell::new(text, 9.0, value).padding(pad).align(Align::Right)),
);

let mut start = 0;
loop {
    let placed = table.fit(MARGIN, TOP, TOP - BOTTOM, start)?;

    let mut content = Content::new();
    placed.draw(&mut content)?;

    let mut page = Page::a4();
    page.content = content.into_bytes();
    doc.add_page(page)?;

    match placed.outcome() {
        FitProgress::Done => break,
        FitProgress::BoxFull { next_row } => start = next_row,
        FitProgress::RowTooTall { row } => return Err(too_tall(row)),
    }
}

columns = hqf_pdf.Columns(
    [
        hqf_pdf.ColumnWidth.fraction(1.0),
        hqf_pdf.ColumnWidth.points(46.0),
        hqf_pdf.ColumnWidth.points(94.0),
        hqf_pdf.ColumnWidth.points(94.0),
    ],
    TABLE_WIDTH,
)

table = hqf_pdf.Table(columns)
table.header(1)
table.rule(hqf_pdf.Rule.frame(), hqf_pdf.Stroke(0.8))
grey = hqf_pdf.Rgb.gray(0.75)
table.rule(hqf_pdf.Rule.horizontal_other(), hqf_pdf.Stroke(0.25, grey))

pad = hqf_pdf.Padding.symmetric(5.0, 4.0)
table.push(
    hqf_pdf.Row(
        [
            hqf_pdf.Cell(font, 9.0, label, padding=pad),
            hqf_pdf.Cell(font, 9.0, value, padding=pad, align=hqf_pdf.Align.Right),
        ]
    )
)

start = 0
while True:
    placed = table.fit(MARGIN, TOP, TOP - BOTTOM, start)

    content = hqf_pdf.Content()
    placed.draw(content)

    page = hqf_pdf.Page.a4()
    page.set_content(content)
    document.add_page(page)

    if placed.done:
        break
    start = placed.next_row

Comment les refus reviennent

En Rust, tout ce qui peut refuser rend un résultat portant le type d'erreur de la bibliothèque : une énumération non exhaustive de 76 variantes, chacune nommant précisément ce qui s'est passé — une police mal formée, une image mal formée, une police introuvable, une page introuvable, deux champs nommés pareil, quelque chose qui manque pour l'impression, quelque chose qui manque pour l'archivage, quelque chose que le niveau de conformité interdit, une ligne plus haute que sa boîte, pas de licence, une licence invalide, un fichier chiffré. L'appelant filtre sur le cas exact plutôt que sur un texte de message.

La bibliothèque n'appelle ni unwrap ni panic sur un chemin de production : une donnée venue de l'extérieur — un PDF, une police, une image, un profil — qui ne tient pas la route est une issue ordinaire, rendue comme telle.

Côté Python, la même chose lève une seule classe d'erreur. Deux cas de mise en page ont leur propre exception, toutes deux filles de l'erreur de valeur intégrée, pour qu'une boucle de pagination puisse les attraper à part : une ligne de tableau plus haute que la boîte qu'on lui a donnée, et un bloc d'empilement dans le même cas.

À côté des refus, les remarques. L'écriture des octets a une forme qui rend les octets et la liste des remarques que le document porte sur lui ; le fichier est écrit et valide dans les deux cas, et une remarque signale un document qui n'est probablement pas celui que l'appelant voulait. Le contrôle face à une norme va plus loin : il rend tout ce qui se met entre le document et cette norme, sans rien écrire ni rien changer.

Ce que la version courante couvre

Version 1.107.0 : écriture et lecture de PDF, les trois générations de protection en lecture et la moderne en écriture, de PDF/A-1 à PDF/A-4, PDF/X-4, PDF/UA-1 et PDF/UA-2, Factur-X, balisage complet, signature PAdES avec le signataire fourni par l'appelant, sortie linéarisée, flux d'objets, et reprise de pages venues d'autres fichiers.

Prévus pour une version future : une façade en C pour les langages qui appellent par là, et les formats d'image JBIG2 et JPEG 2000.

Le manuel

Le manuel complet du moteur — chaque appel, chaque réglage, chaque piège — se transmet en discussion directe avec l'équipe, et c'est volontaire.

La raison est simple : ce qui aide vraiment, c'est la partie qui répond à votre question, avec l'exemple qui correspond à votre cas. Alors le chemin est celui-ci. Vous vous inscrivez sur ce site, vous nous écrivez ce que vous cherchez à faire — une facture avec son XML, un tableau de deux mille lignes, une planche à passer en presse — et l'équipe vous renvoie la partie du manuel qui traite exactement de ça, avec le code des deux côtés, Rust et Python.

Vous parlez aux gens qui ont écrit le moteur, et la réponse arrive taillée pour votre projet. En attendant, les 94 exemples livrés avec la bibliothèque couvrent la plus grande partie de ce qu'on peut lui demander, et chacun tourne tel quel.