I blogged last year about my switch from Markdown to AsciiDoc, and that I was using AsciiDocFX.
I still like AsciiDoc, but AsciiDocFX has been getting on my nerves:
Still, I used it.
But, I built a new computer this week. And I've been setting up my softwares on it. I thought it might be worthwhile to see if there's an AsciiDoc plugin for Visual Studio Code. And, of course there was, because apparently the Code extension ecosystem is booming!
So, I installed AsciiDoc by Joao Pinto, since it came with a live preview. But, it requires me to actually install the asciidoc command line tool.
So, I thought, that should be easy enough. I went to the AsciiDoc site and started following the directions for Windows installation.
Okay, well now I need to install Ruby. Should be easy enough. I already have Chocolatey NuGet, so I'll just run
choco install ruby. No problem. I know that ruby comes with gem, so I should be all set.
According to AsciiDoc... docs... I just use
gem install asciidoctor and that should do the trick.
But, no. It's not that easy. Otherwise I wouldn't be writing this blog. I got an error message:
SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed
I'm sure all you Ruby people or Mac people or whatever already know where this is going, but I had no clue. So I googled it. I found a whole bunch of suggestions on StackOverflow. Some solutions made sense but weren't for Windows, and vice versa. I eventually hit upon some random guy's Gist and SSL upgrades on rubygems.org which lead to me this page on rubygems.org about SSL updates.
Fixing RubyGems Certificate Thingy
So, following that literally:
gem install --local C:\rubygems-update-2.6.7.gem
update_rubygems --no-ri --no-rdoc
gem uninstall rubygems-update -x
So, I guess that fixed... something? It's described in the gist I linked above. But I don't really understand why it's still a problem for a brand new install of ruby. Not complaining! It worked!
Okay, now Install AsciiDoc
gem install asciidoctor works. And now I get a live preview of AsciiDoc in Visual Studio Code.
I'll report back after some more time blogging to see if I like this, or if I eventually go back to AsciiDocFx.
UPDATE: As of early April 2017, I've been blogging this way and I'm extremely happy with it. Visual Studio Code keeps getting better, the preview plugin keeps getting better. I've had to introduce a few tweaks in my process, but I've got the whole pipeline semi-automated. It's easy to bring in code samples (thanks to AsciiDoc), easy to post to both the Couchbase blog and this blog, easy to run Yoast on it, and so on. Some day I'll write a blog post explaining the whole process (and hopefully get some good suggestions for streamlining!)
Welcome to another "Weekly Concerns". This is a post-a-week series of interesting links, relevant to programming and programmers. You can check out previous Weekly Concerns posts in the archive.
If you have an interesting link that you'd like to see in Weekly Concerns, leave a comment or contact me.
Having been almost a month gone from Zimbra (aka Telligent), I'm starting to remember and notice some things that I've previously taken for granted.
One of the axioms that was drilled into me in my early days at Telligent was "no ticket, no work". Which is to say, if it's not work that's been defined and entered into the backlog and approved for work and ready to be tracked, then don't do it. There are several benefits to this approach. One is that it tends to address gold-plating and adhoc features (since I have to take the time to think about something and communicate it to the team).
But one of the things about this approach that I definitely took for granted was how this helps with tracking. For every commit I did to source control, I had to put the ticket number in the commit message. The tracking system we were using just happened to have the ability to integrate with source control, which was nice. But even if it didn't, as long as I know the ticket number, I could very easily search the commit logs and see what code changes were made for the ticket in question. This made code reviews, retrospectives, conflicts, documentation, bug fixes, etc so much easier.
It doesn't cost you but a few seconds to put the ticket number in your commit message, and a few more seconds to put in a decent commit description while you're at it.
Matthew D. Groves lives in Central Ohio. He works remotely, loves to code, and is a Microsoft MVP.