sblg: path/to/file.xml:7:0: no element found *** Error 1 in
(Makefile:111 'path/to/file.html')

well that’s not the most helpful error. The way the blog is setup, I write files in markdown, they get converted to XML and then to HTML, so looking at the generated XML file it only had the headers in it which are generated from a template so clearly something in my post was breaking it. I took an old post and tried to generate the XML, same error; so something had changed when I upgraded last week, a quick look at the mail the upgrade generated confirmed that sblg stayed at the same version, which means that one of the dependencies changed, question was which one and what. It was fairly late and I was tired so I should have thought of this earlier but when I run the command to generate posts it produces a lot of output and this scrolls by fast. So scrolling up to the very beginning I found the issue:

lowdown: unknown option -- E

The lowdown(1) manpage confirms there is no E flag, but what did the E flag do? Now the intrepid reader will remember my post where I mentioned I had found all the required scaffolding for this on another site, well I had only ever modified the pieces which didn’t work for me, not actually figured out all the intricacies, in my Makefile I had:

lowdown -E html-escape $< ;

the manpage had a few flag dealing with HTML, but none that matched that exactly. I headed to the version history and found that the current version removed the deprecated E option which a long time ago had been replaced by long options. Scrolling further down I found that in version 0.5.2 long options where introduced. So I downloaded the version before that, 0.5.0, so I could extract the included manpage and find out what the old E option with html-escape did before it was deprecated.

     -E feature
             Enable the given feature (see Output features).  See -D.
             You can specify this multiple times for different
             features.

and

     html-escape
             Leaves in-line HTML in its source form as if it were
             opaque text.

Making progress, now back to the current manpage to look at what this could mean. There were two long options which talked about html escapes:

     --html-no-escapehtml
             If --html-no-skiphtml has been specified, this causes
             embedded HTML not to be escaped, and is instead output
             verbatim.  This has no effect if --html-no-skiphtml has
             not been specified.

and

     --html-no-skiphtml
             Output embedded HTML.  By default, embedded HTML is not
             output at all.  See --html-no-escapehtml.

Now the wording differs but it seemed clear that the second option was the one I wanted. So I modified my Makefile and I could again generate blog posts. Success!

But reading the first option got me thinking, once again referring back to my initial sblg post, one of my issues was that when I make posts with embedded links when I put them in the markdown file, lowdown will mangle it, so I’d have to manually edit the XML file afterwards and then recreate the HTML file. This was always annoying but relatively quick to fix, but I started wondering if the first option might actually fix this. Turns out that it does, so modifying my Makefile to use that flag too I have saved myself that extra manual step. Just goes to show that reading the manual can actually reap some rewards.