Carrying a font inside the document

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

A typeface is a file, just like a photograph. If the document merely says "set this in such a typeface", the machine that opens it has to own that typeface already — and often it does not. The answer is simple: the typeface is tucked inside the document itself. The file weighs a little more, and in exchange it looks exactly the same on any screen and at any printer's.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

fonts carries the TrueType or OpenType fonts the request transports itself, base64-encoded, each under the name items refer to it by. A font name is resolved before anything is drawn, and in three places, most specific first: the fonts embedded in the request, the fonts kept for the client, the server's library. The server keeps a client's own font only where its entitlement provides for it. Only the subset actually used is written into the document.

Every key, with its default

The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.

fonts — array, optional, empty by default.
fonts[].name — string, required. The name items set text in this font by, in their font key.
fonts[].data — string, required. The bytes of the font file, base64-encoded. An encoding that cannot be read is refused, naming the font.

An embedded font can stand as the base of a typographic variant (font_variants) and as a link in a fallback chain (font_chains). A document claiming an archiving standard writes its fonts inside itself: that is what fonts does, where the fourteen standard faces of standard_fonts travel apart from the file.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

One name below stands for a font file: put the encoded file in its place, or send the file itself beside the description, as a part of the same call.

{
  "fonts": [{ "name": "body", "data": "PASTE_THE_FONT_FILE_BASE64_HERE" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 765 },
      "content": ["Set in a font the file carries with it"],
      "font": "body",
      "font_size": 14
    }
  ]
}

The line that sends it, in three languages

The lettering

The older Type 1 font programs The fourteen faces every reader owns The typographic niceties of a face A face whose letters you draw yourself A backup face for the rarer signs

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

See the prices See the examples

Glossary

PDF library: A piece of software your own programs use to write PDF documents. It has no window and no buttons: your program tells it what to draw, and it hands the finished file back. This site also calls it the engine, which is the same thing under another name. The server is a second program that holds the engine and answers whoever asks it for a document over the network, and the rendering service is that server running on our machines rather than on yours.
byte: The unit a file's weight is counted in, the way a parcel is counted in grams. A thousand of them make a kilobyte, and a million make a megabyte — the size of one photograph taken with a telephone. A one-page PDF here weighs between six thousand and a hundred and twenty thousand, so a hundred of them fit in the space of five photographs.
standard: A rule argued out in committee, published under a number anybody may buy and read, and identical for every firm claiming it. A claim to follow one can therefore be checked against the text. A way of working that merely spread because it worked is a habit of the trade: useful, widespread, and answerable to no text at all.
font: The drawing of every letter, digit and mark a document writes, held in a file of its own. A PDF carries the fonts it is set in inside itself, which is why it opens looking the same on a machine that has never had them. Leave them out and a reader puts another font in their place, and the layout moves.
lightened typeface: Putting into the file only the letters the document actually draws, instead of the whole typeface. A typeface holds thousands of shapes; a letter or an invoice uses a few dozen. Carrying only those is what makes the files here small.
request: One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.
server: A machine that waits for calls and answers them, running day and night with nobody sitting at it. The one that draws documents here holds the engine and hands back the finished pages; the one your website runs on is a different machine doing the same kind of job.
TrueType: One of the two shapes a typeface file comes in, and the commonest. It holds the drawing of every letter and enough instructions to keep it readable at small sizes. A document carries the file inside itself.
OpenType: The wider shape a typeface file comes in, holding either kind of letter drawing plus the typographic niceties: the pairs of letters that fit together, the figures that line up in a column, the small capitals.

Every word the site explains