Looking for writing-related posts? Check out my new writing blog, www.larrykollar.com!

Thursday, September 08, 2022 No comments

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.

Monday, September 05, 2022 No comments

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.

Sunday, August 28, 2022 No comments


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.

Thursday, August 04, 2022 1 comment

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.

Saturday, July 16, 2022 No comments

Pain in the Drain

Ah, Friday. The day you come downstairs after wrapping up reports and shutting down the work laptop for the weekend. Two days of rest, relaxation…

And then you see the contents of the kitchen cabinets, usually under the sink, sitting in a big box on the floor. “The dishwasher is leaking,” the wife said.

That didn’t really make sense to me. There’s a cabinet wall between the cabinet and the dishwasher. If it was the dishwasher leaking, wouldn’t it be coming out in front of the dishwasher? But if the cabinet was wet, it was either the drain line leaking, or the water intake line.

So I got my electric lantern to light up the whole intersection of Under and Sink. Wife started the dishwasher, which happened to be on the drain cycle… and water started shooting out the hole where the drain line went through!

“So what is it?” she asked.

“Most likely, the drain line itself has a hole in it,” I ventured. “But if the drain is at the top of the dishwasher, it could be loose there and shooting water across the drain line.” Which didn’t really sound plausible to me, but it’s unusual for a problem at FAR Manor to actually be the first idea I have.

But unusual doesn’t mean never.

When a drain line looks like this,
it’s time to replace it.

So this morning, I dug up the info about the dishwasher, in case it mattered, then disconnected the intake and drain lines under the sink so we could pull the dishwasher out. As with most things at FAR Manor, it fought until we found the little tabs just behind the tile, holding it in. Pushing down with a screwdriver let them clear the tile and we dragged the body of the dishwasher into the sun LED light of the kitchen. The drain line went all the way down and under the dishwasher. Wife suggested I look under the front, and I found the line coming out a front-facing outlet and curling back. (She was hitting on all cylinders with the ideas this afternoon.)

With drain line and model number in hand, I rolled to Home Despot. Charlie insisted on coming along, and took several micro-naps on the way there and back. Turns out dishwasher drain lines are universal, so I got one and a can of wasp&hornet bomb (more on that shortly). We needed groceries, but Charlie was ready to go home and looked it.

I had some trouble reaching the under-sink drain connection, because the original drain line had an elbow that shortened the turnaround. I had just enough. If I have to pull the dishwasher out again for any reason, I’ll grab a hole saw and put a lower hole in for the drain line—that should give a good foot of slack. The wife wondered if we could put something around the drain line to prevent future wear-through, so we took the piece of rubber we had to cut off the dishwasher end (the universal line has step-down sizes, you cut to the size you need) and slipped it over the other end and pushed it into the hole. Maybe that will keep it happy.

A crude attempt at not having to do this again

So we ran an empty load… and water started coming out from under the dishwasher. Looking underneath, I could see it was shooting out the drain connection at the dishwasher. I replaced the clip-type hose clamp with a worm gear-type, and that (and a few towels) took care of the problem.

Groceries have been got, and the kitchen floor is still dry, so it appears we have saved ourselves a crap-ton of money on a plumber. Getting on and off the floor is a pain at my age, but at least I can do it.

Now that it was dark, it was time to save a crap-ton of money on an exterminator (they quoted us $225 for this job).  Hornets built a large nest above a gable window, and I had to get up on a ladder for even a nominal “27' jet spray” to reach it. I hope it worked, but even with a flashlight trained on the target, I’m not sure the spray reached it. I guess we’ll find out tomorrow. If not, I’ll get the extension ladder and get a lot closer than I’d really like. I hope it doesn’t come to that.

Friday, July 01, 2022 No comments

Our newest resident

