The Naked King (part 2) #FlashFicFriday

Image credit: openclipart.org

Once upon a time, in the Strange Lands north of Aht-Lann-Tah, a king got swindled by two dudes pretending to be tailors… yeah, you know that story. You have to wonder about a king, who would be willing to expose himself to louts who weren’t worthy to see his wardrobe, but royalty doesn’t see reality in the way you or I would at all. And even if the clothing was invisible, the dolt should have felt it as he got dressed.

But I digress. You know the next part: a child called out, “He’s naked!” and all the other folk watching the grand parade could no longer pretend. I’m here to tell you what happened after that.

• • •

The fake tailors had long skedaddled. King Atate issued a proclamation, offering a huge reward for their capture, saying they had created clothing that was invisible to not only the unrefined, but to everyone. That was met by general derision, and a running joke in which patrons attempted to pay for drinks and groceries with invisible money, claiming that only the best merchants could see the coinage. The merchants went along with the joke… as long as the customers provided visible coinage in the end, because it was funny.

As far as I know, the swindlers were never caught. They may have kept running until they dropped dead from old age. Jokes or no, that didn’t stop citizens from trying to find them, and some dishonest folk attempted to pull a reverse Anastasia of sorts, claiming their battered victims were the swindlers.

The latter stopped when the king refused to grant further audiences. Most of his subjects assumed he ducked out to his summer palace; but there were persistent rumors that he owned a villa outside Aht-Lann-Tah, and had fled there.

Now the authorities in Aht-Lann-Tah were eager to capture King Atate, as he had been accused on many occasions of mistreating (in the worst ways) local serving-wenches, claiming royal privileges outside his own realm. But honor and their laws meant that they would not move unless they knew he was in their realm.

The great weakness of royalty is, they are insulated from reality. Thus, they often do not understand that the best course of action is to take the L and distract their subjects with some other spectacle. And so it was with King Atate. His attempts to find the child who had spoken out during the parade fell flat. A nobody can be anybody, after all. Other attempts to address the issue were met with peals of derisive laughter.

So King Atate, having indeed fled to his villa outside Aht-Lann-Tah, drank himself into a semi-functional stupor and commanded his servants to transcribe a speech and take a photo of himself, sitting at a table with his traditional non-swindled regalia, as he spoke.

Unfortunately (for King Atate), he had neglected to remove the Jeroboam’s Pizza box from the table as he spoke. Jeroboam is a popular local chain in Aht-Lann-Tah, and the authorities pounced as soon as they saw the photo. The embassy protested, but only diplomats have immunity—not kings.

And so, King Atate was (to the relief of many in his kingdom, not to mention the girls held captive in his villa) taken into custody. The child who had been brave enough to call out the monarch issued a note: If only that pizza box had been invisible as your clothes.

After a short period of uncertainty, the kingdom righted itself. With no heir to the throne, the dukes formed a council, and managed the affairs of the realm as best as they could (by comparison, they did well). And so, except for King Atate and his hangers-on, they all lived happily… until the next thing happened.

The “next thing” never takes long in the Strange Lands.

Adventures of a #techcomm geek: Still I look to find a reason

A future project—I plan to start on it in earnest early next year—is requiring a specific set of “reset reason codes.” The codes, and their meanings, are described in MULPI (a standard specification in the industry I work in)… at least, so said the ticket the developers are using to track this piece of the melange that makes up modern communication devices. I had a PDF copy of MULPI on my work system already, and once I realized the spec said “initialization reason” where my co-workers used the more direct “reset reason,” I found the table in section C.1.3.6. Hey, it’s only 887 pages.

Needle in a haystack

Besides it being a table—I hate tables, in general—I found two glaring issues:

• I wanted the number in the left column, not the right
• The table did not describe the conditions that would cause the reset

The latter was a matter of searching the PDF on initialization reason, but first I wanted to reverse the columns in that table. Copying the table out of the PDF, and pasting into a terminal window, gave me one line per cell:

Initialization Reason

Initialization Code

POWER-ON

1

T17_LOST-SYNC

2

ALL_US_FAILED

3

BAD_DHCP_ACK

4

etc

Once again, I had a textual nail, and I reached for my hammer: awk. Redirecting the lines into a junk file (literally called junk), I decided to create tab-delimited output with the column order reversed:

awk '{getline num; print num "\t" $0; next}' junk

