Doug's Place

A Simple Unit Test Framework

Sun, 29 Mar 2026 05:26:46 -0400

Over the past few years, I created Basic Unit Test (BUT), the simplest possible unit-test framework for C code that I could think of. I had one important criterion for it, and that was the code for the test driver had to be separate from the code for the test suites. I didn’t want to tie each test suite to a specific driver. I wanted the flexibility to write different drivers, possibly with different features, to be able to load and run the test suites.

Overview

Any unit-test framework needs to define its test suites, test cases, and a way to detect, collect, and report errors. Let’s start with how test cases are defined and then see how they are collected into a test suite.

Test Cases

A test case needs a test function and optionally a setup and cleanup function. I found it convenient to define them with a macro and a typedef:

#define BUT_TEST_FN(NAME) void NAME(struct BUTTestCase *btc)
typedef BUT_TEST_FN(but_test_fn);

#define BUT_SETUP_FN(NAME) void NAME(struct BUTTestCase *btc)
typedef BUT_SETUP_FN(but_setup_fn);

#define BUT_CLEANUP_FN(NAME) void NAME(struct BUTTestCase *btc)
typedef BUT_CLEANUP_FN(but_cleanup_fn);

On the surface, it looks a bit silly to have three separate macros for these function signatures, because they are all identical. For small test suites, it doesn’t matter much, but for a large enough test suite the names signal intent. I never wrote a “large enough” test suite with BUT, so I just used BUT_TEST_FN. Here’s one that ignores the test case and throws an exception:

BUT_TEST_FN(test_failure) {
    BUT_UNUSED(btc);
    BUT_THROW(but_expected_failure);
}

The test case itself has a name and a pointer for each of these functions.

struct BUTTestCase {
    char           *name;
    but_setup_fn   *setup;
    but_test_fn    *test;
    but_cleanup_fn *cleanup;
};
typedef struct BUTTestCase BUTTestCase;

The name and test function cannot be NULL, but if the test doesn’t need any setup or cleanup, then those fields can be NULL.

I made a few macros to make it easier to define test cases. Here the author of the test case can simply give the test case a name and the three pointers to functions:

#define BUT_CASE(NAME, TEST, SETUP, CLEANUP) \
    static BUTTestCase TEST##_case = {       \
        .name    = NAME,                     \
        .setup   = SETUP,                    \
        .test    = TEST,                     \
        .cleanup = CLEANUP,                  \
    }

For example:

BUT_CASE("Expected Test Failure", test_failure, NULL, NULL);

defines a test case called “Expected Test Failure” where the test just throws an exception. No setup or cleanup functions are needed. There is a BUT_CASE_NAME variant that comes in handy, because it separates the name of the test case from the name of the test function. For example:

BUT_CASE_NAME("Expected Test Setup Failure", setup_failure, NULL, test_failure, NULL);
BUT_CASE_NAME("Expected Test Cleanup Failure", cleanup_failure, NULL, NULL,
              test_failure);

I also provide macros that define a test case and allow you to define the test function in place, both with and without setup and cleanup functions.

#define BUT_TEST(NAME, TEST)                              \
    static void TEST(void);                               \
    static void TEST##_wrapper(struct BUTTestCase *btc) { \
        BUT_UNUSED(btc);                                  \
        TEST();                                           \
    }                                                     \
    static BUTTestCase TEST##_case = {                    \
        .name    = NAME,                                  \
        .setup   = NULL,                                  \
        .test    = TEST##_wrapper,                        \
        .cleanup = NULL,                                  \
    };                                                    \
    static void TEST(void)

There are several variants that enable users to define their own struct with BUTTestCase as its first element and have fields for test-specific data.

Test Suites

A test suite needs only a name or ID and a set of test cases. Here’s its definition:

struct BUTTestSuite {
    char         *name;
    u32           count;
    BUTTestCase **test_cases;
};
typedef struct BUTTestSuite BUTTestSuite;

The driver will need to retrieve the test suite from a DLL, so I defined some macros to make it easy to define test suites:

// a macro to define a common field for test-case structs to embed a BUTTestCase.
#define BUT_EMBED_CASE BUTTestCase btc

// Auto-register test cases in a suite
#define BUT_SUITE_BEGIN(NAME)      static BUTTestCase *NAME##_cases[] = {
#define BUT_SUITE_ADD(TC)          &TC##_case,
#define BUT_SUITE_ADD_EMBEDDED(TC) &TC##_case.btc,
#define BUT_SUITE_END              }

and ensure the retrieval function is also defined:

#define BUT_GET_TEST_SUITE(NAME, SUITE)                                  \
    static BUTTestSuite SUITE##_ts                                       \
        = {.name       = NAME,                                           \
           .count      = sizeof SUITE##_cases / sizeof SUITE##_cases[0], \
           .test_cases = SUITE##_cases};                                 \
    DLL_SPEC_EXPORT BUTTestSuite *get_test_suite(void) {                 \
        return &SUITE##_ts;                                              \
    }

I also defined a function pointer that the driver uses to cast a void pointer to the right type, typedef BUTTestSuite *(*but_get_test_suite)();, though, I wish I had named it get_test_suite_fn to convey its type more and look less like the actual function.

The begin, add, and end macros are used in just that order:

BUT_SUITE_BEGIN(ts)
BUT_SUITE_ADD(simple_t1)
BUT_SUITE_ADD(simple_t2)
BUT_SUITE_ADD_EMBEDDED(deep1)
BUT_SUITE_END;

Tack on a BUT_GET_TEST_SUITE macro and you’re done:

BUT_GET_TEST_SUITE("My Tests", ts);

Exceptions and Assertions

Exceptions are key to detecting errors. They enable a quick escape, in an orderly fashion, from deep inside test code out to the driver. If some constraint isn’t held, test code throws an exception and the driver catches it, inspects it, and reports from where it was thrown and why it was thrown. The where and why helps in debugging the offending piece of code.

The exception component is inspired by and uses many of the methods from chapter 3 of David Hanson’s book, “C Interfaces and Implementations, Techniques for Creating Reusable Software”. It is implemented as a set of wrappers around setjmp/longjmp.

Reasons

Exceptions themselves are just static strings, so each one is unique, and if the strings are well chosen they describe themselves.

typedef char const *BUTExceptionReason;

Here are a few that BUT provides for general use:

BUTExceptionReason but_expected_failure   = "expected failure";
BUTExceptionReason but_unexpected_failure = "unexpected failure";
BUTExceptionReason but_invalid_value      = "invalid value";

State

To provide a well-structured exception handling mechanism, we define an environment that can be in one of three states:

Entered: a try block has been entered and setjmp has been called to initialize a jump buffer.
Throw: an exception has been thrown by a call to longjmp using the most recently defined jump buffer.
Handled: either a thrown exception has been caught, or a finally block has been entered w/o a thrown exception.

These three states are represented by this enum:

typedef enum BUTExceptionState {
    BUT_ENTERED,
    BUT_THROWN,
    BUT_HANDLED,
} BUTExceptionState;

Environment

Exceptions are managed as a stack of environments that contain a jump buffer, a link to the parent environment, a state field, and context captured from a thrown exception that gets passed into a handler so the issue can be recorded and reported for analysis.

One important detail is that its state field is declared volatile. This is one of the few times where volatile is essential, because compilers are allowed to stash values in registers. In light of setjmp/longjmp, the state must be restored after calling longjmp. However, there is a serious flaw in the implementation. The context information, reason, details, file, and line, are not also declared volatile. The code works when compiled with Visual Studio 2022, but will fail miserably if compiled with clang.

Throwing and Catching

Test code can just throw an exception using one of the throw macros. The simplest, BUT_THROW(reason) records the file and line number from which it was called. BUT_THROW_DETAILS allows for a printf-style format string and a sequence of values to be captured before throwing the exception.

To catch an exception, define a try catch block using BUT_TRY to open a new block, BUT_CATCH(some_exception) or BUT_CATCH_ALL to catch all exceptions, and BUT_END_TRY to close it. BUT_TRY initializes a new exception environment (BUTExceptionEnvironment) which includes calling setjmp on the environment’s jump buffer. setjmp returns zero, which maps to the BUT_ENTERED state. It also gets the current stack, and pushes the new environment on to the top of the stack.

Normal execution continues with the code in the try block, and if the catch block finds that the state is BUT_ENTERED it pops the stack, changes the state to BUT_HANDLED, and lets execution continue. Similarly, when execution gets to BUT_END_TRY, it checks the state and if it’s BUT_ENTERED (maybe there was no catch block), it pops the stack and sets the state to handled.

Calling BUT_THROW() throws an exception which pops the top environment off the stack, captures the details of the exception, and calls longjmp on the environment’s jump buffer to return execution to where setjmp was called. Now setjmp returns 1, which sets the state to BUT_THROWN and the catch block will compare its exception against the incoming one. If the exception is a match, the state is changed to handled, and execution continues normally. If it’s not a match, execution continues to the end of the try/catch block where the exception is rethrown so another try/catch block can attempt to handle it.

If no try/catch block can handle the exception, the stack becomes empty and the throw code calls the context’s currently defined handler. Usually that’s the test driver’s handler, which will catch the exception and record/report the error.

Context

I found it useful to wrap the environment in a context that combines a pointer to an exception handler with a stack of environments.

struct BUTExceptionContext {
    but_handler_fn          *handler; ///< exception handler
    BUTExceptionEnvironment *stack;   ///< top of a stack of exception environments
};

I defined a global default context, g_default_context_ and an active context pointer, g_context_ in exception.c that get built into both the driver code and each test suite. The global context is initialized to the default context the first time but_get_exception_context() is called.

The Exception Context Problem

The DLL model creates a subtle issue. Both the driver and each test DLL statically link the exception library, so they each get their own independent copy of the exception stack. An exception thrown from the DLL without any try/catch blocks wants to pop an environment from the DLL’s stack, which is empty. The throw hits the unhandled exception handler.

BUT solves this with context injection. The driver has its own instance of a BUTExceptionContext holding a handler function pointer and the exception stack pointer. After loading the DLL, the driver calls GetProcAddress to find the test suite’s but_set_exception_context function and calls it to pass a pointer to the driver’s own context. From that point on, exceptions thrown in the DLL find the driver’s exception frames.

One small wart in this implementation is that BUT_CATCH compares the address of the thrown exception to the one its argument points to. This won’t work if the driver ever needs to catch a specific exception thrown from a test suite. However, the BUT driver uses BUT_CATCH_ALL so pointer mismatch isn’t an issue.

There’s a related wrinkle with exception reasons. Reasons are constant strings. Matching them by pointer equality would compare a pointer in the DLL to the address of the same string in the driver, which are different objects at different addresses even though they hold the same text. BUT uses strcmp for exception matching. When the driver’s handler catches an exception it uses BUT_UNEXPECTED_EXCEPTION which is just strcmp(e, but_expected_failure). If the exception is not expected (strcmp returns a non-zero value), then it has caught something interesting and reports it.

Summary

At this point BUT was good enough. What I really wanted was a test framework that could inject faults into memory management functions to stress test C code. My intent was to continue using the same pattern of macros and typedefs to develop a fault-injection test framework. It worked for a while, but eventually turned out to be harder than I thought. I had to rework the entire exception-handling implementation into a service provided by the driver to test suites through a shared interface. That’s the story for the next post.

Writing a Unit Test Framework in C

Thu, 30 Jan 2025 20:40:29 -0500

The C programming language was one of the first programming languages I ever learned (after learning Basic, APL, and Fortran). I haven’t written much in C lately and I miss it, so I decided I needed a project to write C on a regular basis.

One of the problems with writing C code is making sure it does what you intend it to do. I’ve made lots of mistakes in the past, and I’d like to reduce their likelihood a little. One way to do that is to test code thoroughly, so a unit-test framework would be useful.

There are already lots of test frameworks out there, like Check, CUnit, and CuTest. Some of them look great, but I think that the experience of writing my own will be a gentle way to get back into a regular habit of writing C.

I should note that I don’t have Linux. I use Windows, and so I need code that compiles and runs there. That said, Check looks great, but the tutorial jumps to using Autotools. I just can’t relate to that with my Windows development environment.

CUnit organizes tests into test suites and test suites into a registry. It looks like developers have to bring their own test driver and compile/link in their registry to the driver. That doesn’t quite fit my mental model for organizing tests. I think there should be a standalone driver that dynamically loads test suites. In other words, the driver is an executable and each test suite is a DLL.

CuTest’s documentation is a little sparse, but similar to CUnit, it looks like that each test suite a standalone executable. Again, I want a separate test driver where test suites can be listed on the command line and possibly provide command-line options for running tests and specifying output formats.

While writing this note and looking for a few exemplary test frameworks, I found cmocka. It has a great looking website making me think it must be very polished. It also requires writing your own main function for each test suite. I’d rather just write tests and not be concerned about a main function.

I’m writing a unit-test framework for the experience, to try my own ideas of what unit tests and the testing experience should look and feel like. For example, if a test fails it should be able to throw an exception that is caught by the driver. In C exception handling can be supported through setjmp/longjmp. Splitting that between an executable and a DLL is difficult. Perhaps that’s why these frameworks are designed so that test suites are standalone executables. I think I’ve figured out how to get around that obstacle and do it cleanly.

Goals

I’ll start simply. In fact, what’s the simplest unit test framework that can get the job done? Such a project needs:

Test Driver: load and run test suites.
Test Suite: a set of tests to run.
Test Case: some standard way to write test cases and collect them into test suites such that a test driver can load, setup, run, and teardown each test.
Test Result: a way to indicate whether a test passed or failed, and why.
Reporting: a backend module to report test results in a consistent format.

The bulk of a test driver can be implemented in a static library. An actual test driver can be built up from components, so a specific driver can have a particular backend, or several selectable backends for reporting results. The rest of the internals are common to all drivers.

I believe a shared library should encapsulate a suite of test cases. The test driver itself can be built as a static library that provides all of the functionality needed to load and run tests, and collect results that can be reported in some manner (e.g., written to a terminal or a file).

Resources

Subunit is a streaming protocol for test results.
xUnit.net is an open-source unit testing tool for the .NET Framework.
xUnit, by Martin Fowler.
Common JUnit XML Format & Examples. At least in the world of Java programming, the JUnit XML file format is a standard format to exchange test results between tools. It might be worth considering as a backend to a test driver.

What Came Next

The framework described here was completed and is called Basic Unit Test (BUT). A follow-up post will cover the implementation in detail. After working with BUT, I identified one big design problem and several improvements worth pursuing, so I built a second framework called Faultline. I’ll push that to GitHub soon and write more on that in a subsequent series. It was quite a journey.

Update March 23, 2026: Faultline is on GitHub.

Glob Patterns

Mon, 08 May 2023 17:01:29 -0400

Some time in 2016 or 2017, I needed a way to match file paths with glob patterns. The trick was that it had to work in a filter driver running in the Windows kernel. There weren’t a lot of ready-to-use libraries that were kernel-ready. In fact I couldn’t find any, so I wrote my own.

Back then, I wrote an implementation in C which was very Windows-centric, and didn’t hold to the syntactic rules from the glob(7) man page. It was sufficient for the job, but I wanted to revisit the problem and create something more generally useful. I uploaded an implementation in Go on GitHub that holds to the glob(7) rules, is very efficient, and runs in user space on both Windows and Linux.

This Go module accepts the ** wildcard (to match directory paths recursively) as well as normal wildcards. When I originally researched how to go about building a pattern-matching function, I looked for existing code to get an idea of how to structure a solution. I hoped that I could find an open-source library where I could just transliterate the code from whatever language it was written to C (without any calls to the standard library, because that’s not a thing within the Windows kernel). All the examples I could find were either limited to the standard wildcards or had exponential behavior, as Russ Cox so eloquently discussed.

That got me thinking about the shape of glob patterns. Simple patterns, made up of literal strings, the ? wildcard, and character classes, are matched character-by-character (with a little extra processing for character classes). The * pattern matches zero-or-more characters followed by whatever simple pattern follows it. So abc*xyz is a glob composed of a simple pattern, abc, followed by a zero-or-more pattern *xyz. The latter pattern is called a directory pattern, because it’s limited to matching file and directory names within a single directory. Directory patterns amount to specifying a loop that consumes a character (except a path separator) every time the simple pattern that follows it fails to match some portion of a path.

Similarly, ** patterns, recursive patterns, can be thought of requiring a loop that consumes any character that isn’t matched by whatever pattern follows it. The trick here is to realize that ** can be followed by a simple pattern and zero-or-more directory patterns. If at any point during the matching process the simple pattern or any of the directory patterns that may follow it fail, then processing continues by allowing ** to consume one character from the path and then matching the path to the pattern restarts from that point. This is still an $O(n)$ process, because each iteration makes progress through the path until either the whole pattern and path are consumed, or a match cannot be found.

This realization, that recursive patterns are made up of simple and directory patterns, led to a relatively simple algorithm and a fast implementation. See the repo for the code.

Layoffs at F5

Tue, 25 Apr 2023 07:43:42 -0400

In April 2023, I was laid of from F5, Inc.. It was a significant layoff of about 9% of the workforce, or 623 employees, worldwide. Given that the economy, at least here in the United States, doesn’t seem all that bad, I was surprised to see so many good engineers, product managers, sales people, and others let go.

I started working for F5 after it acquired Threat Stack on October 1st, 2021. At the time I worked in the Application Infrastructure Protection (AIP) division doing pretty much what I was working on before—adding features to the Windows, Linux, containerized, and Fargate agents.

It’s not just the layoff that upset me. I really enjoyed working in the Agent Team and particularly on the Windows agent, but now I hear that the company intends to disband AIP, and everything that Threat Stack built over the past decade or so will be gone.

The agents were all well built tools providing telemetry to a backend platform that analyzed events to detect anomalous behavior. Several years ago, an intern and I developed the Windows agent from scratch. The team and I enhanced its capabilities through the years. I thought it had a few clever designs, especially when it came to monitoring activity in the file system.

File system monitoring was accomplished with a quite capable and efficient kernel minifilter. It had a glob pattern-matcher for comparing file activity against a set of rules that defined what behavior was “interesting”. Among other things, it could accurately detect file deletions, which is hard to do on NTFS. The minifilter had its own memory allocator and tagged allocations based on what the memory was used for. By running poolmon, it was easy to determine which components were allocating memory, how much they were allocating, and also ensure that there were no memory leaks at all.

The agent also monitored running processes, associated those processes with the accounts they were running under, watched network connections being established and broken, and looked for significant security-related events. All of this information was relayed to the backend platform for analysis. It was a good system that provided our customers with the situational awareness they needed to mitigate attacks and even stop attacks before a serious incident occurred.

Update November 2023: Yeesh! F5 had another round of layoffs earlier this month. More of my friends and previous coworkers are now looking for work. It just feels wrong. Yes, there have been a lot of layoffs from much larger tech companies, but they are still raking in lots of money. I suspect F5 is still doing very well, too. They are probably eliminating projects (and thus the employees who were working on them) that don’t directly support their core hardware business and (I assume) their aspirations to develop virtual network devices and their own cloud.

The Orchard

Sat, 05 Nov 2022 08:07:31 -0400

My wife and I went to the Paramount Theater in Boston last night to see The Orchard, a variation of Anton Chekhov’s play, The Cherry Orchard, starring Jessica Hecht and Mikhail Baryshnikov. It was a very avant-garde play. It used a robotic arm that was its own character, a Boston Dynamics robotic dog, and a projection ~~screen~~ curtain draped in front of the whole stage.

The projection screen was artfully and cinematically used during various scenes to strengthen the presentation of their characters inner emotional state. It also provided atmosphere (through, for example, projecting cherry blossoms blowing in the wind), and acted as an announcer for each act of the play.

The one real disappointment was that the actors didn’t project their voices and enunciate their words well enough, so I found the dialogue difficult to discern through much of the play. I suspect the hope was their microphones and the speakers would be enough to pick up and amplify their voices.

A Table Shortcode for Hugo

Thu, 23 Sep 2021 10:59:36 -0400

I write a lot of notes in Markdown files and use Hugo to display them in a browser. It makes for easy reading and jumping among them. Several months ago, I needed to create some tables where some cells spanned mulitple rows or columns. That’s not possible with Markdown tables. Creating tables in HTML with appropriate classes seemed tedious. I thought it might be less so by defining tables in TOML and use a shortcode to translate them into HTML.

I might be wrong. It turns out that it’s very hard to define a table in TOML. It’s even harder to define one where a cell can span two or more rows or columns. Once you have that, you still have to write a lot of CSS to get it to display properly.

What I have is a way to turn a TOML table stored in /data/complete-example.toml into this:

All the Features in the Create-Table Shortcode
Header R2C1	Header R2C2	Header R2C3
Header R3C1	Header R3C2	Header R3C3
Header R4C1	Header R4C2	Header R4C3
a	b	c
d	e	f
Header R1C1	Header R1C2	Header R1C3
foot1	foot2	foot3

It’s not a complete solution, but it’s enough given the effort to get this far.In the future, if I need fancy tables, I think I’ll just embed HTML into the markdown.

The contents of /data/complete-example.toml is:

# Table caption
caption = "All the Features in the create_table Shortcode"

[header]
  hd1 = ["Header R1C1", "Header R1C2", "Header R1C3"]
[[head]]
  hd1 = ["Header R2C1", "Header R2C2", "Header R2C3"]
[[head]]
  hd1 = ["Header R3C1", "Header R3C2", "Header R3C3"]
  hd2 = ["Header R4C1", "Header R4C2", "Header R4C3"]
[[body]]
  row = ["a", "b", "c"]
[[body]]
  row = ["d", "e", "f"]


# Don't embed colgroup in another array. It becomes an embedded map.
# [[head.colgroup]]
#   span = 1
# [[head.colgroup]]
#   span = 2

[[foot]]
  row = ["foot1", "foot2", "foot3"]

# This map is at the top-level of the table and can be used to create an HTML
# colgroup for the table. One entry for each <col> element.
[[colgroup]]
  span = 1
[[colgroup]]
  span = 2
  class = "odd"
[[colgroup]]
  span = 1
  class = "even"

To use the shortcode on this file, include {{< create_table src="complete-example" >}} in a markdown file.

The create_table Shortcode

This shortcode starts with realizing Hugo’s built-in .Site.Data variable isn’t a path to a configured data directory. It’s a map of all files in the data folder, its subfolders, the files contained in those subfolders, and the contents of all those files. On one hand, that’s rather insane. On the other, it gets all that data into memory so Hugo can operate on it more quickly than if files had to be individually loaded and parsed.

Let’s capture that in a variable for use later:

<!--
  .Site.Data isn't a path. It's a map of all the files in the data folder,
  its subfolders and their files, and the contents of all those files.
-->
{{- $data := .Site.Data -}}

Next, get the data that’s in the given file. The file is given in the src attribute:

{{- $src := .Get "src" -}}
{{- $pathComponents := split $src "/" -}}

Here’s the code to pull out the data just for that file:

<!--
  Use the components of the src path to rummage through the map-of-maps in
  $data to get the src table's contents.
-->
{{- range $component := $pathComponents -}}
  {{- if ne $data nil -}}
    {{- $data = index $data $component -}}
  {{- end -}}
{{- end -}}

From here, I’ll give a quick top-down view of the shortcode. It defines a table as an HTML <table> element with a class of the same name. The contents of the table is generated from a buildTable template and our data:

<table class="table">
{{- template "buildTable" $data -}}
</table>

buildTable Template

The buildTable template attempts to determine if the TOML data has a head and body. It also captures the data for a caption, any column groups, the head, body, and foot of the table. It starts with initializing some variables.

<!-- Table data is always a map -->
  {{- $table := . -}}
  {{- $haveHead := false -}}
  {{- $haveBody := false -}}
  {{- $captionValue := "" -}}
  {{- $colGroupValue := "" -}}
  {{- $bodyValue := "" -}}
  {{- $headValue := "" -}}
  {{- $footValue := "" -}}

The next step is to collect all the keys in the map. The keys are expected to be the components of an HTML table.

body
caption
colgroup
head
foot

  <!-- collect all the keys in the map -->
  {{- range $key, $val := $table -}}
    {{- if eq $key "body" -}}
      {{- if $haveBody -}}
        {{- $haveBody = $haveBody | append $val -}}
      {{- else -}}
        {{- $haveBody = true -}}
        {{- $bodyValue = $val}}
      {{- end -}}
    {{- else if eq $key "caption" -}}
      {{- $captionValue = $val -}}
    {{- else if eq $key "colgroup" -}}
      {{- $colGroupValue = $val -}}
    {{- else if eq $key "head" -}}
      {{- $haveHead = true -}}
      {{- $headValue = $val -}}
    {{- else if ne $key "foot" -}}
      {{- if $haveBody -}}
        {{- $bodyValue = $bodyValue | append $val -}}
      {{- else -}}
        {{- $haveBody = true -}}
        {{- $bodyValue = $val}}
      {{- end -}}
    {{- else -}}<!-- key is foot -->
      {{- $footValue = $val -}}
    {{- end -}}
  {{- end -}}

Now we can fill in all those variables.

  {{- if ne $captionValue "" -}}
    <caption>{{- $captionValue -}}</caption>
  {{- end -}}
  {{- if ne $colGroupValue "" -}}
    <colgroup>
      {{- template "createColgroup" $colGroupValue -}}
    </colgroup>
  {{- end -}}
  {{- if ne $headValue "" -}}
    <thead>
      {{- template "createRowsHead" $headValue -}}
    </thead>
  {{- end -}}
  {{- if ne $bodyValue "" -}}
    <tbody>
      {{- template "createRows" $bodyValue -}}
    </tbody>
  {{- end -}}
  {{- if ne $footValue "" -}}
    <tfoot>
      {{- template "createRows" $footValue -}}
    </tfoot>
  {{- end -}}

There are several templates used by that chunk of code. They are small, so we can go through them quickly.

createColGroup Template

createColGroup creates column groups with the <col> element:

{{- define "createColgroup" -}}
  {{- $colgroup := . -}}
  {{- range $idx, $col := $colgroup}}
    <col{{range $attr, $val := $col}} {{$attr}}="{{$val}}" {{end}}>
  {{- end -}}
{{- end -}}

createRowsHead and processMapHead Templates

These two templates are mutually recursive. createRowsHead creates rows in the <head> section of the table. It processes each element of the row, creating a new <th> element as it goes.

<!-- Use only within thead elements. This will generate
   <tr><th>...</th><th>...</th>...</tr> row sequences
-->
{{- define "createRowsHead" -}}
  {{- $rows := . -}}
  {{- range $idx, $row := $rows -}}
    {{- if and (not (reflect.IsMap $row)) (not (reflect.IsSlice $row)) -}}
      <!-- row value is a scalar -->
      <th>{{- $row -}}</th>
    {{- else if reflect.IsMap $row -}}
      <!-- row value is a map -->
      {{- template "processMapHead" $row -}}
    {{- else if reflect.IsSlice $row}}
      <!-- row value is a slice -->
      {{- template "createRowsHead" $row -}}
    {{- else -}}
      <!-- row value type is unknown -->
      {{- $idx -}} (head-row-unknown): {{- $row -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

If a new row needs to be generated, createRowsHead calls processMapHead which generates a new <tr> element. Likewise, processMapHead will call back to createRowsHead in the case that a column has more than one value.

{{- define "processMapHead" -}}
  {{- $row := . -}}
  {{- range $k, $v := $row -}}
    {{- if and (not (reflect.IsMap $v)) (not (reflect.IsSlice $v)) -}}
      <td>{{- $k -}} (map->scalar): ({{$v}})</td>
    {{- else if reflect.IsMap $v -}}
      <tr class="head">{{- $k -}} (map-map): {{- template "processMapHead" $v -}}</tr>
    {{- else if reflect.IsSlice $v}}
      <tr class="head">{{- template "createRowsHead" $v -}}</tr>
    {{- else -}}
      <td>{{$k}} (map-unknown): {{- $v -}}</td>
    {{- end -}}
  {{- end -}}
{{- end -}}

createRows and processMap Templates

These two templates are mutually recursive. createRows creates the column (<td>) elements for each row in <body> or <foot> element. Note that createRows is a recursive template, so it can handle some weirdly designed tables.

<!-- Use within <table>, <tbody>, or <tfoot> elements, but not within <thead>;
  this will generate <tr><td>...</td><td>...</td>...</tr> row sequences
-->
{{- define "createRows" -}}
  {{- $rows := . -}}
  {{- range $idx, $row := $rows -}}
    {{- if and (not (reflect.IsMap $row)) (not (reflect.IsSlice $row)) -}}
      <!-- row value is a scalar -->
      <td>{{- $row -}}</td>
    {{- else if reflect.IsMap $row -}}
      <!-- row value is a map -->
      {{- template "processMap" $row -}}
    {{- else if reflect.IsSlice $row}}
      <!-- row value is a slice -->
      {{- template "createRows" $row -}}
    {{- else -}}
      <!-- row value type is unknown -->
      {{- $idx -}} (rows-unknown): {{- $row -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

processMap either creates columns in a row, or generates a new row and calls itself recursively. If a column has more than one value, it calls back to createRows to process them.

{{- define "processMap" -}}
  {{- $row := . -}}
  {{- range $k, $v := $row -}}
    {{- if and (not (reflect.IsMap $v)) (not (reflect.IsSlice $v)) -}}
      <td>{{- $k -}} (map->scalar): ({{$v}})</td>
    {{- else if reflect.IsMap $v -}}
      <tr class="body">{{- $k -}} (map-map): {{- template "processMap" $v -}}</tr>
    {{- else if reflect.IsSlice $v}}
      <tr class="body">{{- template "createRows" $v -}}</tr>
    {{- else -}}
      <td>{{$k}} (map-unknown): {{- $v -}}</td>
    {{- end -}}
  {{- end -}}
{{- end -}}

The Complete create_table Shortcode

Here’s the whole thing w/o comments. It’s not that useful, but it was a journey and an education to get here.

<!--
  .Site.Data isn't a path. It's a map of all the files in the data folder,
  its subfolders and their files, and the contents of all those files.
-->
{{- $data := .Site.Data -}}

{{- $src := .Get "src" -}}
{{- $pathComponents := split $src "/" -}}

<!--
  Use the components of the src path to rummage through the map-of-maps in
  $data to get the src table's contents.
-->
{{- range $component := $pathComponents -}}
  {{- if ne $data nil -}}
    {{- $data = index $data $component -}}
  {{- end -}}
{{- end -}}

{{- define "processMapHead" -}}
  {{- $row := . -}}
  {{- range $k, $v := $row -}}
    {{- if and (not (reflect.IsMap $v)) (not (reflect.IsSlice $v)) -}}
      <td>{{- $k -}} (map->scalar): ({{$v}})</td>
    {{- else if reflect.IsMap $v -}}
      <tr class="head">{{- $k -}} (map-map): {{- template "processMapHead" $v -}}</tr>
    {{- else if reflect.IsSlice $v}}
      <tr class="head">{{- template "createRowsHead" $v -}}</tr>
    {{- else -}}
      <td>{{$k}} (map-unknown): {{- $v -}}</td>
    {{- end -}}
  {{- end -}}
{{- end -}}

{{- define "processMap" -}}
  {{- $row := . -}}
  {{- range $k, $v := $row -}}
    {{- if and (not (reflect.IsMap $v)) (not (reflect.IsSlice $v)) -}}
      <td>{{- $k -}} (map->scalar): ({{$v}})</td>
    {{- else if reflect.IsMap $v -}}
      <tr class="body">{{- $k -}} (map-map): {{- template "processMap" $v -}}</tr>
    {{- else if reflect.IsSlice $v}}
      <tr class="body">{{- template "createRows" $v -}}</tr>
    {{- else -}}
      <td>{{$k}} (map-unknown): {{- $v -}}</td>
    {{- end -}}
  {{- end -}}
{{- end -}}

<!-- Use only within thead elements. This will generate
   <tr><th>...</th><th>...</th>...</tr> row sequences
-->
{{- define "createRowsHead" -}}
  {{- $rows := . -}}
  {{- range $idx, $row := $rows -}}
    {{- if and (not (reflect.IsMap $row)) (not (reflect.IsSlice $row)) -}}
      <!-- row value is a scalar -->
      <th>{{- $row -}}</th>
    {{- else if reflect.IsMap $row -}}
      <!-- row value is a map -->
      {{- template "processMapHead" $row -}}
    {{- else if reflect.IsSlice $row}}
      <!-- row value is a slice -->
      {{- template "createRowsHead" $row -}}
    {{- else -}}
      <!-- row value type is unknown -->
      {{- $idx -}} (head-row-unknown): {{- $row -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

<!-- Use within <table>, <tbody>, or <tfoot> elements, but not within <thead>;
  this will generate <tr><td>...</td><td>...</td>...</tr> row sequences
-->
{{- define "createRows" -}}
  {{- $rows := . -}}
  {{- range $idx, $row := $rows -}}
    {{- if and (not (reflect.IsMap $row)) (not (reflect.IsSlice $row)) -}}
      <!-- row value is a scalar -->
      <td>{{- $row -}}</td>
    {{- else if reflect.IsMap $row -}}
      <!-- row value is a map -->
      {{- template "processMap" $row -}}
    {{- else if reflect.IsSlice $row}}
      <!-- row value is a slice -->
      {{- template "createRows" $row -}}
    {{- else -}}
      <!-- row value type is unknown -->
      {{- $idx -}} (rows-unknown): {{- $row -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

{{- define "createColgroup" -}}
  {{- $colgroup := . -}}
  {{- range $idx, $col := $colgroup}}
    <col{{range $attr, $val := $col}} {{$attr}}="{{$val}}" {{end}}>
  {{- end -}}
{{- end -}}

{{- define "buildTable" -}}

<!-- Table data is always a map -->
  {{- $table := . -}}
  {{- $haveHead := false -}}
  {{- $haveBody := false -}}
  {{- $captionValue := "" -}}
  {{- $colGroupValue := "" -}}
  {{- $bodyValue := "" -}}
  {{- $headValue := "" -}}
  {{- $footValue := "" -}}

  <!-- collect all the keys in the map -->
  {{- range $key, $val := $table -}}
    {{- if eq $key "body" -}}
      {{- if $haveBody -}}
        {{- $haveBody = $haveBody | append $val -}}
      {{- else -}}
        {{- $haveBody = true -}}
        {{- $bodyValue = $val}}
      {{- end -}}
    {{- else if eq $key "caption" -}}
      {{- $captionValue = $val -}}
    {{- else if eq $key "colgroup" -}}
      {{- $colGroupValue = $val -}}
    {{- else if eq $key "head" -}}
      {{- $haveHead = true -}}
      {{- $headValue = $val -}}
    {{- else if ne $key "foot" -}}
      {{- if $haveBody -}}
        {{- $bodyValue = $bodyValue | append $val -}}
      {{- else -}}
        {{- $haveBody = true -}}
        {{- $bodyValue = $val}}
      {{- end -}}
    {{- else -}}<!-- key is foot -->
      {{- $footValue = $val -}}
    {{- end -}}
  {{- end -}}

  {{- if ne $captionValue "" -}}
    <caption>{{- $captionValue -}}</caption>
  {{- end -}}
  {{- if ne $colGroupValue "" -}}
    <colgroup>
      {{- template "createColgroup" $colGroupValue -}}
    </colgroup>
  {{- end -}}
  {{- if ne $headValue "" -}}
    <thead>
      {{- template "createRowsHead" $headValue -}}
    </thead>
  {{- end -}}
  {{- if ne $bodyValue "" -}}
    <tbody>
      {{- template "createRows" $bodyValue -}}
    </tbody>
  {{- end -}}
  {{- if ne $footValue "" -}}
    <tfoot>
      {{- template "createRows" $footValue -}}
    </tfoot>
  {{- end -}}

{{- end -}}

<table class="table">
{{- template "buildTable" $data -}}
</table>

Asymptotic Notation

Thu, 23 Sep 2021 07:45:20 -0400

Big-O, Big-$\Omega$ (Big-Omega), and Big-$\Theta$ (Big-Theta) notation are used to describe some aspect of an algorithm (usually the running time or the memory resources it needs) relative to the size of the input data.

Big-O Notation: describes the asymptotic upper bound. In other words, if $f(n)$ describes the running time of an algorithm; $f(n) \text{ is said to be } O(g(n))$ if there exists a positive constant $C \text{ and } n_0$ such that $0 \le f(n) \le c g(n) \text{ for all } n \ge n_0$.
Big-$\Omega$ Notation: describes the asymptotic lower bound. In other words, if $f(n)$ describes the running time of an algorithm; $f(n) \text{ is said to be } \Omega(g(n))$ if there exists a positive constant $C \text{ and } n_0$ such that $0 \le cg(n) \le f(n) \text{ for all } n \ge n_0$.
Big-$\Theta$ Notation: describes the running time or memory usage. It seems to exist only when $O(g(n)) == \Omega(g(n))$. In other words, if $f(n)$ is the running time of an algorithm, then $f(n)$ is said to be $\Theta(g(n))$ if $f(n) == O(g(n)) \text{ and } f(n) == \Omega(g(n))$. Mathematically, $0 \le f(n) \le C_{1}g(n) \text{ for } n \ge n_0 \text{ and } 0 \le C_{2}g(n) \le f(n) \text{ for } n \ge n_0$. These equations can be merged into $0 \le C_{2}g(n) \le f(n) \le C_{1}g(n) \text{ for } n \ge n_0$. In other words, $f(n)$ is sandwiched between $C_{2}g(n) \text{ and } C_{1}g(n)$.

Here is a summary of these three asymptotic notations. They are used to express the computational complexity of an algorithm.

Big-O	Big-$\Omega$	Big-$\Theta$
The maximum rate of growth of an algorithm can be characterized as less than or equal to a given function.	The minimum rate of growth of an algorithm can be characterized as greater than or equal to a given function.	The rate of growth of an algorithm is equal to a given function.
The algorithm’s asymptotic upper bound.	The algorithm’s asymptotic lower bound.	The algorithm has an asymptotically tight bound.
Worst case or ceiling of the growth rate.	Best case or floor of the growth rate.	The worst case and best case of the growth rate is characterized by the same function or that they converge on said function.

Waiting for Election Results (2020)

Sat, 07 Nov 2020 08:23:14 -0500

The election is over. All we can do is wait for the counting complete. I hope enough people who see just how terrible this failure of a human being, Donald Trump, is went to the polls and voted. The future of our country depends on it.

Nevertheless, I have to get a few things off my chest. This morning, I considered writing a post about how horrible and dangerous the actions and words of Donald Trump are and how they undermine trust in one of the most sacred aspects of American democracy, the electoral process. It is through our right to vote for our representatives in government that our democracy functions. Without trust in that process, our democracy and our country fail.

I was going to declare Trump a fascist and state that public officials who stay quiet are tacitly in agreement with his baseless claims of corruption in the election. Of course, those who publicly state support for him and his lies, I was also going to slap on the fascist label. Instead of labeling Trump a fascist outright, I took a step back. I wanted to learn a little more about what a fascist really is.

I found an article by John McNeil, a professor of history at Georgetown University, How Fascist is Donald Trump? There’s Actually a Formula for That. McNeil measures Trump’s statements and behaviors against 11 traits of fascism through the lens of the two horrible dictators who created it: Benito Mussolini and Adolf Hitler. Through this comparison, I realized just how much more brutal are real fascists. Thankfully, Trump can count fascism as another of his many failures.

The truth is state officials all across the country have worked very hard to ensure all legal votes are counted. Most ballots are counted by machine. Both major parties have representatives observing the counting process, so if for some reason the machine can’t read a ballot, both parties view the ballot and try to understand the intent of the voter. Given the level of oversight and the difficulty of synchronizing fraud across multiple states, it is inconceivable that either party could throw the election.

Trump has been, and still is, a danger to our country. He is relentlessly undermining trust in our electoral process. He makes baseless claims of illegal ballots being counted. He falsely claimed that no ballots could be legally counted after election day - at least in Pennsylvania where he was ahead. However, he wanted counting to continue in Arizona, where we was behind. He has threatened to not leave the Office of the President if he loses. He and others who should know better (like Richard Grenell, former Acting Director of National Intelligence) have claimed that illegal votes are being counted in Nevada.

He is truly a horrible person. During his time as president, some of Trumps terrible acts are:

he refused to denounce white supremacists, and so he tacitly supports them.
he instituted a policy that separated immigrant parents from their children, caged the children, and deported the parents. There are now over 500 immigrant children who cannot be reunited with their parents. This is monstrous. Does this reach the level of a crime against humanity?
he lied about people fleeing brutality in South and Central America, characterizing them as criminals and drug addicts.
he distanced the US from her allies in Europe.
he has been duped by brutal dictators Vladimir Putin and Kim Jong-un into trusting them.
he lied to, and continues to lie to the American people about the dangers of COVID-19. Here in early November, cases are spreading at a frightening rate (over 140,000 new cases and 1200 deaths yesterday).
he continues to lie about how quickly we will recover from the pandemic. Given how fast the disease is spreading and its mortality rate (2.4% in the US according to Johns Hopkins University of Medicine) there could be thousands more deaths per day.

Vote 2020

Wed, 28 Oct 2020 08:12:51 -0400

If you live in the United States of America, please vote! Election Day is Tuesday, November 3rd.

Vote for whomever you like, but understand that Trump is tearing apart our country.

He lied to us Americans about the deadliness of COVID-19 and how easliy it spreads. Now well over 200,000 Americans are dead. Many of those deaths could have been prevented if we had been forewarned and taken precautions.
He has failed the economy. Many small businesses are failing and may not recover.
He ripped apart immigrant families and there are now over 500 immigrant children who can’t be reunited with their parents.
He bullies, denigrates, and belittles people who disagree with him or are less powerful than he is so he can feel superior.
He refuses to denounce white supremacists and actually commanded one group to “stand back and stand by”.

Do you really want him to be our president? I don’t understand how that’s possible.

A New Hugo-Based Blog

Sat, 22 Feb 2020 17:38:32 -0500

In my previous post I talked a little about why and how I started this blog. Here I want to present my experience with Hugo and what I like about it.

Late in 2018 I came across Hugo, a static site generator written in Go. Dissatisfied with Jekyll, I needed a different static site generator, and I had been learning Go at Work. This looked like a good opportunity to try blogging again.

I stumbled quite badly a few times along the way. I thought a theme would help me get my site up and running quickly, but they don’t balance well with my need to twiddle with the site’s layout and look and feel. The long and short of it is, I took what I learned from trying out a couple of themes, and hunkered down to learn a few things about “The Hugo Way”, and the basics of HTML & CSS.

The Short-lived Academic Theme

As I have a tendency to do with new tools, I dove in too deep, too fast. Hugo has themes, and they look like a good way to get something up and running quickly. I looked over [`]the theme gallery](https://themes.gohugo.io/) checking all the features and how they looked. Academic is very flexible and chock full of features. I decided to give it a whirl in February 2019. It looked like this out of the box.

First Try with Vanilla Bootstrap

I tried a few small configuration changes to see how I liked it. My hope was only minor changes would be necessary so I could have a site that looked good to me and had a responsive layout. That way I could just write posts.

My First Time Using the Academic Theme

Quick Switch to Vanilla Bootstrap

Sadly, Academic was short lived. By the 9th of the month I gave up on it. For all the features it has, I found it too hard to configure and customize. Don’t get me wrong. Academic is amazing and has good documentation, but this theme has its own themes. It’s a little more complex than what I needed. Also, I didn’t realize at the time, but Academic isn’t just a Hugo theme. It is a website builder. It uses Hugo as an engine to bring life to a website rather than being a set of content-decorators run by Hugo.

Too new to how Hugo workds and the complexities of a website builder, I looked for a simpler solution and settled on Vanilla Bootstrap.

First Try with Vanilla Bootstrap

The change was dramatic and configuration was simplified. While Academic has two levels of configuration, the core through config/_default/config.toml and another level controlled through the content in the content/home directory, Vanilla Bootstrap requires only core configuration of Hugo and a handful of theme-specific parameters all managed through the default configuration files.

It looked pretty good for a few hours of work. It was easy to define a menu at the top of the home page providing links to other pages. Most of what I needed to define the menus was contained in config/_default/config.toml:

  # See https://feathericons.com/
  # The value of pre is the icon name
  [menu]
    [[menu.nav]]
      name = "Home"
      pre = "home"
      url = "/"
      weight = 1
    [[menu.nav]]
      name = "Notes"
      pre = "edit"
      url = "/notes/"
      weight = 2
    [[menu.nav]]
      name = "About"
      pre = "smile"
      url = "/about/"
      weight = 3
    [[menu.nav]]
      name = "Now"
      pre = "play"
      url = "/now/"
      weight = 4
    [[menu.nav]]
      name = "RSS"
      pre = "rss"
      url = "/index.xml"
      weight = 5

The theme provides the other major component in theme/vanilla/layouts/partials/nav.html:

  <div id="nav-border" class="container">
    <nav id="nav" class="nav justify-content-center">
    {{ $showActiveNav := .Site.Params.showActiveNav }}
    {{ $currentPage := . }}
    {{ range .Site.Menus.nav }}
      {{ $active := "" }}
      {{ if eq $showActiveNav true }}
        {{ $isMenu := or ($currentPage.IsMenuCurrent "nav" .) ($currentPage.HasMenuCurrent "nav" .) }}
        {{ if or $isMenu (eq $currentPage.Title .Name) }}
          {{ $active = "nav-link-active" }}
        {{ end }}
      {{ end }}
      {{ $icon := printf "<i data-feather=\"%s\"></i>" .Pre }}
      {{ $text := print $icon " " .Name | safeHTML }}
      <a class="nav-link {{ $active }}" href="{{ .URL }}">{{ $text }}</a>
    {{ end }}
    </nav>
  </div>

It cycles through the menu.nav items in config.toml and translates those values to a feather icon, text, and a link to the given URL. The site was beginning to fill out, although today the icons look silly to me.

There’s a “Notes” menu item, because I thought I would use the site to keep notes as well as regular blog posts. I’ve since separated my personal notes and works-in-progress from blog posts. I’m willing to go only so far in what I make public. It’s best to keep some thoughts as background material, and let others stew for a while before publicizing them.

I created a simple 404 page, and a big “jumbotron” area for all the index pages. The site was beginning to fill out. Although, today the icons look silly to me.

Jumbotron

The note is dated April 8, 2019 because that was my goal for publishing the site. It took a little longer than I expected. Mostly, I was unsure about putting up my notes in public, the design was poor, and I thought I should do better.

In hindsight, content is more important than style. It would have been better to write posts and develop the site simultaneously.

More Puttering Around with Layout

It was still early February, and I was learning how Hugo worked, it’s configuration system, and how and where to integrate CSS, SCSS, and JavaScript (particularly MathJax). I spent time breaking up the layout into partials for more consistency across the site.

I added a picture of Motif No. 1 I took in Rockport, Massachusetts to fill the jumbotron. It got cropped rather poorly, though.

Wide Menu Day

MathJax

I was happy to learn a little about configuring MathJax. It makes it possible to display equations on web pages. To configure MathJax to automatically number equations - just include the following in layouts/partials/script.html (which is included in layouts/_default/baseof.html):

  <!-- Configure MathJax for automatic equation numbering. See
    http://docs.mathjax.org/en/latest/tex.html#automatic-equation-numbering
    for details
  -->
  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({
      TeX: { equationNumbers: { autoNumber: "AMS" } }
    });
  </script>

I realize that MathJax is a large JavaScript library. It’s probably stupid to try optimizations without testing, nevertheless I didn’t want to load MathJax with every page. Most pages don’t require it, so I wrap the MathJax configuration in an if-block that detects if the page (or the whole site) defines the parameter math. The configuration has been updated, as well.

Now all I have to do is add math: true to the front matter of any file that includes $\LaTeX$.

  <!-- Include MathJaX if either the page or the site params define math=true -->
  {{- if or .Params.math .Site.Params.math -}}
  <!-- Configure MathJax for automatic equation numbering. See
    https://docs.mathjax.org/en/latest/tex.html#automatic-equation-numbering
    for details.
    Also, for tex2jax configuration see https://docs.mathjax.org/en/latest/
    options/preprocessors/tex2jax.html

    Note that the double-backslashes are very important. Without them ordinary
    markdown will interpret (parenthetical statements) as inline math, and cause
    similar problems if text is put between '[' and ']'.
  -->
  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({
      TeX: { equationNumbers: { autoNumber: "AMS" },
              extensions: ["AMSmath.js", "AMSsymbols.js"] },
      tex2jax: {
        inlineMath: [['$','$'], ['\\(','\\)']],
        displayMath: [['$$','$$'], ['\\[','\\]']],
        processEscapes: true,
        processEnvironments: true,
        skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
      }
    });
  </script>

In addition to being updated, it tries to load from a Cloudflare, but if it can’t connect it loads a local copy.

  <!--
    Load MathJax. Note that this is one of the most general configurations.
    See the configuration docs for others. There might be a lighter version
    that will work for my purposes.
    https://docs.mathjax.org/en/latest/config-files.html#common-configurations
  -->
  <!-- MathJax: Fall back to local if your computer is offline and can't connect
    to the CDN. For convenience, the configuration for the fallback deactivates
    image fonts support (imageFont:null). This allows you to host a slim local
    copy by deleting the PNG fonts.-->
  <script async type="text/javascript" src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML'></script>

  <script>window.MathJax || document.write('<script type="text/x-mathjax-config">MathJax.Hub.Config({"HTML-CSS":{imageFont:null}});<\/script><script type="text/javascript" src="{{ "scripts/MathJax-2.7.5/MathJax.js" | absURL }}?config=TeX-AMS-MML_HTMLorMML"><\/script>')</script>
  {{- end -}}

Pagination

I had added lots of notes and the layout was still sprinkled with distracting icons, this time with a redish theme and green accents. I had at least learned how to paginate my page lists. For example, the default list (layouts/_default/list.html) used Hugo’s built-in pagination:

  {{ define "main" }}

  <main>
      <!-- default list template -->
      <article>
        <!-- "{{.Content}}" pulls from the markdown content of the corresponding _index.md -->
        {{ .Content }}
      <!-- Paginates through content/note/*.md -->
      {{ $paginator := .Paginate (where .Pages "Type" "note") }}
      {{ range $paginator.Pages }}
        <h2><a class="font-125" href="{{ .Permalink }}">{{ .Title }}</a></h2>
        <div class="article-meta-data">
          {{ partial "date-and-tags.html" . }}
          <!-- this renders based on layouts/_default/summary.html (either the
          local one, or the one in a theme -->
          {{ .Render "summary" }}
        </div>
      {{ end }}
      {{ partial "pagination.html" . }}
      </article>
  </main>

  {{ end }}

Pagination, Redish Theme, and Green Accents

Scrollbar Jumping

At some point I noticed that when navigating from a page that had no scrollbar (like a short post or note) to one that did (such as the paginated lists of notes displayed above) the whole layout shifted slightly. I found a fix for it at CSS-Tricks.

At the time, I had a layouts/partials/style.html partial file. All I had to do was add a few lines of CSS to it:

  html {
    margin-left: calc(100vw - 100%);
    margin-right: 0;
  }

SCSS Pipeline Processing

By April I had setup a pipeline for processing SCSS into CSS. The pipeline consisted of this small amount of template code:

  <!-- For more info about using SCSS and this pipeline see:
    https://github.com/gohugoio/hugo/commit/dea71670c059ab4d5a42bd22503f18c087dd22d4,
    https://gohugo.io/hugo-pipes/scss-sass/, https://gohugo.io/hugo-pipes/postcss/,
    and https://gohugo.io/hugo-pipes/
  -->
  {{ $style := resources.Get "sass/main.scss" | toCSS | minify | fingerprint }}
  <link rel="stylesheet" href="{{ $style.RelPermalink }}" integrity="{{ $style.Data.Digest }}" media="screen">

The main.scss file lived in assets/scss/ at the root of the repository.

Sorry Vanilla. You have to Go

One aspect of design I didn’t enjoy was trying to figure out the correct CSS classes to apply to a given situation. For example, the body element is <body class="d-flex flex-column h-100">. I have no idea what those classes mean and why I need them, so I started learning more about HTML and CSS.

My new goal was to really understand the structure of my site, so I know where things are, what needs to be modified as I build it to look the way I want it to, and know the elements and classes defined in the layout so they can be styled correctly. Vanilla Bootstrap was a nice place to start, but I don’t understand the choices made for structure and styling. Its use of Bootstrap added another layer of complexity to learning how changes to CSS will affect the site.

In the middle of April, I ripped out Vanilla Bootstrap and started over.

Back to Basics

Weird. I started off the year with a sophisticated theme, because I thought it would help me get to a nice looking website fast. I found the large array of options in Academic to be overwhelming.

Switching to the theme to Vanilla enabled me to learn more about layout and styling, but what I wound up with was cutesy and still too difficult to reason about when it came to knowing which levers to pull and dials to turn to affect the layout and styling in a predictable way.

Ripping out Vanilla left me with a barebones layout. Here are some of the things I learned along the way to creating a site more to my liking.

By late April, I learned that navigation links didn’t have to be wrapped in an unordered list. Looking through git log, I found the navigation menu had always been wrapped in an unordered list.

  <ul class="navbar-nav mr-auto">
    <li class="nav-item">
      <a class="nav-link" href="/#about" data-target="#about">
        <span>Home</span>
      </a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="/#publications_featured" data-target="#publications_featured">
        <span>Publications</span>
      </a>
    </li>

Now I have just a <nav> element that wraps a <div>:

  <nav class="main-nav">
    <div class="main-nav__items">
      <a class="main-nav__link navLink-active" href="http://localhost:1414/">Home</a>
      <a class="main-nav__link " href="http://localhost:1414/about/">About</a>
      <a class="main-nav__link " href="http://localhost:1414/now/">Now</a>
      <a class="main-nav__link " href="http://localhost:1414/index.xml">RSS</a>
    </div>
  </nav>

The CSS for this section consists of class definitions for main-nav and main-nav__items. It is very simple, and doesn’t even try to style the main-nav__link class.

  .main-nav {
    display: flex;
    justify-content: flex-start;
  }

  .main-nav__items a {
    font-size: 1.1em;
    margin-right: 1ch;
  }

Unwrapping them changed navigation from:

Unstyled Navigation List

to this:

Plain Navigation

General Layout

Per the MDN docs on box-sizing border-box makes dealing with the sizes of elements much easier, and generally eliminates a number of pitfalls you can stumble on while laying out your content, so I set border-box globally.

  * {
    box-sizing: border-box;
  }

I learned I can set site-wide parameters in Hugo’s configuration files. I set the site width and several other parameters in config/_default/params.toml:

  showActiveNav = true
  author = "Douglas Cuthbertson"
  description = "This is my soapbox for thoughts on programming, project planning, sketching, drawing, kempo, and any other topic that may suit my fancy."
  dateFormat = "Monday Jan 2, 2006"
  dateFormatExtended = "Monday Jan 2, 2006 15:04"
  subtitle = ""
  copyright = "(c) 2015-2020 Douglas Cuthbertson. This work is licensed under the [Creative Commons Attribution 4.0 (CC BY 4.0), International License](https://creativecommons.org/licenses/by/4.0/)"
  footerText = "Made with HTML, CSS, JavaScript, and perseverance. Generated by [Hugo](https://gohugo.io/)"
  hideFooter = false
  #featured_image = "/images/gargoyle-overlooking-paris.jpg"
  #featured_image = "/images/motif-number-1.jpg"
  site_width = "104ch"

  componentDropCaps = "drop-caps_goudy"
  mainSections = ["note", "post", "project"]
  planck = "\u210E"
  reduced_planck = "\u210F"

and use site_width in assets/style/base.css as follows:

  {{ $siteWidth := .Site.Params.site_width }}
  {{ if not .Site.Params.site_width }}
  {{ $siteWidth = "936px" }}
  {{ end }}

I’ve only recently decided that this is a bad idea. Every time I try to experiment with the site width, I have to touch the configuration. Hugo must go through a complete rebuild of the site, which takes much more time than necessary.

The only reason to put a parameter in a configuration file is if the value must be accessed from more than one place. In this case, it was needed only in a single CSS file. Once I defined the width directly in base.css, site rebuilds were faster, and my CSS is no longer cluttered with Go template code. Also, layouts/partials/head.html was slightly simplified. Instead of accessing base.css as

  {{ $cssBase := resources.Get "style/base.css" | resources.ExecuteAsTemplate "style.base.css" . }}

the code is now

  {{ $cssBase := resources.Get "style/base.css" }}

Color Consistency and Contrast

In May I was trying to ensure colors were being used consistently. I learned that the site should have primary and accent colors, and define the color of the body text. Some designers say that black text on a white background is too harsh and set dark gray text on a light gray background. When I look at those sites, I find the contrast is often too low and causes eye strain. I originally just went with black text on white. I figured it’s a work in progress, and that can be adjusted when the rest of the site is more to my liking.

In deference to experienced designers I now set the text to a very dark gray on a very light gray background. I created a palette using CSS custom properties:

  :root {
    --color100: #f5fffa;
    --color200: #7cffbb;
    --color300: #00eb75;
    --color400: #00c663;
    --color500: #00a151;
    --color600: #007c3e;
    --color700: #00572c;
    --color800: #003219;
    --color900: #000b05;
    --gray100: #fcfcfc;
    --gray200: #dedede;
    --gray300: #bfbfbf;
    --gray400: #a1a1a1;
    --gray500: #828282;
    --gray600: #636363;
    --gray700: #454545;
    --gray800: #262626;
    --gray900: #080808; /* text */
    --color500-complement: #a30052; /* anchor hover */
    --color500-adjacent: #0062a3; /* drop-caps */
    --color500-adjacent-complement: #a34100; /* reserved */
    --color700-complement: #00572b;
    --color700-adjacent: #003457;
    --color700-adjacent-complement: #572300;
  }

I like this aspect of CSS. It means I can define all the colors I care about in one place, and I don’t have to learn SCSS at the moment to do it.

Some sites eschew black text on a white background. For example, Web Design in 4 Minutes recommends using a medium gray (#555) for body text, a dark gray (#333) for headings and strong text all against a white background. However that creates a rather low contrast. To make matters worse, the background for code blocks is set to #eee.

The Web Content Accessibility Guidelines recommends a contrast ratio of at least 7:1 for normal text and 4.5:1 for large text. Large text is defined as 14 point (typically 18.66px) and bold or larger, or 18 point (typically 24px) or larger. The contrast ratio for headings set to #333 against white is strong at 12.62:1. Body text set to #555 against white is barely acceptable at 7.46:1. Finally, the constrast ratio of code blocks (#555 against a background of #eee) is unacceptable at 6.42:1.

Originally, I had black text on a white background. In deference to designers who have a lot more experience creating web sites than I do, I set the background and text colors to the lightest and darkest grays in the palette, respectively.

  body {
    background-color: var(--gray100);
    color: var(--gray900);
  }

The contrast ratio is 19.52:1. Is that too high? One day I’ll look into separate degrees of contrast for body text and headings.

Styling Fun

One thing I particularly liked was how nice drop caps looked on Gwern. I looked at his CSS and created a new file, static\style\drop-caps\drop-caps.css with a simplified version of his CSS. I dropped it in the static/ directory instead of the assets/ folder out of expediency, and I modified layouts/_default/baseof.html to pull in the drop caps definitions.

By the end of June I removed most of the feather icons and simplified the layout. It looked better.

June 2019. A More Simple Presentation

Debugging Layouts

A simple trick to help debug layouts is to put a high-contrast border and background color around the sections you’re working on.

  .wrapper > * {
    border: 2px solid #f08c00;
    background-color: #ffec99;
    border-radius: 5px;
    padding: 10px;
  }

A little thing like that helped me make a two column layout.

Two Column Layout

By the end of September last year, I had restructured a lot of the blog. It has a stronger two-column layout and a splash of color.

A Splash of Color

Since then, I’ve been periodically iterating on the design. It is pretty much complete and I’m generally happy with the way it has turned out. I’ll continue to fiddle with it here and there, but I plan to write about things with which I’m more familiar.

Restart

Tue, 11 Feb 2020 05:48:36 -0500

Creating a blog is hard. I admire those who are able to design their own and write regular posts, so much so that I’m trying again to create my own blog. I started this blog late in 2015. After writing a few posts, I became discouraged. I didn’t like the way it looked, the tools often broke, and I didn’t have a clear idea of what I wanted to write, or why I was blogging.

Recently I was inspired by a post by Mattias Ott from May 12, 2019, Into the Personal-Website-Verse. He encouraged people to create their own personal website to write, create, share what you like, and to tinker with new technologies.

Your own blog is supposed to be a place where you can make mistakes and learn without pressure. With that in mind, I’m declaring this blog as my soapbox. My space to say what ever I want. My laboratory for experiments in web technologies. My window into my own experience from which I can reflect upon my past, figure out what’s of interest now and navigate to a better future. If I’m lucky, I might engage someone who wishes to share their own thoughts and experiences, and I’ll learn something new.

Rebuilding from Jekyll to Hugo

My first priority was to find good tools for creating a static site. The original experiment was, in part, to use Jekyll to build the site from Markdown files and publish it from GitHub Pages. I was familiar with git, had been using GitHub for years, and Jekyll and GitHub Pages were advertised as a hand-in-glove fit for each other, and they are.

I installed and configured Ruby (Jekyll is written in Ruby, but is not a standalone executable), Bundler to keep Ruby gems up-to-date, Compass to generate CSS from SASS/SCSS, and Jekyll of course, and settled in to learn how to create a blog. After reading a lot of docs, and experimenting a lot with HTML and SCSS, I had a working blog. It was kind of ugly, but it was functional. It had two columns, the left for posts and the right for links to posts by year. As I recall, it took quite a bit of effort to put together the markup, styling, and learn how to use the Liquid Template engine to pull together things like lists of posts by year, month, and day.

At first, the writing and learning experience was delightful. I have a note from March 7, 2016 that says, “Jekyll is really easy to install and use. What takes time is learning enough about its bells and whistles, markdown, HTML, CSS, and Sass to make a blog or website you’re own.”

I had a couple of .bat files to update and launch Jekyll and Compass. The first was _build\start.bat:

  @echo off
  REM Update all the gems and then start Compass and Jekyll
  call bundle update
  SET PROJECT_PATH=%~dp0
  call %PROJECT_PATH%quick-start.bat

The second was quick-start.bat:

  @echo off
  REM Start Compass and Jekyll without updating gems
  start bundle exec compass watch

  REM Give compass a few seconds to start before launching jekyll.
  @ping 192.0.2.2 -n 1 -w 4000 > nul

  start bundle exec jekyll s --port 4000

All I had to do was run build\start.bat and open a browser to http://localhost:4000. Each time I edited and saved a file, the view in the browser would update after a second or so. Blogging life was good.

Later came a series of annoyances. It started with Compass crashing a lot when editing scss files. Compass was valuable for its math library. I found the exponentiation and logarithm functions most valuable. I used them for calculating the luminance of a color and the contrast ratio between two colors.

The crashes got so annoying that I stopped using Compass in September of 2016. Compass wasn’t being maintained anymore, and I wasn’t about to start learning Ruby just to be able to write a blog. Fortunately, I learned that Jekyll had a built-in sass compiler. I also figured out how to write the color luminance and contrast ratio functions in pure sass, so I didn’t need Compass’ math library either. I don’t use scss currently. I guess (hope) luminance and contrast ratios are built-in functions by now, but in case they aren’t, here’s a gist with those functions and a few others. Feel free to use it as you will.

In October of 2016, the --watch option being disabled for Windows in version 3.3.0 of Jekyll. That option was originally intended for BASH on Windows, but was extended to the default cmd.exe and PowerShell. I found a fix among the comments in Jekyll issue 5462. The comments said the underlying problem in BASH on Windows has been fixed, so --watch will be enabled in a later release. A temporary fix was to open vendor\bundle\gems\jekyll-3.3.0\lib\jekyll\commands\build.rb and replace the line if Utils::Platforms.windows? with unless Utils::Platforms.windows?.

I wasn’t comfortable at all with manually modifying gem files. I didn’t know Ruby, and those files were managed by Bundler. It just seemed like a bad idea. Still, I was still able to use live-reload and see the effects of edits on HTML and SCSS a few seconds after they happened. Fast feedback loops are truly invaluable when learning anything new.

My last post was in November of 2016 after the US presidential election. I don’t remember exactly why I stopped, but part of the reason was that Jekyll was slow, and it felt like the Windows implementation was treated as a second-class citizen.

Besides blogging, I was also using it as a note taking system. I loved that I could write a markdown file, and Jekyll could turn my notes into a nice looking web page. However, when I had a few dozen notes it would take several seconds to see edits appear in a browser. I wasn’t very good with using HTML and CSS, so I became frustrated as I tried to use my notes repository to experiment with layout and design. The feedback loop was irritatingly slow.

I spent months looking into other solutions. I read about Luhmann’s Zettelkasten (the original blog is gone, but the article is here on the Way Back Machine) for organizing my files, and Sphinx, the tool used by the Python programming language for generating all of their documentation.

Sphinx turned out to be a bit of a rabbit hole, a good one. The source documents for Sphinx are written in reStructuredText (rST). I was curious why that file format was chosen over Markdown or plain text. While rST has its issues and limitations, it is a much more rich markup language than Markdown. Also, Sphinx is a programmable environment. If it doesn’t have a directive you need, there’s a way to define new ones.

The possibilities just wowed me. I ported all my old notes from Markdown to rST and dove into Sphinx, directives, and roles. I spent a lot of time learning, writing, and even played around with CSS a little bit. Even so, Sphinx presented a kind of impedance mismatch between what I was trying to do - just have a tool that builds nice web pages from my notes - and keeping a Python environment up-to-date as I wanted to try new features added to later releases of Sphinx.

My success with Sphinx for notes left me with a desire to blog again. I was probably suffering from myopia, but at the time I didn’t realize that Jekyll is not necessary to build GitHub pages, and I didn’t know how or if Sphinx could be configured to work with GitHub pages.

Well, I spent a lot of time in 2018 learning Go for a new project at work. It’s a very nice programming language. Late in 2018, I came across Hugo. It looked interesting, and what do you know, it’s written in Go! I had to give it a try. I figured even if it’s not to my liking, I can look at the source code, and learn something more about Go.

It turns out that not only is Hugo useful, it is fast, not too hard to integrate MathJax for nice looking equations, has a powerful template language, and it is even possible to write pages in rST - though it requires integration with the Python script rst2html5.

That’s enough for now. I’ll cover my adventures using Hugo in a future post.

A Dangerous Spectacle

Wed, 09 Nov 2016 00:00:00 +0000

I am truly saddened by the outcome of the 2016 presidential election.

I woke up this morning to find that Donald Trump is our president elect. I feel really awful about it.

Our national anthem declares America as “the land of the free and the home of the brave.” While we don’t always live up to that ideal, it’s something we strive for. It’s something we are all proud of.

We’ve elected as our next president a person who bullies people. He’s denigrated those with disabilities. He abuses women. He spreads fear and hate based on race and religion, and wraps it in spectacle.

I hoped more people were unwilling to overlook the pain, suffering and fear he spreads and see him for what he is - a hateful, dangerous person who cares for nothing but himself. Instead, he will become our next leader. Good luck to us all.

Serving a Blog

Sun, 04 Sep 2016 00:00:00 +0000

I want a blog where I control the design and layout. I want to be able to change the way it works and appears so I can experiment with various ideas, learn by attempting to replicate other designs and see what happens.

I’ve tried CMS solutions running on Linux-based servers. One of the first ones I tried many years ago was Apache Cocoon. I was enticed by how flexible and programmable it was with its pipeline architecture. It seemed anything was possible. Ultimately, trying to program using XML and XSLT, and configure Java servlets proved to be too complicated. The languages and processes needed to keep the site up and running were too far removed from those for adding content.

The mechanics of site maintenance took too much time away from just plain writing. I didn’t realize that was the problem at the time, so I allowed myself to be lured into other complex solutions. I tried Plone for a short while, but got tired of configuration bugs (the bugs were probably mine, and I was too impatient to figure out how to make Plone work correctly). I had a short run with web2py and a long one with Drupal 5 and 6. Drupal was fun and I did get it to work fairly well. The only real problem was keeping up with patches for the core system as well as all of the plug-ins. They made it relatively easy to do, but it was another time consuming annoyance.

I ran each of these CMS solutions from a Windows box at home and a dynamic DNS provider. Besides being cheap and rickety, there were always quirks running on Windows as most of these systems were designed and tested on Linux. Windows support varied from very well to an after thought.

Simplicity

I’ve come around to thinking that if I’m going to have a corner of the web to express my thoughts, the tooling and maintenance of it should be as simple and low-overhead as possible. Static sites are very appealing in this respect. Post a little content wrapped in some HTML, give it some style with CSS and it’s done.

Still, nothing is ever quite simple when it comes to digital information. I’m always concerned about having copies of data to prevent loss. I’d like be able to look back and see how I got to where I am today - especially when it comes to reverting changes that, upon reflection, weren’t so good. I also don’t have a lot of spare cash to spend, so most cloud servers are out of the questions.

I did use a small Digital Ocean droplet for a while - only $5.00 USD/month. It addressed the cash issue very well, and I used Fossil SCM for version control. I also have a server running FreeNAS where I backup all my data.

To build anything on a computer, you need good tools. For static site generation, I settled on Jekyll, a static site generator that turns Markdown, HTML and CSS (and even Sass into a website. I made changes locally, and ran Jekyll to see the results. When I was satisfied, I’d check-in the changes to Fossil and copy, via SSH, the _site folder to my droplet where nginx would serve the content. I thought it was as simple as it could get.

It does get more simple. GitHub is an amazing site that lets anyone make a git repository. If you don’t mind it being publicly available, then their service is free! They also make it easy, with Jekyll, to create a personal website. I no longer have to be (directly) concerned with web server configuration and security. That’s offloaded to the experts at GitHub. Also, uploading changes to my site is easier. All I have to do to update my blog is to commit the changes to my local repository and execute git push origin.

The Remaining Complexity

At this stage, I can’t imagine how it could be easier (and certainly it can’t be cheaper). The only complexity left is figuring out how to make my blog appear pleasing to the eye. That’s a matter of laying out some HTML, writing content marked up with Github Flavored Markdown and using CSS and SCSS to give it some style.

I originally had a complex mess inherited from previous attempts at making a personal site with varying goals. I’ve now pared it down to something much easier to manage. I’ll post again about my current, more modest goals, what inspired the current design and how I’m going about the process of reaching them.

References

Fixing the Width

Thu, 10 Mar 2016 00:00:00 +0000

What an ugly, fragile blog.

All I wanted to do was make the page a little wider. Suddenly the widths of the left and right columns were varying in size depending on content. Headings were crazy sizes. Both headings and paragraphs had awkward line spacing. While syntax highlighting is a great feature, poor color choices make code very hard to read. It was a mess.

I spent a lot of time trying to figure out what was going wrong. One of the problems was using flex-grow: 1; for the left column and width: auto; on the right. These settings left too many decisions up to the browser. I now calculate the column widths and margins based on the width of the whole body. The code also floats the two columns to the left and right, respectively. It may not be the best solution, but it will do until I learn how to responsive grid systems work.

I also got rid of jQuery and some other JavaScript. It was a holdover from another website I created a while ago. The only JavaScript remaining is for MathJax, which I plan to use for - what else? - math!

\[ \begin{bmatrix} a & b & c & d \\ e & f & g & h \\ i & j & k & l \\ m & n & o & p \end{bmatrix} \times \begin{bmatrix} x \\ y \\ z \\ w \end{bmatrix} = \begin{bmatrix} ax + by + cz +dw \\ ex + fy + gz + hw \\ ix + jy + kz +lw \\ mx + ny + oz + pw \end{bmatrix} \]

This blog is still quite ugly, but I’m feeling better about it after putting in a couple of days work to make the width behave the way I want it to. Now to learn more about layout design, typography, Sass, CSS and how best to put to use semantic HTML5 tags, like <main>, <aside>, <header> and others.

2019.07.29 Edit: typos 2019.08.07 Edit: tags

The Pursuit of Happiness Gels in the Imagination

Wed, 09 Mar 2016 00:00:00 +0000

Imagination is good, but action needs to be taken in the real world.

I wonder if the reason I have so many non-fiction books waiting to be read is that I’m looking for the thrill of living in a world of fun and self-fulfillment, but I’m not willing to create it. I have books on game programming, drawing, sketching, animation, project management, time management, organizing, clutter reduction, investing and other topics. Even among those I have read, they don’t do me much good unless I act upon them.

The Wondermark comic No. 1204, The Cargo Cult of Adulthood, started me thinking about imagination versus creating and doing real things. It contrasts buying stuff with buying experiences. The chain of thought starts with buying a movie ticket to get a few hours of being in a dramatized world. Similarly, buying a lottery ticket buys a few days of dreaming there’s a chance of becoming a millionaire. The thought continues with the notion that buying stuff can transport us into a fun, but imaginary world. Things like workout clothes, cookbooks, and self-help stuff, says David Malki, the author of Wondermark, are the tickets of admission to the fun imaginary worlds of being fit, eating well and having a good life.

He goes on to shortcut the whole process by proposing we skip shopping and just pay someone to give us a daily pep talks about how fun our lives really are, but that’s beside the point. These things we buy are just fodder for the imagination unless some action is taken in the real world. Create something new, or clean up something old to make it useful and accessible and then actually put it to use. Put on the workout clothes and exercise. Follow the lessons in that book about sketching, put pencil to paper and practice.

First efforts will probably stink. Exercising is difficult in the beginning. The first sketch will be awful. It’s all about sticking with it. Improvement will happen.

Maybe this post is just me giving myself a pep talk (it’s certainly cheaper than paying someone else to do it), but I have things to do, and I feel more like getting them done.

I created this blog to become a better writer, quell demons of doubt and to workout ideas. I titled it “Dream, Sketch, Code”, because I have a lot of half-baked ideas, think about and create software, and I want to get better at sketching and drawing. Besides being a relaxing activity, I’d like to draw well enough that I can use sketches to better describe my ideas.

A Quick Note on Python

Mon, 04 Jan 2016 00:00:00 +0000

I saw an amusing Python tutorial.

I have been meaning to learn Python for a while now. While searching for other things, I came across an amusingly titled video on YouTube, Python Programming: Learn Python in One Video, by Derek Banas.

I had no illusions it was going to cover the language in any depth. Still, it is only about 45 minutes long, so I decided to take a look. It actually hit a lot of highlights and was a nice overview of the language.

For example, it introduces the built-in operators and data types. It goes over the for and while loops. It also covers several other programming concepts. If you’ve never seen Python before, this video is worth a look.

I recently picked up a copy of Steven Skiena’s “Programming Challenges” and started going through the problems. To see if I learned anything from the video, I tried coding the first puzzle, the 3n+1 problem. The link is to the puzzle on the UVa Online Judge, where one can submit code in C, C++, Java or Pascal. Sadly, they don’t support Python. Nevertheless, here’s my version in Python:

import sys

# Execute: "python p100.py < data" where 'data' is the input file, two integers per line.
def cycle_length(n):
    result = 1

    while (n != 1):
        if (n % 2):
            # n is odd, so multiply by 3 and add 1
            n = 3 * n + 1
        else:
            # n is even, so divide by 2
            n /= 2

        result += 1

    return result

# Each line of input consists of two integers
def main():
    for line in sys.stdin:
        input_list = line.split()
        input_list = list(map(int, input_list))

        # reset the max cycle length for each line of input
        max_cycle_length = 0

        # Make a copy of the original list for output
        original_list = list(input_list)
        if input_list[0] > input_list[1]:
            x = input_list[0]
            input_list[0] = input_list[1]
            input_list[1] = x

        for n in range(input_list[0], input_list[1]+1):
            length = cycle_length(n)
            if length > max_cycle_length:
                max_cycle_length = length

        print("%d %d %d" % (original_list[0], original_list[1], max_cycle_length))

if __name__ == "__main__":
    main()

I think the only thing here that wasn’t covered in the video is reading from stdin.

A Blog on GitHub

Wed, 30 Dec 2015 00:00:00 +0000

What do you really need to know to setup a blog on GitHub?

I want a platform to write about software development, design patterns, and anything else that came to mind. GitHub user pages looked like a good place to start. I’ve toyed with Jekyll and Compass in the past, so I thought it would be easy to setup. For the most part, it is. Along the way, I discovered a few stumbling blocks that I will share.

Initial Setup

The initial steps (create a GitHub repository, install and configure Jekyll) were easy. The first stumbling block I ran into was ensuring the versions of my Ruby gems and my Jekyll configuration were consistent with what GitHub supported. GitHub doesn’t yet support Jekyll v3, which is what I have installed on my desktop.

Fortunately they provide excellent documentation. The most important part is to add gem 'github-pages' to your Gemfile. By running bundle install, you get Jekyll and all the dependencies in the correct version to be compatible with Jekyll on GitHub.

I also installed Compass. It’s a nice tool that watches the files in the repository for changes, and recompiles the .scss files as needed. GitHub doesn’t use Compass, so you have to commit the CSS files it generates to the repository.

Creating a Blog

Reading and following the documentation for GitHub pages, Jekyll and Compass will establish all of the scaffolding you need to start a blog. It will not provide any scaffolding for the structure and contents of the blog itself.

I thought I’d be able to make a cool blog with responsive CSS so it would be readable on a variety of screen sizes. I learned quickly to keep things simple. I just don’t know enough CSS right now to make that happen. I stumbled upon (Googled for “html5 sidebar layout”) one good tutorial (which used to be at http://multimedia.journalism.berkeley.edu/tutorials/css-layout/, but still exists on the Way Back machine). It enabled me to create the basic structure for this blog. Warning: I had to insert p script { display: block;} to display the code blocks. Each code block is wrapped in a <script> element and is written in an XML <![CDATA[...]]> block. The user agent stylesheet sets script {display: none; }, so I couldn’t see the code.

I made a few adjustments to the styling and HTML to suit my taste. One thing I was delighted to learn was how to make the content area and the sidebar the same height. The tutorial presented a solution in JavaScript, but that didn’t work for posts. The disqus comment block wasn’t included in the calculation.

The main content area and the sidebar are both included in div section with the ID boxes (<div id="boxes">). All I had to do was style the div with display: flex;. Here’s the code and comment from my stylesheet.

/* Using display: flex; to make the sidebar column the same length as the main content.
   See: http://tutorialzine.com/2014/10/easiest-way-equal-height-sidebar/ for details.
   */
#boxes {
    display: flex;
}

More To Do

There’s a lot of work that goes into making a web page look presentable. At the very least, text should be readable, sections should be well aligned, and the color theme should be pleasing to the eye. There is a lot to fiddle with, but I think I’ve done an okay job for now. I glad I have a place to write down ideas, write about projects I want to pursue and share some thoughts in general.