Literate programming is much more than just commenting code

• leo-editor

  16 1,451 10.0 Python

  Leo is an Outliner, Editor, IDE and PIM written in 100% Python.

  

• srcweave

  1 76 6.4 Common Lisp

  A literate programming system for any language.

I’d like to see a literate programming version of GitHub where the community standardizes around an eminently-readable Markdown-like syntax. srcweave [1] looks like a great start.

[1]: https://github.com/justinmeiners/srcweave

• WorkOS

  workos.com sponsored

  The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.

  

• tanglemd

  1 - -

IMHO the two biggest problems I find with existing tools are that they assume the documentation is the source of truth and that the tangling will leave artifacts in code. Both of these make them poorly suited to the sort of projects that most of us work on, I'm not Knuth writing a dead tree tome but I would like some better ways to add documentation to existing projects and have to integrate with others.

I wrote a PoC of a tangling tool that worked through "virtual" files and had a syntax aware handler, there's enough information that it could possible work with language servers too, but sadly I haven't had time to take things further: https://gitlab.com/lusher/tanglemd

• marginalia

  1 803 6.5 HTML

  Ultra-lightweight literate programming for clojure inspired by docco (by clj-commons)

  

• RawParser

  3 8 0.0 C

  Showing how a grammar driven parser can be implemented

I have started working on a program that can parse Markdown files with fragments of C code and weave those fragments into a C program that can be compiled. For an example input, see https://github.com/FransFaase/RawParser#documentation

• sicmutils

  13 750 0.0 Clojure

  Computer Algebra, Physics and Differential Geometry in Clojure.

  

- multiple stories about the same piece of code, but all with the ability to IMPORT the story as a library

I've been writing sicmutils[0] as a "literate library"; see the automatic differentiation implementation as an example[1].

A talk I gave yesterday at ELS demos a much more powerful host that uses Nextjournal's Clerk to power physics animations, TeX rendering etc, but all derived from a piece of Clojure source that you can pull in as a library, ignoring all of these presentation effects.

Code should perform itself, and it would be great if when people thought "LP" they imagined the full range of media through which that performance could happen.

[0] sicmutils: https://github.com/sicmutils/sicmutils

[1] autodiff namespace: https://github.com/sicmutils/sicmutils/blob/main/src/sicmuti...

[2] Talk code: https://github.com/sritchie/programming-2022

[3] Clerk: https://github.com/nextjournal/clerk

• programming-2022

  3 11 0.0 HTML

  Talks at the <Programming> 2022 Conference in Porto, Portugal

- multiple stories about the same piece of code, but all with the ability to IMPORT the story as a library

I've been writing sicmutils[0] as a "literate library"; see the automatic differentiation implementation as an example[1].

A talk I gave yesterday at ELS demos a much more powerful host that uses Nextjournal's Clerk to power physics animations, TeX rendering etc, but all derived from a piece of Clojure source that you can pull in as a library, ignoring all of these presentation effects.

Code should perform itself, and it would be great if when people thought "LP" they imagined the full range of media through which that performance could happen.

[0] sicmutils: https://github.com/sicmutils/sicmutils

[1] autodiff namespace: https://github.com/sicmutils/sicmutils/blob/main/src/sicmuti...

[2] Talk code: https://github.com/sritchie/programming-2022

[3] Clerk: https://github.com/nextjournal/clerk

• InfluxDB

  www.influxdata.com sponsored

  Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.

  

• clerk

  22 1,692 8.5 Clojure

  ⚡️ Moldable Live Programming for Clojure

  

- multiple stories about the same piece of code, but all with the ability to IMPORT the story as a library

I've been writing sicmutils[0] as a "literate library"; see the automatic differentiation implementation as an example[1].

A talk I gave yesterday at ELS demos a much more powerful host that uses Nextjournal's Clerk to power physics animations, TeX rendering etc, but all derived from a piece of Clojure source that you can pull in as a library, ignoring all of these presentation effects.

