I used to program on paper, then type it in later. Not all the time, but sometimes. Sometimes I’d write pseudocode. Sometimes I wrote just the code I would type in later. Sometimes just flow charts and subroutine signatures. These days, I only really do the last version, because I always have a computer nearby now. I’m not stuck in a boring lecture, for example, with only a legal pad.

Back then, and later, I’d also review code on paper. This was before I was doing formal “code review” for work. Sometimes I just wanted to look at my own code, out of the context of my computer, and think about it. Sometimes I wanted to look at somebody else’s code. Either way, putting it on paper was really useful. I could read it away from the rest of the distractions of my computer, and I could draw circles and arrows in a bunch of different colors.

The way I did it, then, was to use Vim’s :hardcopy command. Like the rest of Vim, it has slightly strange but actually very good documentation. I worked on Windows in the early 2000s, and I could enter :ha and get a printout. Sometimes, though, I’d use the a2ps program instead. That was a bit more work to use, but it produced better listings (as I recall), especially because it would print two pages of code on one piece of paper, while remaining quite legible.

Over time, I printed code less often. This was partly, but not entirely, because I was coding less. Lately, I’ve been coding a bit more. On top of that, I do a lot of it sitting not twenty feet from Mark Dominus, who seems to print out nearly every hunk of code he reviews. This has brought back memories of how much I got out of printing code. It also led to him asking me a question or two about a2ps that left me a little surprised and embarrassed that I had forgotten how to use it well.

Over the last twenty four hours, I’ve tried to get back up to speed, and to find (and simplify) a method for printing code listings on demand. This blog post is a bit of a recounting of that work, and what I found.

PostScript

I wanted to start with a2ps but I have to write a prelude about PostScript.

The “a” in a2ps stands for “any”. The idea is that you feed it basically any kind of source code (or plain text) and it will build a PostScript file for printing. PostScript is a programming language created by Adobe and used (mostly but not entirely) to drive printers. It’s a bit of a weird language, but it’s postfix and stack-based, so I have a soft spot in my heart for it. You can see three books on PostScript on shelf three in my post about my technical bookshelf. Ten years ago, showing the kid different kinds of programming, we wrote this program:

/text {
  /Times-Roman findfont exch scalefont setfont
} def

