3 ms·

It doesn't really sound like the same thing I'm talking about, to be honest. And I find the idea of a tool that automatically rewrites machine readable code in

It doesn't really sound like the same thing I'm talking about, to be honest. And I find the idea of a tool that automatically rewrites machine readable code into a natural language to be of dubious value beyond use cases where someone is first picking up the language. Similar to those tools that exist to generate comments in the form "Set global position" based on a method named setGlobalPosition. It just creates redundancy, and if you're committing the output to your source tree, then it's redundancy in the form of clutter, too. What I'm thinking of, as I said, should shoot for parity with having a half-screen browser window open to the right containing the relevant docs. Only in this instance the docs are "live", and the lookup process is context-sensitive, requiring very little manual effort to perform it. I know that a basic attempt at something bearing minimal similarity is available in most editors that try to implement Intellisense, but generally I find the helpfulness of the small popup in most implementations to be limited to helping you get the method signature right, and not much else. One of the nice side effect of the design I'm talking about would be a system that encourages keeping the docs up-to-date and useful as much as it encourage their consumption.

mikekchar 11y ago
I think you might be misunderstanding what "literate programming" is. It's a method of programming where you embed code inside English language documentation. The idea is to be able to present the documentation in a way that is useful to a human, but have the compiler extract the computer code and reassemble it in the way that the computer would like to see it. Literate coffeescript does not have the tools for extracting and rearranging text, so it's really just a way of embedding markdown text into your coffeescript code. However, it's useful because you can embed html hyperlinks which can do things like enable you to click to get to the tests, etc. Here is a small example of something I wrote in literate coffeescript: https://github.com/ygt-mikekchar/react-maybe-matchers/blob/master/src/ReactMaybeMatchers.litcoffee#react-maybe-matchers-for-jasmine https://github.com/ygt-mikekchar/react-maybe-matchers/blob/m... Now imagine that you have the English text on the left hand side and the source code on the right hand side. Ideally you would have tools that would allow you to make the hyperlinks (possibly automatically) and keep the documentation in sync. Such tools do not yet exist at the moment, unfortunately. Edit: I should admit to being embarrassed about my fluent interface abuse in this code ;-)
- carussell 11y ago
  Sorry. I'm familiar with literate programming, but I mistook one of your statements: > formats the output in a similar way - you have the english text in a pane on the left and the code in a pane on the right ... to be a description of a system that didn't really sound like what I had in mind, and didn't really sound like literate programming, either. After reading this comment and a reread of your original one, I understand I was wrong in my interpretation of what you meant. Sorry about that.

mikekchar 11y ago

I think you might be misunderstanding what "literate programming" is. It's a method of programming where you embed code inside English language documentation. The idea is to be able to present the documentation in a way that is useful to a human, but have the compiler extract the computer code and reassemble it in the way that the computer would like to see it. Literate coffeescript does not have the tools for extracting and rearranging text, so it's really just a way of embedding markdown text into your coffeescript code. However, it's useful because you can embed html hyperlinks which can do things like enable you to click to get to the tests, etc. Here is a small example of something I wrote in literate coffeescript: https://github.com/ygt-mikekchar/react-maybe-matchers/blob/master/src/ReactMaybeMatchers.litcoffee#react-maybe-matchers-for-jasmine https://github.com/ygt-mikekchar/react-maybe-matchers/blob/m... Now imagine that you have the English text on the left hand side and the source code on the right hand side. Ideally you would have tools that would allow you to make the hyperlinks (possibly automatically) and keep the documentation in sync. Such tools do not yet exist at the moment, unfortunately. Edit: I should admit to being embarrassed about my fluent interface abuse in this code ;-)

carussell 11y ago
Sorry. I'm familiar with literate programming, but I mistook one of your statements: > formats the output in a similar way - you have the english text in a pane on the left and the code in a pane on the right ... to be a description of a system that didn't really sound like what I had in mind, and didn't really sound like literate programming, either. After reading this comment and a reread of your original one, I understand I was wrong in my interpretation of what you meant. Sorry about that.