BUILD 17/30: A PDF-LIB Reference

⊕ show captionAbout the Title Picture: The word counting block is 8x8 points, with a 1 point inset stroke, separated by 3 point spacers. From a layout perspective, this is the fundamental graphics structure of a Word Counting Calendar. All proportional dimensions from font sizes to calendar cell sizes and rows derive from this base unit so it looks nice.

I managed to do some foundational stuff that pushed the PDF Generator project a little further along:

1. Established that the base unit size for the Word Counting Calendar is 8pt. This unit will be used to derive all sizes and spacing used in the design generator, which should make it quite flexible.

2. Determined that pdf-lib, the PDF library I've been using, doesn't handle advanced operations as it's designed to hide that stuff. For now it will do; I made a cheatsheet to organize its documentation into something usable.

I would have liked to do more, but this is what I was able to get done today.

The Layout Math

Here's what a Word Counting Calendar looks like.

⊕ show captionFigure 1. A Word Counting Calendar

The smallest unit is the word counting block, of which there are 10 inside each day. Here's what it looks like.

⊕ show captionFigure 2. An 8pt square. The stroke is 1pt as shown by the green 1pt square.

Ten of these squares are stacked as a pyramid using precise spacing locked to a point grid, as can be seen in the green rectangles in the figure below.

⊕ show captionFigure 3. A word counting block. The spacing between the word count blocks are precisely set as integer divisors of the 8pt base unit.

Drawing this pyramid is the first task, which requires establishing the math for the layout. By defining everything in terms of a base unit square (our 8x8pt stroked word count box) using nice whole-integer divisors and multipliers, we can get a proportionally-pleasing and scaleable layout that can be reused in other forms.

Converting Layout to Drawing Commands

With this defined, I wanted to just start drawing boxes, but unfortunately the PDF drawing commands are more primitive than what you get in an illustration program like Adobe Illustrator or Affinity Designer. In particular, there is no notion of an outset and inset strokes. All strokes are center set, so you need to do some math to compensate for thisThe difference causes layout math complications similar to CSS box-sizing: content-box versus box-sizing: border-box. The original CSS spec loused this up good until the introduction of border-box fairly recently..

The math isn't difficult to compensate for this, but I wasn't sure exactly what drawing commands were available, because the pdf-lib API reference is an alphabetical listing of all the classes and their methods. It's a reference in that is lists everything that's in the library, but it's not useful.

As I am wont to do, I started making a cheat sheet for it so I can see the patterns of use in the library instead of looking something up every three seconds in the API reference.

Not much has changed in graphics context-based operators since the 1980s, but every library picks their own names and parameters for themNerdout time! PDF itself is a subset of drawing commands that were based on Postscript as a language for printers and then vector-based display devices like the Apple Lisa and later the Apple Macintosh. PDF is also an random-access object-based file format that holds various embedded elements like images, fonts, other PDF objects, forms, and other metadata.. I just need to know the names of these methods and their function signatures, as well as what graphics state options can be set and how it is persisted. PDF uses conventions similar to Postscript (see aside) and I already know how that works.

BUILD CHALLENGE COMMENTARY

I am easily annoyed by bad reference materials, and will often stop to create new ones so I can grasp the system concepts that are part of every useful system. PDF-LIB is architecturally sound from what I see in the source code, but its documentation is not much better than listing all the main exports of the library. If you know PDF internals already, then you don't need more than that. Until now, I did not know those internals, so making the cheat sheet was my way to absorb them.

While taking a break in momentum to fix this documentation hole meant I didn't actually draw anything, it should save me time in the future.

BONUS ACHIEVEMENTS

My low-productivity days continue. Ongoing lethargy, bloatedness, and fuzzy-headedness clouded my day despite ample sleep. I think I did OK today, though in the eyes of others it may have looked like procrastination: spending time to write new documentation and dilly-dallying with proportional layout systems. But this kind of detail is how I distinguish my work as a computer graphics designer from others; the result will be absolutely bulletproof and 100% explainable should anyone ask about it.