newpath 24 text 200 400 moveto
        (You're standing on my neck!) show

newpath 284 284 72 0 360 arc stroke
newpath 265 300 12 0 360 arc fill
newpath 303 300 12 0 360 arc fill
newpath 250 225 moveto 275 225 lineto
        275 200 lineto 250 200 lineto
        250 225 lineto stroke
newpath 275 225 moveto 300 225 lineto
        300 200 lineto 275 200 lineto
        275 225 lineto stroke

newpath 300 225 moveto 325 225 lineto
        325 200 lineto 300 200 lineto
        300 225 lineto stroke

It draws a skull with the caption “You’re standing on my neck!”. Try it!

But how? Well, in theory you can send it directly to your printer with lp, but on current macOS (unlike older versions) you will get this error: Unsupported document-format “application/postscript”.

I’m not sure exactly where the problem lies. My suspicion is that it’s in the CUPS service that serves as the mediator between the user and the printer on macOS. Probably I could get around this by using mDNS and IPP, and honestly I am tempted to go learn more. But there was a simpler solution: ps2pdf converts a PostScript program to a PDF file. It’s shipped with Ghostscript and is easy to get from Homebrew.

PDF is actually based on PostScript, but I don’t know the details. PostScript has also been used for rendering graphical displays, using a system called Display PostScript (DPS), which was developed by both Adobe and NeXT, and later became the basis for the MacOS X display system. So, why doesn’t macOS support PostScript well anymore? Honestly, I don’t know.

Anyway: lots of the things I tried using for printing output PostScript, which is meant to be easy to send on to the printer. With ps2pdf installed, printing these files isn’t so hard. It’s just a drag that they can’t be send right to the lp command.

a2ps

Right, back to a2ps! Given a piece of source code, it will spit out a PostScript program representing a nice code listing. Unfortunately, running it out of the box produced something pretty awful, and I had to fumble around a good bit before I got what I wanted. I didn’t save a copy, so if you want to see it, you can try to reproduce it on your own. The problems included being off center, running off the page margins, using a mix of different typefaces in one source listing, using awful colors, and probably other stuff. So, I had to consult the manual. Unfortunately, I started doing that by running man a2ps, immediately hitting the problem that has infuriated geeks for decades: I got a pretty mediocre man page with a footnote saying the real docs were in Texinfo. And info isn’t installed.

Eventually I found myself reading the a2ps manual as a PDF on the web. With that (and with some help from Mark), I found that much of what I needed would come down to putting this in ~/.a2ps/a2psrc:

Options: --medium=letter
Options: --line-numbers 1
Options: --prologue color

This set my paper size, turned on line numbering on every line, and said that I wanted highlighting to be expressed as color, not just font weight.

There were two problems that I could not get over:

1. Typeface mixing! Everything was in fixed text except for literal strings, which were (to my horror) represented in a proportional font.
2. Awful colors. For example, subroutine names were printed in black on a bright yellow background. Probably some people think this is fine. I did not. (The a2ps manual admits: “It is pretty known that satisfying the various human tastes is an NEXPTIME-hard problem.”)

So, how to fix it? By hacking on a PostScript file!

a2ps combines (roughly) two things to build the final PostScript program: the prologue, and the program. (There’s also the header (“hdr”), but that’s included directly by the prologue. Let’s not split hairs.)

The program is a series of PostScript instructions that will print out your listing. The prologue is a set of function definitions that the program will used. The a2ps binary (written in C) reads your source document, tokenizes it for syntax highlighting, and then emits a program. For example, here’s a hunk of output for the Perl code that I’ll be using in all the samples in this post.

0 T () S
(sub) K
( ) p
(richsection) L
( \(@elements\) {) p n
(185) # (  Slack::BlockKit::Block::RichText::Section->new\({) N
0 T (    elements => _rtextify\(@elements\),) N
0 T (  }\);) N
0 T (}) N
0 T () N
(190) # () S

The parentheses are string delimiters, and because PostScript is a postfix language, when you see (richsection) L it’s calling the function L with the string “richsection” on the stack. True, there may be other things on the stack, but I happen to know that L is a one-argument function. It looks like this:

/L {
  0 0 0 FG
  1 1 0 true BG
  false UL
  false BX
  fCourier-Bold bfs scalefont setfont
  Show
} bind def

This prints the string on the stack to the current position on the page in black on bright yellow. Yuck. This function comes from the “color” prologue, which is installed in share/a2ps/ps. There’s no way to change parameters to it, so the recommended practice is to copy it into ~/.a2ps and edit that. This would be more horrifying if there were new version of a2ps coming out with notable changes, but there aren’t, so it’s … fine.

I hacked up a copy of color.pro and changed the prologue option in my configuration file to rjbs.pro. I renewed my PostScript programmer credentials! While doing this, I also fixed the typefaces, replacing Times-Roman with Courier in the definition of str, the string literal display function.

This got me some pretty decent output, shown here, and linked to a PDF:

By the way, all the samples in this post will be from formatting this copy of Slack::BlockKit::Sugar.

This was fine, but I had two smaller problems:

1. The syntax highlighting is a bit anemic (but not so bad).
2. The line spacing is a little tight for me.

Fixing the first one means editing the “style sheet” for Perl. This isn’t like CSS at all. It doesn’t define the style, it defines how to mark up tokens as being one thing or another. The functions in the prologue will do the styling. I looked at what might be worth putting here as a sample, but I think if you want to see what they look like, you should check out the perl.ssh file itself. It’s fine, but it’s also obvious that making it better would be an ordeal. I bailed.

