Cent courriers dans un seul fichier

En mots de tous les jours

Écrit pour tout le monde. Il dit ce que cela pose sur une feuille de papier, et ne vous demande rien de plus.

Un envoi de cent relevés de compte, c'est un seul gros fichier et cent courriers différents. La machine qui imprime et met sous pli doit savoir où couper : deux feuilles pour celui-ci, une seule pour celui-là. D'habitude on lui donne cette information dans un second fichier, à part. Ici, on peut l'écrire dans le document lui-même, avec le nom du destinataire, sa ville, sa référence. Un seul fichier part à l'atelier, et il se suffit.

Pour un développeur

Écrit pour celui qui écrit le programme appelant : le modèle, les unités, et les réglages qui portent le poids.

document_parts déclare une hiérarchie de parties : un arbre dont les feuilles réclament chacune une suite de pages, et dont les nœuds portent ce qu'un atelier lit sur chacune. Une feuille réclame ses pages soit en nommant le premier et le dernier numéro, soit en comptant à partir de là où la partie précédente s'est arrêtée ; les deux façons se mélangent. Ce qu'une partie déclare est une liste de valeurs nommées, jamais un objet, parce que l'ordre d'écriture est celui qu'on a donné.

Chaque clé, avec son défaut

La référence : quelles clés sont obligatoires, lesquelles sont facultatives, ce que vaut chacune par défaut et quelles combinaisons le serveur décline.

• document_parts — objet, facultatif, absent par défaut. Absent, le fichier est un seul document.
• document_parts.root — objet, obligatoire. La partie à laquelle toutes les autres se rattachent.
• document_parts.node_names — tableau de chaînes, facultatif, vide par défaut. Le nom de chaque niveau de la hiérarchie, de la racine vers le bas. Un nom qu'un bon de travail ne sait pas lire est refusé.
• document_parts.record_level — entier, facultatif. Le niveau dont chaque partie tient pour un destinataire, la racine comptant pour le niveau zéro.
• Un nœud porte children (tableau récursif, vide par défaut) ou claim, jamais les deux, jamais aucun des deux.
• claim prend deux formes : {"pages": {"first": n, "last": n}} avec deux entiers ≥ 1, une suite qui finit avant de commencer étant refusée ; ou {"next_pages": n} avec un entier ≥ 1, qui reprend là où la partie précédente s'est arrêtée. Deux suites qui se chevauchent sont refusées.
• data — tableau, facultatif, vide par défaut. Les valeurs nommées que la partie déclare, dans l'ordre.
• data[].name — chaîne, obligatoire. Lettres et chiffres ASCII, _, -, . et :, commençant par une lettre, _ ou :.
• data[].value — obligatoire. Sept formes : {"text": s}, {"date": s} en ISO 8601, {"integer": i}, {"real": f}, {"boolean": b}, {"list": …}, {"fields": …} pour des valeurs nommées imbriquées.

Les parties de document sont décrites par la clause 14.12 d'ISO 32000-2 ; l'exemple ci-dessous déclare "version": "2.0", la version qu'un lecteur demande pour les honorer.

Une requête entière qui le dessine

Envoyez ceci tel quel et un PDF revient. Rien n'en a été retiré.

{
  "version": "2.0",
  "document_parts": {
    "root": {
      "children": [
        {
          "claim": { "next_pages": 1 },
          "data": [{ "name": "Recipient", "value": { "text": "Baker and Sons" } }]
        },
        {
          "claim": { "next_pages": 1 },
          "data": [{ "name": "Recipient", "value": { "text": "Westmill Dairy" } }]
        }
      ]
    }
  },
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "pages": [1],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 762 },
      "content": ["Statement for Baker and Sons"],
      "font": "sans",
      "font_size": 13
    },
    {
      "type": "text",
      "pages": [2],
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 762 },
      "content": ["Statement for Westmill Dairy"],
      "font": "sans",
      "font_size": 13
    }
  ]
}

La ligne qui l'envoie, en trois langages