First Crack Release Notes, July 2019

I have done a bit of work on First Crack since last month’s update. It’s time I shared it with you.

July Activity #

First, the things I did in July.

Guided Setup #

When I re-released First Crack in June, it forced the user to fill out a settings file before building their website. This felt clunky and raised the barrier to entry for new users, so I added a guided setup in July. Now, rather than making the user fill out a config file, First Crack guides them through the process by asking questions for each field. With this update, it even finds the Python 2 or 3 binary on their system, and modifies the engine to run on either version — all behind the scenes. This adds a little more polish to the engine.

makefile Integration #

As I thought about ways to lower First Crack’s barrier to entry, I identified two easy areas for improvement: editing the path to the Python executable, and knowing how to run the engine. On my machine, Python 3 lives in /usr/local/bin/. Most machines have the binary in /usr/bin/, though, and so new users must first locate their binary and then edit six files to reflect that path. I did not like this, but given the complexity of the task at hand, it did not seem unrealistic. I also told new users to run blog.py, which assumes they know to use either ./blog.py or python blog.py. This also seemed reasonable, but why not make both easier?

I started with a shell script. This could have solved my first problem, by detecting the version of Python on the host machine and then modifying the scripts as needed. It would not have solved the second, though, and I knew I could do better. I settled on a makefile. This allowed me to abstract the back-end by reducing ./blog.py to build the site to make. This simple command takes care of finding the Python binary, editing the scripts, handling file permissions, and walking the user through the setup process. I used the makefile to abstract other things, too, like previewing (make preview) and deploying (make deploy) the website. I think this turned out great.

Python 2 Integration #

Moving First Crack to Python 3 took all of a few minutes last month, so this month I decided to re-add support for the millions of devices running Python 2. During the first run, First Crack mow finds Python on the user’s system and modifies itself to work in either Python 2 or 3, based on what it finds.

Improved Documentation #

As part of these changes, I also spent some time on the README. As I said last time, I will always have more work to do in this area, and in July, I spent some more time there.

Augusta Plan #

Going forward, I plan to focus my efforts on these areas in Augusta, 2019. I carried some of these over from last month’s update.

Re-Implement "Pretty Print" #

I would still like to re-implement the “pretty print” feature now that First Crack uses a stateful Markdown parser. I did not get to this in July, so I pushed it to August.

Release Markdown Parser #

I would still like to release the Markdown parser as its own project. I still have some bugs to work out, though, and I would like to add the ability to parse multi-line strings and entire files at once. Perhaps in August.

Publish Implementation of Markdown Spec #

I still want to outline the peculiarities of my implementation of the Markdown spec in a formal document. That has yet to happen.

Improve Documentation #

I did some work on the documenation this month, but as always, I could do more. Again, a few of the ways I think I can improve the README in particular:

I got a few things done in July. Again, though, I have a lot of work ahead of me. I look forward to it, as always.

Permalink.