Mirabile dictu, it worked the first time! The getline function does a sort of look-ahead, grabbing the next line of input before the normal awk loop can get to it. So it’s pretty easy to grab two lines, print them in reverse order, and move on to the next pair.

“Oh,” I then thought, “I should have made it a Markdown table.” Rather than start over, I just piped the output of the first awk script into another one:

awk '{getline num; print num "\t" $0; next}' junk | \

awk 'BEGIN {FS="\t"} NR==2 {print "|-----|-----|"} \

   {print "|", $1, "|", $2, "|"}'

Once again, first time was the charm! This “long pipeline of short awk scripts” approach does make debugging easier, especially if you don’t have to do any debugging. If you’re not familiar with awk, let me pretty up that second script to make it easier to follow:

BEGIN {

    FS="\t"

}

NR==2 {

    print "|-----|-----|"

}

{

    print "|", $1, "|", $2, "|"

}

The BEGIN block gets executed before the script reads its first line of input. In this case, it sets the field separator (the character or regular expression that breaks a line into fields) to the tab character.

The block beginning with NR==2 applies only to the second line of input (NR = “record number” or line number). In this case, it prints a Markdown separator (between table heading and body) before processing the second line… remember, awk takes each pattern/action pair in order. Since there is no next statement, it falls through to the default action.

The last block is the default action, since it has no pattern to trigger its use. It puts Markdown table call separators on each end of the line, and between the two fields. The commas insert the output field separator (a space, by default). I could get the same result with:

print "| " $1 " | " $2 " |"

So I copied the Markdown-formatted table from the terminal window and pasted it into a text editor. From there, adding a third column was easy. Not so easy, or at least somewhat more tedious, was searching the PDF for “initialization reason” and adding the conditions triggering each reason code to the table. In some cases, there are multiple issues for a particular reason. In two cases, there was nothing in the spec at all about the reason code. Fortunately, I was familiar with one of the causes and the other was straightforward.

The Markdown has been converted to DITA, and is now waiting for the project to get started in earnest. And it won’t be bugging me to deal with it over the next couple months.

Pizza Night Multilemma: solved!

I still remember an old Hägar the Horrible strip, where the family is gathered around the table. Supper is a pizza, presumably with everything, and everyone wants to take out a topping (anchovies, vegetables, what have you). Helga, the wife, thinks, “I hate ‘take-out’ food.”

I can relate. If we order pizza, we usually have to order two, both with one set of toppings on each side (and make something else for Charlie). I like everything (especially meat), wife prefers mostly veg, Mason’s a minimalist (he’s recently shifted from pepperoni to plain cheese), and Charlie can’t eat regular cheese unless we want Fukushima-style containment breaches.

But I have solved the Pizza Night Multilemma. The TL;DR: everyone gets their own custom pizza.

By doubling my go-to pizza crust recipe, I can divide it into fourths, then top each one with exactly what everyone likes. Everyone wins, even Charlie, as he does pretty well with the vegan version of mozzarella. I asked him what his favorite thing to eat is (knowing the answer), and he said, “bread!” When I asked him if he wanted to see how to make bread this afternoon, he was all for it. So we got to work. He was right up against the kitchen island, watching every move (as I explained it). I had to get him to step back a couple times, as he was encroaching on my workspace. When I got to the kneading phase, he wanted to give it a try himself, and I let him have a couple shots at it. He probably would have done better with a stool, as he didn't have good leverage to push the dough into the table, but he did get floured up for the occasion.

Flour-y language

The pizza crusts are highly irregular, even when tossed a little bit (I’m no expert), but “occasional flaws reflect the handmade nature of this product.” Charlie’s crust started out triangular, then became more trapezoidal as I spread it out. Mason’s was heart shaped. Wife and I both ended up with irregular shapes, but “irregular is normal in the Strange Lands.”

Had I thought it out better, I would have rearranged the oven racks to put the cooking pizza up top and the pre-bake crust on the next shelf, but doing things one at a time worked out. In a slightly inspired move on my part, I cut up some liverwurst and put it on Charlie’s pizza (Mason sampled a leftover piece and opined that cooking liverwurst improves the taste). In any case, everyone got what they wanted, and everyone was happy (and that’s nearly a miracle at FAR Manor).

Everyone got what they wanted

Clockwise, from top left:

• Plain cheese (Mason)
• Vegan cheese and liverwurst (Charlie)
• Mushrooms, onions, peppers, and pepperoni (me) (pepperoni is under the cheese)
• Mushrooms, onions, and peppers (wife)

