Ce dont le document dit être fait

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.

L'encre sur une page n'a pas d'ordre à elle. Une personne voit que les gros mots du haut sont un titre et que les deux colonnes se lisent l'une après l'autre, mais un programme ne voit que des marques posées à des coordonnées, dans l'ordre où elles ont été dessinées. C'est ici qu'on le lui dit : ceci est le titre, voici les paragraphes, ceci est une figure, et voilà l'ordre dans lequel on les lit. Une fois que c'est écrit, un document se lit correctement à voix haute, se copie sans se mélanger, et se réagence sur un petit écran. On peut aussi dire qu'un passage est dans une autre langue, pour qu'il soit prononcé comme il faut, et donner à une image une phrase qui la décrit pour quelqu'un qui ne la voit pas.

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.

Écrit au premier niveau d'une requête, sous "structure"

structure est ce dont le document dit être fait, dans l'ordre de lecture : les éléments qui tiennent les courses marquées que les articles ont laissées derrière eux. Un article ouvre une course marquée avec tag et mark ; l'arbre réclame ensuite cette course par son étiquette, et c'est ce qui relie l'encre au sens. Absente, le fichier ne dit rien de lui-même et se lit dans l'ordre où l'encre est tombée. lang est la langue des mots, en étiquette BCP 47, et un nœud dit la sienne là où un passage est dans une autre. roles laisse la demande employer des balises à elle, chacune dite se lire comme une de celles que la norme nomme. Un nœud porte soit des enfants, soit une course marquée par content, soit une branche bâtie ailleurs.

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.

• structure — objet, facultatif. Absent, le fichier ne dit rien de lui-même.
• structure.lang — chaîne, facultative, une étiquette BCP 47. La langue dans laquelle les mots du document sont écrits.
• structure.roles — tableau, facultatif. Des balises propres à la demande, chacune un objet de tag et standard, la balise de la norme comme laquelle elle se lit.
• structure.children — tableau, facultatif. Les éléments en tête de l'arbre, dans l'ordre de lecture.
• Un nœud prend tag, obligatoire, le nom que la norme donne à ce qu'il est (Document, Sect, H1, P, Figure) ; puis soit children, d'autres nœuds ; soit content, l'étiquette d'une course marquée qu'un article a laissée ; soit branch, le nom d'une branche bâtie ailleurs.
• Un nœud prend aussi namespace, lang pour un passage dans une autre langue, alt, une phrase décrivant ce qu'on ne peut pas voir, et actual_text, ce qu'un passage dit vraiment quand son encre ne l'épelle pas.

Portée : le document entier. C'est contre elle qu'accessible est jugée ; seule, elle ne coûte rien et se lit simplement par qui veut l'ordre et le sens plutôt que les coordonnées.

Une requête entière qui le dessine

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

{
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "structure": {
    "lang": "en-GB",
    "children": [
      {
        "tag": "Document",
        "children": [
          { "tag": "H1", "content": "heading" },
          { "tag": "P", "content": "opening" }
        ]
      }
    ]
  },
  "items": [
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 720, "urx": 523, "ury": 760 },
      "content": ["What this document is"],
      "font": "sans",
      "font_size": 20,
      "tag": "H1",
      "mark": "heading"
    },
    {
      "type": "text",
      "rect": { "llx": 72, "lly": 660, "urx": 523, "ury": 710 },
      "content": ["It is read in the order the tree gives, not the order of the ink."],
      "font": "sans",
      "font_size": 11,
      "tag": "P",
      "mark": "opening"
    }
  ]
}

La ligne qui l'envoie, en trois langages

Glossaire

norme

Une règle débattue en commission, publiée sous un numéro que n'importe qui peut acheter et lire, et identique pour toutes les entreprises qui s'en réclament. Dire qu'on la suit peut donc être vérifié face au texte. Une façon de faire qui s'est simplement répandue parce qu'elle marchait est une habitude du métier : utile, très suivie, et qui ne répond devant aucun texte.

CMJN

Les quatre encres d'une imprimerie : le cyan (un bleu), le magenta (un rose), le jaune et le noir. Un écran, lui, fabrique ses couleurs avec de la lumière. Un document qui part à l'impression dit donc ses couleurs en encres, et non en couleurs d'écran.

PDF balisé

Un PDF qui range son texte en plus de le dessiner : ceci est un titre, ceci un tableau, cette case appartient à cette colonne. C'est ce qui permet au logiciel qui lit à voix haute, ou au programme qui récupère les chiffres, de comprendre la page.

ordre de lecture

L'ordre dans lequel un document est fait pour être lu, qui n'est pas toujours celui dans lequel il a été dessiné. Sur une page à deux colonnes, l'encre peut descendre une colonne puis l'autre, ou passer de l'une à l'autre ; le logiciel qui lit la page à voix haute suit l'ordre déclaré plutôt que de deviner.

Tous les mots que le site explique