Subject:	I broke my blog...
From:		.jh
Date:		2021-06-24T17:04:00Z
Tags:		about blog tech openbsd sblg 2021

While writing today's ThrowbackThursday post I discovered that the
latest upgrade had broken my blog, while it displayed perfectly fine
if I tried to write a new post it would blow up with this error:

---

```
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)](https://kristaps.bsd.lv/lowdown/lowdown.1.html)
manpage confirms there is no E flag, but what did the E flag do? Now
the intrepid reader will remember my
[post](http://johan.huldtgren.com/posts/2017/about-2017) 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](https://kristaps.bsd.lv/lowdown/archive.html) 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](http://johan.huldtgren.com/posts/2017/about-2017), 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.