I was tempted to make mine Hawaiian (ham and pineapple), but I don’t think we have any pineapple. In any case, everyone has leftovers for tomorrow or whenever. I’ll enjoy mine at lunch.

Cobbled together

Wow, has it really been four years since I discovered the peach tree next to the composter? Not like there was much more to say. The peaches were hard, and the critters stole the entire bunch every year as soon as they started getting ripe. We never did get around to moving it, either.

But, after the clearing out we did, it started getting more sun. I figured there wouldn’t be any this year; the tree started blossoming during a warm spell in January, and you can guess what happened a week later. But later on, as I went out to dump scraps in the composter, I saw it had about a dozen hard fruits on it.

As August rolled around, we moved Chief (the outdoor dog) next to the tree to keep critters away. I started checking every couple of days, felt them begin to soften, saw them start to turn. One fell off, and I took it inside to ripen up in the kitchen window.

A couple weeks ago, the composter run showed me a batch of ripe and nearly ripe peaches! I pulled up the front hem of my T-shirt for an impromptu basket, and harvested the lot before the critters could.

Wife stuck them in the fridge, with assurances that she would make them into something. She was leaning toward peach ice cream, using goat milk so Charlie could have some, but goat milk prices are getting to the point where it might be worth having our own goats. Then Mason got the ro, then the wife did. I considered freezing them (i.e. the peaches), so they would be at least usable for something when we got to them.

Last weekend, she got them out and got going on some peach cobbler. It wasn't huge, because we only had about 10 to work with, but there was enough to go around.

Tastes as good as it looks!

The tree itself is still rather spindly, so I’m still thinking about transplanting it (assuming we get a winter that’s more than Long November again). And I should have grabbed some vanilla ice cream to go with the last of the cobbler.… but it’s pretty darn good on its own.

So even FAR Manor is capable of pleasant surprises. Too bad they’re so rare.

Adventures of a #techcomm Geek: Go API chapter 2, “No ReST for the weary” (edit#2)

Image source: openclipart.org

Last time I had to deal with an API, it was pulling a vendor’s documentation into our own system. Now, I have to document our own APIs.

OpenAPI, formerly known as Swagger, is quite popular in the ReST API universe these days. And why not? One source builds a website, the hooks, documentation, and everything. At least online. If you want to provide a PDF document describing the API, though, there’s a little more to it.

• First, all those definition and summary strings need some attention. Where developers involve the technical writers in the process makes a huge difference in effort (at least on the writer side).
• Second, there’s more to documenting an API call than the definition and summary strings. There are path variables, query variables, examples, and the list goes on.

Fortunately, there are several utilities that extract documentation from an OpenAPI file. For my purposes, Widdershins works best—it produces a complete Markdown file—although it’s nowhere near ideal.

• One issue was definitely not the fault of the tool. The developers told me of a dozen categories (or tags in OpenAPI parlance) that didn’t need to be documented for customers. Widdershins groups all API calls with the same tag under the same section, and that helps a lot.
• The second issue could be either Widdershins or my personal preference. I didn’t like the order that Widdershins presented data for each method. There were some other minor issues as well.

I had a big wad of text that was my nail, and awk once again is my hammer. I started pounding. I did consider using a YAML parser for a brief time, but realized Widdershins did a lot of busy work for me. It actually does a pretty good job of building a Markdown document, describing all the method calls and schemas. If only there was a way to fix the presentation order, it would be perfect.

My first goal was to reshuffle the internal sections of each method to get them in the order I wanted. Deleting the unneeded groups, I reasoned, was a one-time thing that I could deal with myself.

My script worked the first time, but scrambled a bunch of things on the second attempt. Worse, doing the search-and-delete on those unneeded sections took more time and care than I’d anticipated. I needed a re-think.

Fortunately, a Computerphile interview with Brian Kernighan (the “K” in awk) came around, right when I needed it. It gave me… if not the key to my problem, a map to the key. In a nutshell, Dr. Kernighan advocates against large, monolithic awk scripts. His 1986 paper Tools for Printing Indexes describes his approach as:

…a long pipeline of short awk scripts. This structure makes the programs easy to adapt or augment to meet the special requirements that arise in many indexes.  

This approach can also be easier to debug, as you can replace the pipeline with temporary files and verify that the output of one stage is correct before feeding it to the next stage. Each stage refines the input further.