Fixing line spacing felt like it should be easy, though. Surely there’d be an option for that, right? Sadly, no. I decided to use my PostScript expertise to work. Here’s the N function, which renders a line and moves to the next position:

/N {
  Show
  /y0 y0 bfs sub store
  x0 y0 moveto
} bind def

bfs is the “body font size”. We’re moving a little down the page by reducing the y position of the cursor by the font size. What if we did this?

/y0 y0 bfs 1.1 mul sub store

That should add a 10% line spacing increase, right? Well, yes, but the problem is this: remember how the a2ps binary is responsible for spitting out the PostScript program? That’s where it computes how many lines per page. By mucking with the vertical spacing, we start running off the end of the page. We need to change the number of lines that a2ps puts on the page. No problem, we’d just tweak this code:

job->status->linesperpage =
  (int) ((printing_h / job->fontsize) - BOTTOM_MARGIN_RATIO);

…at which point I realized I had to install automake. I did, and I went a few steps further, and finally gave up. It was too annoying for a Saturday.

What if instead I changed the default style? I won’t bore you with the PostScript, but I made a new function, vbfs, defined as 0.9 of bfs. I updated all the rendering functions to use that value for size, but the full value was still used for line spacing. This worked! But changing the font size mean that I was ending up with horizontal dead space. I was scaling everything down, when all I wanted to scale up was the vertical space. It was unsatisfactory, and I decided to settle for the tight line spacing.

…for about five minutes. And then I decided to try the other GNU program for turning source code into PostScript.

enscript

GNU Enscript bills itself as “a free replacement for Adobe’s enscript program”. I don’t know what that was, but I can tell you that enscript is basically “a2ps, except different”. It serves the same function. I fed it the same hunk of code, but not before reading the manual and finding --baselineskip, which is exactly what I wanted: a way to control line spacing. I used this invocation:

enscript lib/Slack/BlockKit/Sugar.pm \
  --columns=2       \
  --baselineskip=2  \
  --landscape       \
  --color           \
  --highlight       \
  --line-numbers    \
  --output Sugar.ps

It looked pretty good at first, when looking at the first page of output (not pictured here). On the other hand, here’s page three:

The line spacing is nice (and maybe nicer when cranked up), and the colors aren’t offensive. But they’re all wrong. Part of the issue is that this source is using =func as if it was a real Pod directive, which it isn’t. On the other hand, it’s real enough that Perl will ignore the enclosed documentation. Syntax highlighting should start at =func and end at =cut. The syntax definition for Perl in enscript is very strict, and so this is wrong. And that means that the documentation’s syntax highlighting ends up all wrong all over the place. It’s unusable.

Syntax highlighting in enscript is different than a2ps’s style sheets. Instead, it’s programmed with a little “state” language. You can read the Perl state program, but I’m not sure I recommend it. It’s relatively inscrutable, or at least it is written in terms of some other functionality that doesn’t seem well documented. Fixing the Pod thing seemed trivial, but all I could imagine was an endless stream of further annoyance. Maybe this isn’t fair, but it’s where I ended up.

At this point, settling on a2ps might have been a good idea, but instead I moved on to Vim.

Vim :hardcopy

Way up at the top of this post, I mentioned that I had used Vim in the past. So, why not now? Well, reasons. The first one is that I didn’t remember how, and I knew that “it didn’t work anymore”. But I was in for way more than a penny by now, so I went further down the rabbit hole.

It turned out that “it didn’t work anymore” was trivial. I was getting this error:

E365: Failed to print PostScript file

Right. Because lp doesn’t handle PostScript anymore. I could just write the PostScript file to a file, then apply ps2pdf. I did so, and it was bad. The good news was that getting from bad to okay wasn’t so hard. I had to set some printoptions in Vim.

set printoptions=paper:letter,number:y,left:5pc

