La bibliothèque, sur votre propre machine

De quoi il s'agit

Un fichier PDF 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 met à 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 monte 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 crée 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 créé sur votre propre machine, au moment même du clic qui l'a demandé. Rien ne part, rien ne revient.
• Vos informations restent chez vous. Les noms de vos clients, leurs adresses, leurs montants restent sur votre machine du début à la fin. La bibliothèque travaille entièrement sur place, avec ce qu'elle contient dans son propre paquet. Vos données ne quittent jamais la machine qui la fait tourner.
• Elle se suffit à elle-même. Votre logiciel crée ses documents même quand la connexion est coupée, et sur un site isolé. La seule machine à surveiller est la vôtre.

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 QR codes qu'un téléphone lit pour payer, les cases qu'on remplit à l'écran, et le mot de passe qui verrouille le fichier si vous le demandez.

Ce que vous recevez, et comment cela vous arrive

Vous créez un compte sur ce site, vous payez, et le fichier à installer vous attend dans ce compte. Vous vous connectez, vous cliquez dessus, et il s'enregistre sur votre ordinateur, exactement comme n'importe quel autre fichier qu'on télécharge. La même page contient votre facture.

À côté du fichier se trouve votre clé de licence : une suite de lettres et de chiffres, à vous seul, que votre logiciel reçoit une fois et qui indique au moteur qu'il est une copie payante. Remettez le fichier et cette suite à la personne qui développe votre logiciel, et elle a tout.

Tout vient d'ici, de votre compte. Quand un fichier plus récent est prêt, il vous attend au même endroit, et vous venez le chercher quand cela vous arrange.

Ce que vous achetez, c'est le droit d'utiliser le moteur, compilé et prêt à tourner. Son code source reste chez HQF Development, comme un constructeur automobile vend le moteur et garde les plans d'après lesquels il l'a construit.

À qui cette page est destinée

Donnez l'adresse de cette page à la personne qui développe vos logiciels : plus bas, elle trouvera tout ce qu'il lui faut pour juger.

La surface publique en un coup d'œil

La version 1.307.1 du moteur expose 44 modules publics et 220 noms à la racine de la bibliothèque Rust ; la face Python déclare 312 classes, parce qu'un seul espace de noms y réunit ce que le Rust range dans un module par famille. 109 exemples complets sont livrés avec, chacun en deux exemplaires jumeaux, un en Rust et un en Python. Avant toute intégration à la bibliothèque, chacun d'eux est exécuté dans les deux langages et les deux fichiers comparés octet par octet, 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 trace entrent dans le fichier : une page qui contient une ligne contient de quoi écrire une ligne, pas la police entière. La mesure passe par le même objet que le tracé, et c'est ce qui maintient le texte dans son cadre.

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, 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);

c.begin_text();
flow.draw(&mut c, &lines, x, top, box_width)?;
c.end_text();

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

La hauteur d'une rangée n'est jamais donnée : elle se mesure sur le texte que la rangée porte, une fois connues les largeurs de colonnes. C'est ce qui permet au tableau de décider, rangée après rangée, si la suivante tient encore. Ajuster ne dessine rien : cela renvoie la géométrie, si bien qu'un tableau se mesure avant que quiconque ne décide où il va. Appelez-le une fois par page jusqu'à ce qu'il annonce qu'il a fini, ou demandez tout l'enchaînement en un seul appel et recevez 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(TableFrame::new(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(format!("row {row} is taller than a page").into());
        }
        outcome => return Err(format!("the table fitted to {outcome:?}").into()),
    }
}

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 renvoie un résultat qui contient le type d'erreur de la bibliothèque : une énumération ouverte de 96 variantes, chacune nommant précisément ce qui s'est passé — une police mal formée, une image mal formée, une police absente, une page absente, deux champs de même nom, quelque chose qui manque pour l'imprimerie, quelque chose qui manque pour l'archivage, quelque chose que le niveau de conformité interdit, une rangée plus haute que sa boîte, aucune licence, une licence invalide, un fichier chiffré. Un client filtre sur le cas exact plutôt que sur le texte d'un message.

Une donnée venue de l'extérieur — un PDF, une police, une image, un profil — qui ne tient pas est un résultat ordinaire, renvoyé comme tel et jamais un plantage. Il reste 16 arrêts brutaux sur les chemins de production. Chacun énonce l'invariant qu'il tient, et aucun n'est atteignable depuis une valeur fournie par l'appelant.

En Python, les mêmes refus reviennent sous forme d'exceptions, toutes celles de la bibliothèque sous une seule classe qu'un client attrape d'un bloc. Les 2 cas de mise en page — une ligne de tableau plus haute que le cadre qu'on lui a donné, et un bloc empilé dans le même cas — partagent en dessous une classe à eux : une boucle de pagination les attrape ensemble par cette classe commune, ou chacun séparément.

À côté des refus, des remarques. L'écriture des octets a une forme qui rend compte : elle renvoie les octets et la liste des avertissements que le document formule sur lui-même ; le fichier est écrit et valide dans les deux cas, et un avertissement désigne un document qui n'est probablement pas celui que le client voulait. L'un d'eux nomme une police entrée contre l'autorisation inscrite dans le fichier de police lui-même : c'est la licence sous laquelle la police a été achetée qui tranche, et la remarque met la question devant le client, à qui elle revient. Le contrôle contre une norme va plus loin : il renvoie tout ce que l'on sait se dresser entre le document et cette norme, sans rien écrire ni rien changer.

Ce que la version courante couvre

Version 1.307.1 du moteur : écriture et lecture de PDF, les trois générations de protection en lecture et le chiffrement AES-256 en écriture, PDF/A-2, PDF/A-3 et PDF/A-4, PDF/X-4, PDF/UA-1 et PDF/UA-2, Factur-X, balisage complet, signature PAdES dont le client fournit le signataire, sortie linéarisée, flux d'objets, et reprise de pages venues d'autres fichiers.

Le manuel

Le manuel complet du moteur — chaque appel, chaque réglage, chaque piège — est remis lors d'un échange direct avec l'équipe.

Ce qui aide vraiment, c'est la partie qui répond à votre question, avec l'exemple qui correspond à votre cas. Le chemin est donc celui-ci. Vous créez un compte sur ce site, vous nous écrivez ce que vous cherchez à faire — une facture qui contient son XML, un tableau de deux mille lignes, une feuille qui part en presse — et l'équipe vous renvoie la partie du manuel qui traite exactement cela, 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 109 exemples livrés avec la bibliothèque couvrent l'essentiel de ce qu'on peut lui demander, et chacun s'exécute tel quel.