Drezn

Command listings in documentation

I write a fair amount of documentation for systems administration and other tech stuff and have for years now—I suppose my entire professional life (go me!). I’m very interested in tools that don’t get in my way when I’ve got a flow going, and I find a text editor with basic markup or formatting codes is the way to go. In the last semi-long while—probably five years?—I’ve pretty much settled on Markdown or whatever variants the tool I’m using implements.

This is a bit of a ramble. Bear with me.

Background: Mute and other past software projects

Before I’d come across Markdown and fell into using tools that use the format, I’d developed my own, similar syntax and called it Mute: MarkUp for Text Editing. I wrote at least two interpreters: one in Ruby, and one in C++, which I later exported as a PHP library when I rewrote a basic CMS in PHP for some reason. Egads the folly of my youth. This was basically a wiki which, now that I think about it, was pretty cool and very easy to use, and in my mind at least captured the best elements of TWiki, which is what we used in a previous job for all the documentation.

Mute was used in this wiki project, the previous CMS written in Ruby, and also incorporated into a notes app I used for a while, written in C++ with WxWidgets. This was a desktop notes app that would format notes with HTML if it detected or was told the note was written with Mute syntax. Kinda neat, I used it a lot, and I never considered it polished enough to put out there.

Eventually these were abandoned and it was pretty painless: Markdown and Mute, though developed independently, are very similar and arrived at almost the same place. There are some things I like about Mute that aren’t available in Markdown but on the whole I’ve found Markdown adequate for nearly all my documentation.

The problem of documenting CLI procedures with Markdown

One thing that I’ve wished I could do better, though, is command-line procedures, and tonight is the first time I’ve given any thought at all to reviving Mute.

Command listings are often presented as a code listing. This is okay. It’s fine. It’s not great. When describing a list of commands for the reader to issue on a system, I often find competing goals to presentation:

  1. I want the commands to be selectable so the reader doesn’t have to retype it.

  2. I want to demonstrate the context of the commands: the results, and sure, the prompt isn’t just decoration.

With normal code listings meeting both needs isn’t possible, and I often think about which is the more important. And usually I’ll prioritize the second, and it’s not a huge deal for the reader to select each line individually, and it’s still a win.

It occurred to me this evening as I sat down to do something completely unrelated to this and also a thing which now I haven’t done anything with at all that command listings could be presented nicely with some pretty simple HTML and CSS.

(Note: I am not much of an HTML/CSS person; I know enough to get around but I don’t suffer the various browser compatibilities. I get by with a lot of hack-and-slash, web searching, and lately, the Mozilla Developer Network.)

HTML/CSS for describing command-line procedures

I can’t remember what inspired it but I thought if each command was an item in an unordered list, and the list bullet was a command prompt, and the indentation of the list elements was not hanging outside the rest of the paragraph, then the HTML is basically hacked to separate the various syntactic elements—command prompt and command, and by using blocks inside the list element, the results—which I could then present as desired, probably.

This worked really well, pretty much right off the bat. Now I’ve spent way more time writing this article about it, and thinking about what I do with this, than I spent working it out. Here’s an HTML document that implements it:

<html>
<head>
  <title>Code listing tryout</title>
  <style>

ul.codelisting {
  list-style-type: '$ ';        /* command prompt */
  list-style-position: inside;  /* flush with other text */
  font-family: monospace;
  font-weight: bold;            /* commands are bold */
}

ul.codelisting ::marker {
  font-weight: normal;          /* prompt is NOT bold */
}

ul.codelisting p {
  user-select: none;            /* selecting only gets commands! */
  margin: inherit;              /* not extra space around results */
  font-weight: normal;          /* results are not bolded */
}

  </style>
</head>

<body>
<h1>Code listing test</h1>

<ul class='codelisting'>
  <li>sudo go do something
  <p>Okay, I did the thing, says computer</p>
  <li>sudo go do something else
</ul>

</body>
</html>

This checks all my boxes for a usable command listing:

  • Commands and context are visibly distinct, because the command is visually emphasized.
  • The commands are selectable and (if the browser supports it) nothing else will be selected—neither the documented results nor the prompt.
  • The reader gets the context but can select all the commands in one go.

So now what

I have no idea. I had fun thinking about it and I’d like to put it to use—I like good documentation and command listings have always been a minor but persistent annoyance.

The first thing would be to actually see if somebody has implemented this already in some of the common Markdown/Commonmark implementations. The two I use most often are Hugo (this blog and others) and GitLab. Some highlighting enhancements for code listings in such may support some of the formatting although when I’ve looked I’ve been disappointed, but I last looked over a year ago.

Assuming there’s nothing like this implemented, maybe for my own fun I could revive Mute. I also kind of miss that notes app. Like the other stuff I’ve written over the years, it worked for me, because I wrote it just for me. But Mute could maybe be integrated with Hugo.

If I ever start writing again, Mute would be a bit better for me than Markdown, due to some of its more “advanced” (not really) features. Aw, now I’m just trying to convince myself it’s a good idea to take up a new/old project, I have to recognize that.

Here’s how I’d do it though!

$ this is a command
this is the context around it
$ this is the next command
$ and the third
Etc.

That’s pretty easy to implement because I can’t think of any context where you’d start a paragraph with “$ “. Windows or CSH or uh whatever users could present with a different prompt in the CSS but this’d be the Mute syntax.

Anyway. What a weird thing to get mildly excited about.

Comments

JavaScript must be enabled for comments.

Care to comment?