This sets my paper size (which I’d already had in my .vimrc actually!), turns on line numbering, and reduces the left margin to 5%. The default left margin was 10%, which was just way too much. It’s nice to have space to write, but I usually do that in the whitespace on the right side of the code. To print to a file in Vim, you can execute :hardcopy > filename.ps. With these settins, I got this output:

The main problem here is that it’s one-up. Only one page of code per sheet of paper. It’s easy to read, but it takes twice as much paper. It’s a waste, and also leads to more desk clutter than necessary. My desk is enough of a mess as it is.

Fortunately, there’s a solution for this! The slightly obscure mpage command reads a PostScript document in, then spits out another one that’s multiple pages per sheet. It hasn’t quite fallen off the web, but it’s not extremely well published. Here’s a link to its man page hosted at a fairly random-seeming location at CMU. Fortunately, it’s in Homebrew. I could take the PDF above and run this:

mpage -2 -bLetter -S Sugar.ps > Sugar2.ps && ps2pdf Sugar2.ps

The -S option there is fairly critical. It says “allow non-square scaling”. In theory this might introduce some distortion, but I can’t notice it, and it gets a better use of space on the page. I also go back to my printoptions in Vim and set all the margins to 0pc. Since mpage will be adding a margin when it produces the two-up pages, I don’t need any margin on the pages it’s combining. I get four more lines per page, plus more space on the right of each listing.

Here’s what we get:

I wasn’t sure how to get a better set of colors. I’m pretty sure it’s possible, but I’ll have to think about it and play around. There is a very large benefit here, though. The syntax highlighting that I get in the PDF will be based on the same syntax highlighting that I’m used to seeing every day in Vim. I know nothing is critically wrong, and if there was, I’d be very motivated to fix it, because I’d be seeing it every day in my editor!

The real problem, for fixing the colors, is that I use a dark-background color scheme in Vim. Printing tries to emulate your color scheme, but has to correct for the fact that it’s going to print on white paper. The real answer is to have an alternate color scheme ready for printing.

Still, I’m pretty happy with this. All that remained was to make it really easy. So, I wrote a stupid little Perl program that finds a PostScript file on disk, runs it through mpage, then ps2pdf, then puts it on the Desktop and opens it in Preview. Then I updated my Vim configuration to make :hardcopy send print jobs to that instead of lp. It looks like this:

set printexpr=ByzantinePrintFile()
function ByzantinePrintFile()
  call system("/Users/rjbs/bin/libexec/vim-print-helper "
    \.. v:fname_in
    \.. " "
    \.. shellescape(expand('%:t'))
  \)
  call delete("v:fname_in")
  return v:shell_error
endfunc

Vim script is still weird.

This is where I’ll stop, feeling content and full of PostScript. I think for many people, all this PostScript nonsense would leave a bad aftertaste. For them, there’s another option…

Vim 2html.vim

Vim ships with a helper file called 2html.vim, which exports the current buffer as HTML, using the settings and colors currently in use. You can enter this in your Vim command line:

runtime! syntax/2html.vim

…and you’ll get a new Vim buffer full of HTML. The parity with the Vim display is impressive.

The problem is that so far, I’ve found going from HTML to a two-up PDF is too much of a pain. Possibly there’s some weird route from HTML to PostScript to piping through mpage but I think I’ll leave that adventure for another day or another dreamer. Me, I’ve got printing to do.

This post will be short but baffling.

In the following snippet, the ^@ sequences indicate literal NUL bytes in the source document.

use v5.36.0;
my $i = ^@ 1;
sub foo () {
 say q^@Hell0, w0rld.^@;
 $i^@++;
}

foo(^@);

say ^@$i;

This program will run and print:

Hell0, w0rld.
2

The NUL bytes are all ignored… except for the two that act as the string delimiters for the q-operator. As near as I can tell without reading any of the source for the perl tokenizer (or related code), NUL is treated like whitespace. I am gobsmacked. I know all kinds of weird stuff about Perl, but this one surprised me.

