By the time I finished up the code to wrap various parts in HTML tags, I was already aware that it wouldn’t just work. A help output looks like this:
Usage: snail asset push [options] <src>
upload an assset
-p, --project <domain> specify which project (taken from remote if not set)
-n, --name <name> destination filename (taken from src if not set)
-t, --type <type> asset MIME type (default: "application/octet-stream")
-a, --max-age <age_seconds> max-age for Cache-Control (default: 31536000)
-h, --help display help for command
Does not maintain .glitch-assets.
It has plenty of those
> signs, which I would have to escape for HTML. I slipped in a function to do that too. And I was ready to behold version 2.0 of my generated help files (I forgot to mention, version 1 had been more or less a copy and paste of the terminal output into a
<pre> tag, which lacked links for the subcommands). This newly HTML-ed up version looked like this:
(Not really, I hadn’t put in the stylesheets and stuff. This is a dramatization where I intentionally broke some things from the latest version. Anyway.) It was a mess, visually. What the heck?
Of course, there was a good reason why it looked that way. The page looked that way because the source code looked like this:
The HTML code was beautiful. Everything lined up, just as the authors of the help system intended. There was a tidy column for the “terms,” which looked like
<span class="subcommand-term"><a href="rsync.html">rsync <args...></a></span>, and a tidy column for the “descriptions,” which looked like
<span class="subcommand-description">launch rsync with snail pipe as the transport</span>.
That is, the help system did its best to line things up, but those very things were full of tags and character entities that mess with everything’s width once it was viewed as a webpage. And different things would have different lengths due to the non-constant link URL and the varying number of escaped
That day (so to speak, I worked on this across multiple days), I really had to think about objective number 2.
- Try not to have to rewrite the code that generates the terminal help output.