Des blocs posés les uns sous les autres, page après page
Empilez paragraphes, tableaux, images et traits : ce qui ne tient pas au bas d’une page continue sur la suivante, tout seul.
Le résultat dans un vrai PDF
Un rapport qui se met en page tout seul
Un titre, un filet, deux paragraphes, un intertitre, un tableau de vingt-six lignes et une note, donnés dans l’ordre de lecture et répartis sur deux pages par le moteur.
Ouvrir le PDF Voir l’exemple complet
Également dans les exemples : Un roman entier en anglais · Un roman entier en français · Montrer la page un sans attendre le reste
Résumé
Pensez à un rapport que vous écrivez sans jamais décider où une page finit. Vous donnez un cadre pour la première feuille et un cadre pour les feuilles d’après — le premier est souvent plus court, parce que le papier à en-tête en occupe le haut. Un paragraphe se coupe alors entre deux lignes et un tableau entre deux rangées, et la rangée d’en-tête du tableau est répétée au-dessus de la partie qui a continué. Vous pouvez aussi dire qu’un bloc ne doit jamais être coupé, et il passe entier à la feuille suivante plutôt que d’être coupé. Et là où un paragraphe est coupé, vous dites combien de ses lignes doivent rester en bas de la feuille et combien doivent partir en haut de la suivante, pour qu’aucun lecteur ne rencontre jamais de ligne orpheline ni de ligne veuve.
Techniquement
Demandé avec
"type": "stack"
Un élément stack pose une suite de blocs les uns sous les autres, dans l’ordre de lecture, et coupe les pages tout seul : aucun bloc ne dit d’ordonnée, chacun se met sous ce à quoi le bloc du dessus est arrivé, et ce qui manque de place continue dans la boîte suivante. Il prend deux boîtes : first, la place sur la page où il commence, et next, la place sur chaque page d’après. Une pile qui contient du texte se voit refuser deux boîtes de deux largeurs — ses lignes sont coupées une fois, à une largeur. Cinq sortes de blocs y entrent : text, coupé entre deux pages ligne par ligne ; table, coupé entre deux de ses lignes, avec ses lignes d’en-tête redessinées ; image, dessinée à la taille dite et jamais coupée ; rule, un trait sur toute la largeur de la boîte ; et space, de la place laissée vide qui ne dessine rien. Un bloc de texte et un bloc de tableau prennent chacun keep_together, qui pousse le bloc entier à la page suivante plutôt que de le couper. Un bloc de texte prend aussi orphans et widows, le plus petit nombre de lignes d’un de ses paragraphes laissées au bas d’une boîte où il est coupé et le plus petit nombre reporté en haut de la boîte d’après : une coupure qui en laisserait ou en reporterait moins est remontée dans le paragraphe, et, si cela ne suffit pas non plus, le paragraphe entier passe à la boîte suivante. Les deux se lisent à l’intérieur d’un paragraphe et nulle part ailleurs : un bloc dont chaque ligne est un paragraphe à elle seule est donc coupé là où la boîte s’arrête.
Schéma de la requête
Clés obligatoires : blocks, un tableau de blocs ; first, un objet de quatre coordonnées llx, lly, urx, ury ; next, le même objet pour chaque page après la première. Un bloc prend l’une de cinq formes, chacune nommée par son propre type. text prend content, UNE seule chaîne à variables où un retour à la ligne termine un paragraphe et une tabulation atteint le taquet suivant, plus les réglages d’un flow écrits à plat à côté (font, font_size, align, last_align, overlong, leading, word_spacing, break_after, break_at_punctuation, color, shadow, left_indent, right_indent, first_line_indent, space_before), plus keep_together, orphans et widows, deux entiers strictement positifs qui valent chacun, laissés de côté, le nombre de lignes que garde la version du moteur que fait tourner ce site — 2. table prend le corps d’un élément table écrit à plat, sans énoncer de boîte — la pile lui donne la place qui lui reste —, plus keep_together. image prend image, le nom d’une image fournie, avec width et height en points. rule ne prend que stroke, et sa hauteur est la largeur de ce trait. space ne prend que height. Clés facultatives de la pile : id, une chaîne par rapport à laquelle un autre élément se place ; start, la page où la pile commence, la première par défaut ; layer, le nom d’un calque déclaré ; guides, un objet avec un stroke obligatoire, les traits fins dont sont cernées les boîtes dans lesquelles la pile a travaillé — la boîte où les blocs ont été posés, la bande qu’a prise chaque bloc et, à l’intérieur, le bandeau sur lequel chaque ligne de texte est tombée et la boîte que peint chaque cellule de tableau —, absent n’en cernant aucune. Refus : first et next de deux largeurs différentes en présence d’un bloc de texte ; un orphans ou un widows à zéro. Une clé écrite sur un bloc qui ne la lit pas est ignorée en silence, non refusée.
Une requête entière qui crée un PDF
{
"standard_fonts": [{"name": "sans", "face": "helvetica"}],
"items": [
{
"type": "stack",
"start": "on_new_page",
"first": {"llx": 72, "lly": 72, "urx": 523, "ury": 700},
"next": {"llx": 72, "lly": 72, "urx": 523, "ury": 780},
"blocks": [
{
"type": "text",
"content": "Conditions of carriage",
"font": "sans",
"font_size": 16,
"keep_together": true
},
{"type": "space", "height": 8},
{"type": "rule", "stroke": {"width": 0.8, "color": [0.7, 0.7, 0.75]}},
{"type": "space", "height": 10},
{
"type": "text",
"content": "Goods travel at the risk of the sender unless insured.",
"font": "sans",
"font_size": 10,
"orphans": 3,
"widows": 3
}
]
}
]
}Texte
Un bloc de texte posé sur la page Du texte en paragraphes, avec retraits et tabulations Un tampon en travers de la page Une ligne de mots posée le long d’un chemin Une rangée de glyphes demandés par leur numéro
Où aller ensuite
Toutes les clés JSON d’une requête, en une page Les vingt-deux autres choses que l’on peut dessiner