Code should perform itself, and it would be great if when people thought "LP" they imagined the full range of media through which that performance could happen.

[0] sicmutils: https://github.com/sicmutils/sicmutils

[1] autodiff namespace: https://github.com/sicmutils/sicmutils/blob/main/src/sicmuti...

[2] Talk code: https://github.com/sritchie/programming-2022

[3] Clerk: https://github.com/nextjournal/clerk

• rust-jmdict

  1 11 0.0 Rust

  Rust library for access to the JMdict

I had an instance of this where I built up a rather contrived data structure over time and ended up putting what is basically a blog post into the repo to explain the history of that data structure: https://github.com/majewsky/rust-jmdict/blob/main/CONTRIBUTI...

• zx

  114 41,571 7.6 JavaScript

  A tool for writing better scripts

  

I am not a big fan of the complex literate programming style involving code-generation which this article talks about.

But I recently discovered that Google's zx [1] scripting utility supports executing scripts in markdown documents and I combined it with httpie [2] and usql [3] for a bit of quick and dirty automation testing and api verification code and it worked out pretty well.

[1] https://github.com/google/zx#markdown-scripts

[2] https://github.com/httpie/httpie

[3] https://github.com/xo/usql

• httpie

  116 31,842 6.6 Python

  🥧 HTTPie CLI — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins & more. (by httpie)

  

I am not a big fan of the complex literate programming style involving code-generation which this article talks about.

But I recently discovered that Google's zx [1] scripting utility supports executing scripts in markdown documents and I combined it with httpie [2] and usql [3] for a bit of quick and dirty automation testing and api verification code and it worked out pretty well.

[1] https://github.com/google/zx#markdown-scripts

[2] https://github.com/httpie/httpie

[3] https://github.com/xo/usql

• usql

  21 8,605 9.0 Go

  Universal command-line interface for SQL databases

  

I am not a big fan of the complex literate programming style involving code-generation which this article talks about.

But I recently discovered that Google's zx [1] scripting utility supports executing scripts in markdown documents and I combined it with httpie [2] and usql [3] for a bit of quick and dirty automation testing and api verification code and it worked out pretty well.

[1] https://github.com/google/zx#markdown-scripts

[2] https://github.com/httpie/httpie

[3] https://github.com/xo/usql

• Redis

  318 64,821 9.7 C

  Redis is an in-memory database that persists on disk. The data model is key-value, but many different kind of values are supported: Strings, Lists, Sets, Sorted Sets, Hashes, Streams, HyperLogLogs, Bitmaps.

  

• pytudes

  100 22,370 7.7 Jupyter Notebook

  Python programs, usually short, of considerable difficulty, to perfect particular skills.

Yes I agree (and share the hope). In fact, earlier today I was thinking about Peter Norvig's "pytudes" (https://github.com/norvig/pytudes) as good examples of literate programming — and they are notebooks. Also, last weekend I picked up some code I had written a few months ago, threw it all away and started writing it in a notebook (Colab) precisely for this "literate programming" reasons.

There's also "nbdev" (https://github.com/fastai/nbdev) which seems like it should be the best of both worlds, but I couldn't quite get it to work.

• nbdev

  45 4,740 6.5 Jupyter Notebook

  Create delightful software with Jupyter Notebooks

  

Yes I agree (and share the hope). In fact, earlier today I was thinking about Peter Norvig's "pytudes" (https://github.com/norvig/pytudes) as good examples of literate programming — and they are notebooks. Also, last weekend I picked up some code I had written a few months ago, threw it all away and started writing it in a notebook (Colab) precisely for this "literate programming" reasons.

There's also "nbdev" (https://github.com/fastai/nbdev) which seems like it should be the best of both worlds, but I couldn't quite get it to work.

• SaaSHub

  www.saashub.com sponsored

  SaaSHub - Software Alternatives and Reviews. SaaSHub helps you find the best software and product alternatives

  

Suggest a related project