It came up when I tried to run a bunch of small programs through perltidy, and it refused to process just one file, because it was “binary”. There was a NUL after a subroutine’s opening brace. I removed it out, but not because it was a syntax error. Just because it was not in good taste to leave it there.

The other day, a concatenation of circumstances led me to thinking about the lousy state of sending formatted text to Slack. We have a bot called Synergy at work, and the bot posts lots of content. Mostly it’s plain text, but sometimes we have it send text with bold or links. This is for a couple reasons. Our bot supports channels other than Slack (like SMS and Discord and the console), so we can’t express everything in Slack-oriented terms. But even doing so would be hard, because of the APIs involved.

Slack’s APIs are dreadful, and not in the usual ways. At first glance, they look fairly modern and straightforward. Maybe they seem a bit over-engineered, but Slack is a large-scale system, and some of that is to be expected. But when you really start using them, they’re surprisingly painful. Common patterns turn out to have weird exceptions. Things don’t compose because of seemingly-arbitrary restrictions. The documentation seems auto-generated, with all that entails: missing context, lack of an overview of any given abstraction, no helpful hints. Auto-generated documentation is, at least, usually accurate and comprehensive in the methods and types provided, because it comes from the source code. Unhappily, the Slack documentation is frequently inaccurate.

sending text isn’t good enough

So, as I said, the state of the Slack APIs and developer ecosystem is such that I’ve avoided trying to get more out of it. Then again, the kind of formatting we can use easily in Synergy’s messages is not great. It usually uses roughly this:

await $slack->api_call('chat.postMessage', {
  text    => $text,
  channel => $channel,
  as_user => jtrue(),
});

Nice and simple! So, how does this get us rich text? Well, the $text content just gets formatted with Markdown! No, sorry, wait… with mrkdwn. The Slack “mrkdwn” format is like Markdown, but worse. It differs in how bold, italic, and link work, at least. Maybe other things, too. You can disable this, but then you just get plain text, which has its own problems.

This is an actual, practical problem. When we display search results from our work tracker, Linear, imagine we find an issue called “problems with Secure::Key::HSM”. This will get displayed as “problems with Secure:🔑:HSM” because mrkdwn is always on the lookout for emoji colon codes.

mrkdwn is intended for human writers, just like Markdown is intended for human writers. (That said, I don’t actually know whether a human can avoid that problem above.) If you want your software to write rich text output, you should use a less ambiguous, tricky format. For example, HTML. In Slack, the format provided is BlockKit and especially its “rich text” blocks. BlockKit is a (mediocre) object model for describing content that Slack can display in many different contexts (called “surfaces”), like: modal dialogs, messages, canvases, and more. Instead of supplying a hunk of mrkdwn, you can supply an array of “blocks”, and Slack will display them. Blocks are not ambiguous. Take the problematic Linear issue from the last paragraph. The form we want would be expressed in BlockKit like this:

[ {
  "type": "section",
  "text": { "type": "plain_text", "text": "problems with Secure::Key::HSM" }
} ]

Great! (The bad form is actually exactly the same, but replace plain_text with mrkdwn.)

sending rich text is a big pain

But let’s say that in the message above, you wanted to call them “serious problems”, with the italics. You can’t use plain text, because you want italics. You can’t use mrkdwn, because you’d get that emoji. You need a rich text block. Like so:

[
  {
    "type": "rich_text",
    "elements": [
      {
        "type": "rich_text_section",
        "elements": [
          {
            "type": "text",
            "text": "serious",
            "style": { "italics": true }
          },
          {
            "type": "text",
            "text": " problems with Secure::Key::HSM"
          }
        ]
      }
    ]
  }
]

Kinda great, but tedious. Unambiguous, but awful to write.

