Skip to main content

An Approach to Illiterate Programming: doc-code-merge

It's very common to embed code examples in technical documentation. However, doing so is kind of painful. First of all, the environment you use to edit the documentation may not be the same as the environment you use to write code. For instance, I generally use Dart Editor to write Dart code, but I use Sublime Text 2 to edit documentation written in HTML or Markdown. Secondly, it's difficult to run unit tests or use dart_analyzer if the code is trapped in documentation. This is a big problem for us on the Dart project because we move pretty quickly, and we want to make sure our documentation is always 100% correct. I've created a tool called doc-code-merge to solve this problem.

doc-code-merge is the opposite of what Donald Knuth labelled Literate Programming. doc-code-merge lets you write your documentation and your code examples completely separately. When you run doc_code_merge.dart, it makes a copy of your documentation with all the examples merged in. The Pragmatic Programmers mentioned using a similar tool when writing The Pragmatic Programmer: From Journeyman to Master, so the idea has probably been around for a while.
Using doc-code-merge is easy. Start by writing some documentation such as:
Then, write some code such as:
Now, run doc_code_merge.dart:
This results in:
Easy peasy! doc-code-merge automatically handles things like indenting code blocks when generating Markdown and HTML escaping code when generating HTML.

Although doc-code-merge is written in Dart, it'll work with almost any programming language and with almost any type of documentation as long as the documentation is written in text such as HTML or Markdown. We're hoping to make use of it for the Dart web site, dartlang.org, and for our book on Dart, Dart: Up and Running.

If you're interested in using doc-code-merge, check out the README. As always, we invite you to join the Dart mailing list and ask questions on Stack Overflow.

Popular posts from this blog

Dart in 2016: The fastest growing programming language at Google, 2nd fastest growing in TIOBE Index

Dart was the fastest growing programming language at Google in 2016 with millions of lines of code written. It also made it to TIOBE Index Top 20 this month (see TIOBE's methodology).

It takes time to build something as ambitious as Dart and, in some ways, Dart is still in its infancy. But we're glad the hard work is starting to pay off.

Many thanks to our amazing community!

We're going to celebrate by ... releasing 1.22 next week (as per our usual 6 week release schedule).

AngularDart is going all Dart

Until now, the multiple language flavors of Angular 2 were written as TypeScript source, and then automatically compiled to both JavaScript and Dart. We're happy to announce that we’re splitting the Angular 2 codebase into two flavors – a Dart version and a TypeScript/JavaScript version – and creating a dedicated AngularDart team.

This is amazing news for Dart developers because:

The framework will feel more like idiomatic Dart.It will make use of Dart features that couldn't work with the TypeScript flavor. It will be faster.
This is equally great news for our TypeScript and JavaScript developers, by the way. Cleaner API, performance gains, easier contributions. Read more on the Angular blog.

Angular 2 for Dart is used by many teams at Google. Most famously by the AdWords team, but many other Google teams build large, mobile-friendly web apps. Some of the top requests from these teams were: make the API feel like Dart, provide a faster edit-refresh cycle, and improve applicat…

The new AdWords UI uses Dart — we asked why

Google just announced a re-designed AdWords experience. In case you’re not familiar with AdWords: businesses use it to advertise on google.com and partner websites. Advertising makes up majority of Google’s revenue, so when Google decides to completely redo the customer-facing front end to it, it’s a big deal. The Dart team is proud to say that this new front end is built with Dart and Angular 2. Whenever you asked us whether Google is ‘even using Dart for anything,’ this is what we had in mind but couldn’t say aloud. Until now. We asked Joshy Joseph, the primary technical lead on the project, some questions. Joshy is focusing on things like infrastructure, application latency and development velocity, so he’s the right person to ask about Dart.Q: What exactly did we launch on Monday?It’s a complete redesign of the AdWords customer experience that is rolling out slowly as a test to a small initial set of advertisers. The most noticeable thing is probably the Material Design look and f…