Pop, our orange cat, disappeared a few weeks ago. Missing and presumed… you know the drill. :-( KT, the shy and retiring cat, has been slightly friendlier since.

The wife is a dog person, but one of her friends was trying to unload some kittens. So…

Hiya, I’m Miya.

Charlie, who loves pretty much anything that moves, was totally captivated. The wife suggested that I let him name her… so we were hanging out on the porch (where the kitten lives), and I asked him, “What do you want to call her?”

Charlie thought it over for a long moment, then said, “Miya.” (MEE-ya)

“OK… is that M-I-A, or M-I-Y-A?”

A briefer pause. “Y-A.”

Well, it’s slightly more creative than the name I gave a cat at that age: Ia (EYE-a). And I think I did better than Other Brother, who named his cat Yo-Yo. But I digress.

Miya is already nearly twice the size of this picture. She’s thriving, and I hope she’ll do well as a porch cat. She has already figured out how to get up on the table.

Rosie, aka Doofus, aka Stupidog, is (as one might expect) confused. She goes over to the doors to the porch, and looks for Miya. Meanwhile, the kitten is up on a chair near the door, watching the dog, and hops down right in front of her. This usually sets off a startled bark and growl, as Rosie scuttles back from the door. She followed Mason upstairs yesterday, trying to stay relevant. I brought her ball up, and she was happy to fetch it for a bit.

I did bring Miya (and her gear) upstairs earlier this week. I probably won’t try that again, for a while. There was more than enough cat litter to vacuum up once I knocked off work and took everything and everyone back downstairs. Then again, Charlie stayed close and didn’t try to slip downstairs to annoy Mason or get into stuff he shouldn’t… maybe I can put Miya’s litter box in the bathroom? That would help to keep Charlie from playing in it while I’m on a call. Scooping would be simple, with the toilet right there.

Miya has a nice, loud purr, and lets it loose when someone (even Charlie) is holding her. Going out to the porch is just as important (in Charlie’s mind) as going outside, now. Well, I can think of much worse things than hanging out with a kitten and a child. (Much worse, being the illegitimate supreme court.)

Do you have some new critters? Sound off in the comments!

Tuesday, June 21, 2022 1 comment

Wrong Solstice for a bonfire

With the stingy rainfall, and temps well past 90°F lately[1], maybe creeping into triple digits south of Sector 706, you would think it’s summer.

Well, as of today, it is. Top of the year to y’all!

I guess between Memorial Day and Independence Day in the US, we kind of leave the solstice unmarked. On Termag, they call it High Summer, and it’s a week-long holiday. Sorcerers who can and desire travel to Queensport to the annual Gathering of the Conclave for two weeks of business, learning, hanging with old acquaintances (not to mention the occasional Conclave Romance), and cramming their apprentices’ heads full of knowledge.

But I digress. The wife calls this “hay baling season,” and is living the highest honor a farmer has (out standing in her field). Machinery makes this a much less labor-intensive undertaking than in the past, but all that machinery is complex and still needs eyes and hands on it[2]. Modern hay balers in particular are a lot more complex than you might expect (the manual is nearly an inch thick, and not large type). And, you need a tractor to pull it. And a cutter. And a rake (a/k/a “fluffer,” since it fluffs the hay into neat rows so the baler can pick it up). And maybe a truck and trailer to haul the hay to its resting place. And another tractor with a hay fork, to pick up the bales[3] and put them in the barn until they’re needed come winter.

So… to this afternoon. The wife was out standing in her field, when she saw smoke from the direction of another farm, about a mile away. “Not too smart,” she remarked, “it’s too hot and dry to be burning brush.”

This evening, she got a call from one of her helpers. “They were baling at _____’s,” he said, “and their baler caught fire. It torched the tractor, and half the field, too.” Yipe!

The wife points out that hay is exothermic (or “goes through a heat,” as she puts it) as it drys. It’s the main reason she repeatedly tells her helpers to not leave a partial roll in the baler. Her speculation: the people at the other place left a partial roll in the baler overnight, letting it get nice and hot, then that + the heat of the day + friction + the new hay being scooped into the baler = spontaneous combustion, and things got a bit hotter than anyone wanted. Or it could have been a baler malfunction, who knows? I doubt anyone will do a post-mortem to find out.

So think about the farmers, this time of year. Some have lost cattle, others are dealing with fires, and the rest are dealing with all the crap (literal and metaphorical) they have to encounter. Every day is Monday on a farm… and it’s nowhere near August yet.

Since that DALL-E mini thing is all the rage right now, I’ll leave you with its impressions of “hay baler on fire.” [4]

[1] I think Sector 706 is getting the good end of climate change, so far. Despite the current hot weather, we’ve been not nearly as hot as many surrounding regions… not to mention out west.

[2] So the wife has about three helpers. I joke about her hanging out with sweaty men, but she’s sweating just as much.

[3] Round bales are nearly 6 feet (about 1.5m) diameter, and about 4 feet (1.2m) wide. The only way you’re going to move those by hand is if you can roll them downhill.

[4] The top-center image has a vague resemblance to our baler.


Related Posts Plugin for WordPress, Blogger...