Also, there’s a bug. I put “italics” when I should’ve put “italic”. No problem, because you can easily expect an error like this:

Unknown property "italics" at /0/elements/0/elements/style

Not great, but gets the job done, right? Well, the problem is that while you can easily expect that, you won’t get it. What you get is this:

invalid_blocks

No matter how serious or trivial the error, and no matter where it is, that’s what you get. That is the entire body of the response to sending any invalid message. Then you try to go re-read the documentation about how it should work, and you pour over each and every element in the structure and the corresponding documentation. Worse, that documentation, as I said, is bad. I found at least a handful of errors (now reported). The combination of (bad docs) and (bad error messages) and (wordy structure) made it easy to sigh and go on using using (sigh) mrkdwn.

making it hard to screw up

Well, now I didn’t want to do that anymore, so I wrote a bunch of classes, representing each of the kinds of blocks. (More on “kinds of blocks” below.)

Here’s a piece of rich text I generated for testing:

Here is a safe link: click me

• it will be fun
• it will be cool 🙂
• it will be enough

This is easy to type, and simple, and I wanted it to be easy to program.

Here’s the code for that four line Slack rich text:

my $blocks = Slack::BlockKit::BlockCollection->new({
  blocks => [
    Slack::BlockKit::Block::RichText->new({
      elements => [
        Slack::BlockKit::Block::RichText::Section->new({
          elements => [
            Slack::BlockKit::Block::RichText::Text->new({
              text => "Here is a ",
            }),
            Slack::BlockKit::Block::RichText::Text->new({
              text  => "safe",
              style => { italic => 1 },
            }),
            Slack::BlockKit::Block::RichText::Text->new({
              text => " link: ",
            }),
            Slack::BlockKit::Block::RichText::Link->new({
              text  => "click me",
              unsafe => 1,
              url   => "https://fastmail.com/",
              style => { bold => 1 },
            }),
          ],
        }),
        Slack::BlockKit::Block::RichText::List->new({
          style => 'bullet',
          elements => [
            Slack::BlockKit::Block::RichText::Section->new({
              elements => [
                Slack::BlockKit::Block::RichText::Text->new({
                  text => "it will be fun",
                }),
              ]
            }),
            Slack::BlockKit::Block::RichText::Section->new({
              elements => [
                Slack::BlockKit::Block::RichText::Text->new({
                  text => "it will be cool",
                }),
                Slack::BlockKit::Block::RichText::Emoji->new({
                  name => 'smile',
                }),
              ]
            }),
            Slack::BlockKit::Block::RichText::Section->new({
              elements => [
                Slack::BlockKit::Block::RichText::Text->new({
                  text => "it will be enough",
                }),
              ],
            }),
          ],
        }),
      ],
    })
  ]
});

Okay, the good news is that if I screw up on any property or type, this code will give me an error message that tells me a lot more about what happened, and it happens before we try to send the reply. The error message isn’t great, but it will be something roughly like “Slack::BlockKit::Block::RichText::Text object found where ExpansiveBlockArray expected in Section constructor”. Maybe a little worse. But it’s descriptive, it has a stack trace, and it happens client-side.

The bad news is that it took 57 lines of Perl, mostly fluff, to generate four lines of text. This made me sour, so I needed some sugar:

use Slack::BlockKit::Sugar -all => { -prefix => 'bk_' };
bk_blocks(
  bk_richblock(
    bk_richsection(
      "Here is a ", bk_italic("safe"), " link: ",
      bk_link("https://fastmail.com/", "click me", { style => { bold => 1 } }),
    ),
    bk_ulist(
      "it will be fun",
      bk_richsection("it will be cool", bk_emoji('smile')),
      "it will be enough",
    ),
  )
);

This is 13 lines. Maybe it could be shorter, but not much. All the same type checking applies. Also, each function in there has a reusable return value, so you could do things like:

# provide either an ordered List of 2+ Sections or just one Section
my @reasons = gather_reasons();
return bk_blocks(@reasons > 1 ? bk_olist(@reasons) : @reasons);

how does it work?

It’s practically not worth explaining how it works. It is almost the definition of “a simple matter of programming”. You can read the source for Slack::BlockKit on GitHub. It’s a bunch of Moose classes with type constraints and a few post-construction validation routines. I think it’s a pretty decent example of how Moose can be useful. Moose made it easy to make the whole thing work by letting me decompose the problem into a few distinct parts: a role for elements with “style”, a set of types (like for “which kinds of elements can be children of this block”), and BUILD submethods for validating one-off quirks that can’t be expressed in type constraints.

The thing worth nothing, maybe, is how it doesn’t work. It isn’t auto-generated code. It’d be pretty nice if Slack was publishing some data description that could automatically generate an API, maybe with some sugar. I don’t normally enjoy that sort of thing, but it’d probably be better than doing this by hand and then digging for exceptions, right? Anyway, they don’t do that, so I wrote this by hand. It felt silly, but it was only a few hours of work, much of it done while on a road trip.

some of the problems I encountered

I feel a bit childish calling out the problems with the BlockKit API (or its documentation), but I’m going to do it anyway.

First, I’ll say that my biggest problem is the lack of a clear object model. The term “block” and “object” and “element” are used without much clear distinction. It might be safe to say “anything with a block_id propety is a block”. Beyond that, I wouldn’t bet much. Many Block types have an elements property. Some say they contain “objects” and some say “elements”. A rich_text_list thing might be an object, or maybe an element? Or maybe an element is a kind of object? There’s also a kind of object called a “composition object”, which just seems to be another name for “types we will reuse”. I can’t tell if a composition object is substantially different from an “element”. They have their own page in the docs, anyway.

This isn’t a huge deal, but a hierarchy of types makes it easier to build a system that has to represent… well, a hierarchy of types!

non-isolated type definition

Next, the types that do exist are not clearly separated. The most jarring example of this might be:

1. some of the rich text blocks can contain, in their elements, “link” objects
2. “link” objects have a set of styles, chosen from { bold, code, italic, strike }
3. …but the “link” objects contained in a “preformatted” rich text block can only have bold or italic styles

So, the type definition for a link object isn’t a complete definition, it’s contingent on the context. To verify the object, you have to put the verification into the parent: when constructed, a RichText::Preformatted object must scan its children for Link objects and raise an error based on their styling. (The alternative would be to have a distinct PrefomattedLink type, which sounds worse.)

But actually the alternative is to do nothing. This restriction isn’t enforced, and in fact using the strike style works! (I can’t say whether the code style works, since by definition a link in a preformatted section will be in code style.)

missing or bogus properties

The text object (not to be confused with the text composition object) exists almost entirely to pass along its text and style properties for rending. But the text property isn’t documented. It appears in nearly every example, though, so you can figure that one out.

Quite a few blocks are documented as having pixel-count properties, like the border property on the list block. When used at all, these trigger an invalid_blocks error. Possibly their validity is related to the surface onto which they’re rendered, but I can’t find any documentation of this.

Other properties have incorrect type definitions. The preformatted block says its elements can contain channel, emoji, user, and usergroup objects. Trying to use any of those, though, will get an error. Only link and text objects actually work.

what’s next?

I filed an pull request against Slack::Notify, which Rob N★ quickly applied and shipped (thanks!), which makes this code easy to use. So, the iron is hot and I want to strike it. I’ll probably put this in place to replace a couple gross bits in Synergy.

But also, I should write some tests first.

But also, and much less likely, it’d be great to have some form of Markdown Esperanto, where I could write Markdown (or the like) in my code, and then have it formatted into the right output based on the output channel. Given a Markdown DOM, it would be fairly simple to spit out BlockKit rich text. I think. That would be cool, but I’m pretty sure I won’t ever do it. We’ll see, though.