Hi all! I am a web developer primarily, but I feel like this is the right place to talk about my literate programming tool and experiments. For those who are not aware of literate programming, it generates production code ideally and documentation from a single source. Ever since I saw this literate programming talk I have been messing with existing literate programming tools. After trying multiple tools, I ended up writing my own tool using python + sphinx + cog + markdown. I am calling it wheel. It can be used for any programming setup, and it generates html documentation using templates and preprocessors that are commonly used in web development.
Links
1. Wheel - literate programming tool with python + sphinx + cog + markdown + jinja.
2. Plannr (beta) - My App - Evernote + twitter. The Code Walkthrough. I use code generation techniques over hylang and sqlite for the backend.
3. Bitrhythm - my live coding app to make techno. Docs.
Why literate programming ? I bet each one of you has a codebase that you can no longer understand. Literate programming completely fixes this. The other solution I can think of is at the text editor level, like leo, but that doesn't have the advantage of using the web. Apart from free-from documentation - hyperlinks, TODO’s and FIXME’s can greatly enhance everyday development. You can also use cog for simple preprocessing to enable and disable simple feature flags and if you are feeling adventurous for doing code generation with python. Here's a project that uses cog for implementing reflection in C++.
How literate programming can help game developers ? Well for that you need to check out this book on physical rendering that won the 2014 Academy Award for Technical Achievement, written using another literate tool noweb. For games, I think code could be organized around levels and design assets could be directly linked to the pages. For handmade hero in particular, I think literate programming would work well alongside the video tutorials.
At this point, I can't go back to writing normal code. Organizing code by files and folders feels too primitive when you have pages, snippets and hyperlinks. I plan to move all my projects to using literate programming in the future. My next project is to develop a small animation tool using three.js. If you guys have a working codebase that you would like to port to literate programming, I would love to try it, but I will need your help.
EDIT:
Link of my 3D animation tool - Virtuator, currently in active development. I want to mention that a literate document can also function as a Game design document. By treating each chapter as a feature, you can document all major design decisions, research and bugs in detail ... which helps a lot in onboarding any programmer/designer/stakeholder to the project.
Links
1. Wheel - literate programming tool with python + sphinx + cog + markdown + jinja.
2. Plannr (beta) - My App - Evernote + twitter. The Code Walkthrough. I use code generation techniques over hylang and sqlite for the backend.
3. Bitrhythm - my live coding app to make techno. Docs.
Why literate programming ? I bet each one of you has a codebase that you can no longer understand. Literate programming completely fixes this. The other solution I can think of is at the text editor level, like leo, but that doesn't have the advantage of using the web. Apart from free-from documentation - hyperlinks, TODO’s and FIXME’s can greatly enhance everyday development. You can also use cog for simple preprocessing to enable and disable simple feature flags and if you are feeling adventurous for doing code generation with python. Here's a project that uses cog for implementing reflection in C++.
How literate programming can help game developers ? Well for that you need to check out this book on physical rendering that won the 2014 Academy Award for Technical Achievement, written using another literate tool noweb. For games, I think code could be organized around levels and design assets could be directly linked to the pages. For handmade hero in particular, I think literate programming would work well alongside the video tutorials.
At this point, I can't go back to writing normal code. Organizing code by files and folders feels too primitive when you have pages, snippets and hyperlinks. I plan to move all my projects to using literate programming in the future. My next project is to develop a small animation tool using three.js. If you guys have a working codebase that you would like to port to literate programming, I would love to try it, but I will need your help.
EDIT:
Link of my 3D animation tool - Virtuator, currently in active development. I want to mention that a literate document can also function as a Game design document. By treating each chapter as a feature, you can document all major design decisions, research and bugs in detail ... which helps a lot in onboarding any programmer/designer/stakeholder to the project.
Edited by xyzzy
on
The biggest challenge with letting developers use code generation everywhere is that each developer will end up with their own dialect of the language, like libraries in C++. To be beginner friendly, one has to guide the developer into something that is always safe, modular and ready for collaboration with others.
The first version of my language had a hard-coded generator for creating tables and then one could write code to interpret it as state machines.
https://dawoodoz.com/steamroller.html
An experimental version allows using the name of language constructs as identifiers so that multiple language features can be safely combined in the same module even if they are picked from different developers working separately. One can then import the language definitions of if-statements, for-loops, enumerations, structures, tables, et cetera.
The first version of my language had a hard-coded generator for creating tables and then one could write code to interpret it as state machines.
https://dawoodoz.com/steamroller.html
An experimental version allows using the name of language constructs as identifiers so that multiple language features can be safely combined in the same module even if they are picked from different developers working separately. One can then import the language definitions of if-statements, for-loops, enumerations, structures, tables, et cetera.
Dawoodoz
The biggest challenge with letting developers use code generation everywhere is that each developer will end up with their own dialect of the language, like libraries in C++. To be beginner friendly, one has to guide the developer into something that is always safe, modular and ready for collaboration with others.
Definitely guilty of it. I already have a lisp dialect that is increasingly looking like newtonscript. Generative programming is so much fun. I like the tables approach you have taken. Arguably the most popular use of code generation is generating state machine code from action tables, like the ragel compiler. Dialecting increases learning time, but hopefully it increases clarity and actually aids in collaboration as it makes communcationg complex ideas cheaper.
Inspired by Cello which makes C a pseudo scripting language, I am working on an experimental C dialect which will have prototype oriented programming like ES5, generics and namespaces. I think the cog preprocessor, which I (ab)used for literate programming, as a replacement for cpp can make dialecting C more maintainable. It gives you the power of python for preprocessing, which means you can make use of C parsers written in python and give better error messages.
Edited by xyzzy
on