So I split the monolithic script into two medium-size scripts:

• Stage 1a (weed) fixes headings, weeds out unneeded HTML markup (mostly <a name="x"/> tags), and gets rid of those unneeded sections. Having less cleanup already makes this approach worth the effort.
• Stage 1b (shuffle) re-orders the remaining method descriptions. I learned that the input order is important for making this work; so if future versions of Widdershins move things around, it could break the script and I would need to fix it again.

It takes maybe a second to process the raw Markdown through both stages under Cygwin, which is noticeably slower than a shell under a native POSIX system. I expect my 8 year old iMac would be nearly instantaneous.

Now that I’ve cracked the code, so to speak, more stages are coming.

• Stage 2 throws out the schema definitions that none of the remaining methods refer to. A pair of scripts identify which schemas needed to be kept, then weeds out the others.
• Stage 3 fixes cross-references (mostly to schemas). The monolithic Markdown file uses a URL of the form #schemaxyz. Since the ultimate goal is to split the single Markdown file into topics, those URLs need to point to the eventual file name instead. A trio of scripts create file names that correspond to the URLs, replace the original #xyz name with the file name, then shuffle the schema’s description to the top of the topic.

These stages take another second to process… so 13,000 lines of YAML to monolithic Markdown file is about two seconds. The mdsplit script, that splits the methods and schemas into topics and builds a Lightweight DITA (LwDITA) bookmap, takes less than ten seconds to complete. So I’m now at the point where it’s easier to regenerate the entire document if I run into a scripting issue, instead of pushing through the problem. Uplifting the LwDITA to full DITA takes maybe a minute. After the uplift, another script fixes the extensions, changing .md to .dita, and fixing the cross-references.

At this point, I can focus on adding value: adding metadata, grouping related schema definitions, and the like. If I need to regenerate this thing again, I need only run the shell scripts that conduct the Geek Chorus.

Going forward, I’ll need to be able to compare versions, so I can replace topics with actual content changes, or add new topics. At that point, I could hand things off and intervene only when the input changes enough to make a difference. Or, we might decide to ditch the PDF entirely, and that would make things far easier on everyone.

Techcomm geeks never worry about automating themselves out of a job, by the way. There’s always a new presentation format, or new source document formats, or many new ways to streamline workflows. Handing off a system is a triumph; it means we have more time to focus on the next thing.

Edited 5 Sep: I didn’t realize I’d pasted this out of Logseq before going through it and fixing some things. Now we’re up to date.

Edited 7 Sep: All the tweaks have been made, and I now have a turnkey system.

Leverage

Every few years at FAR Manor, one of the A/C units begins a horribly loud rumbling. The first time this happened, the wife called an HVAC dude to see what was W0RnG!one… turned out a mouse had hopped into the squirrel cage and got centrifuged to death.

The same thing happened again, not two weeks ago. An adult mouse weighs maybe 2/3 ounce on average, and that tiny bit of weight in the A/C motor can shake the whole freeking manor! Talk about leverage…

We've run out of money, and the wife continued to complain about the noise, so I got Mason to come upstairs with me on Saturday afternoon as the gofer. I had hoped the A/C fan was horizontal, and would let me easily remove any obstruction or imbalance… but no. It's vertical. I had Mason fetch me a mirror, but realized I could use my phone (with flash on) to see what and where I needed to grope with my gloved hand.

Rubber gloves highly recommended

After a couple attempts, I removed the imbalance and dropped it into a garbage bag before putting everything back together. And lo and behold, no more shaking or rumbling.

Ew. Major ew. But dealing with the (increasingly infrequent, thank God) Charlie accidents is little better. I hope Mason is learning how to fix things on his own, too. He has grandiose ideas of how he and his friends are going to live in style, but any money you save on a service call is available for fun stuff.

EDIT: And you can dang well bet, I treated myself to a bowl of Extreme Moose Tracks after that. I deserved it.

New granddaughter!

 Check out G3, for lack of a better blog-name right now…

I haven’t seen her awake just yet.

Man, it's so hard to remember how tiny they are when they’re newborns. After hoisting Charlie all the time, she’s like a feather. But that won’t last long.

AJ is (so far) very much the Big Sister, and even a little territorial. Charlie thinks she’s fascinating, and gets excited when “the baby is coming to our house.”

By the by, my skin isn’t blotchy. There was sunlight coming in through the window to my right, and between it and the overheads the shadows got funky.