Literate programming and Ruby

Hey there,

I’ve recently digged into Donald Knuth’s literate programming paradigm.
I
find it really interesting on an academic standpoint, and I from the
papers
I’ve read, the benefits are real (less bugs, easier maintenance, proper
documentation, etc…)

However, most of the articles I’ve read on that matter are from the
90’s.
It seems like there was a lost of momentum in that area.

Is anyone using literate programming tools like Noweb with real life
ruby
projects? I’m curious to know what’s the state of literate programming
in
the ruby community. I’m aware of Rocco which does a wonderful job at
“weaving” source files into literate-programing-style outputs.

On Wed, Nov 16, 2011 at 3:06 PM, Michael S. [email protected]
wrote:

I’ve recently digged into Donald Knuth’s literate programming paradigm. I
find it really interesting on an academic standpoint, and I from the papers
I’ve read, the benefits are real (less bugs, easier maintenance, proper
documentation, etc…)

I am skeptical: if the benefits would be so great I would expect it to
be used much more. Instead, we have Javadoc and doxygen and manage
source code in separate files. The latter is definitively easier to
track in RC systems so my assumption is that the community has somehow
decided that it’s usually better off without literate programming.

However, most of the articles I’ve read on that matter are from the 90’s.
It seems like there was a lost of momentum in that area.

When I was introduced to it in the 90’s it somehow felt old already. :slight_smile:

Is anyone using literate programming tools like Noweb with real life ruby
projects? I’m curious to know what’s the state of literate programming in
the ruby community. I’m aware of Rocco which does a wonderful job at
“weaving” source files into literate-programing-style outputs.

I think RSpec also does a good job at making code readable - while
Ruby code in general is very readable (compared to the $${big
contender};;; in the scripting arena anyway).

Kind regards

robert

I’d encourage you to read this:
http://news.ycombinator.com/item?id=2090007

I believe that this is wonderful idea, especially for
documentation and tutorials. Actually after discovering it I changed the
way of writing comments.

Compared to RDoc - it’s different, RDoc is like a telephone dictionary -
You need a phone, look there, got it and closed it, there’s no stories
there. Literate Programming otherwise allows You to tell a story using
words and code, so in this respect it’s a different.
So, i believe RDoc and Literate Programming aren’t compete, it’s
different tools with different purposes.

For example, a simple tutorial featuring Virtual File System for Ruby
(single united API for accessing Local FS, AWS S3, SFTP, …) written
using Literate Programming approach.
I personally like it more than RDoc.

On Thu, Nov 17, 2011 at 12:16:06AM +0900, Steve K. wrote:

I’d encourage you to read this: http://news.ycombinator.com/item?id=2090007

This, from further down the thread, is also interesting:

http://news.ycombinator.com/item?id=2090843

I use literate programming all the time.

http://rubyworks.github.com/qed

I have learned quite a bit from utilizing it, lessons from which I am
presently using to improve the system.

I’d encourage you to read this:
http://news.ycombinator.com/item?id=2090007

The discussion in here was very informative. For Knuth, a literate
program
is composed of macros. However like it has been said, macros usefulness
can
be questionable in structured programming languages. But if we take out
macros from the equation, then what makes literate programming different
from writing code with comments?

Also, I feel like the overhead for using LP is a little too big. It
requires us to change tools and processes.

Da: Intransition [mailto:[email protected]]
Inviato: mercoled 16 novembre 2011 20:02
A: ruby-talk ML; [email protected]
Cc: ruby-talk ML; [email protected]
Oggetto: Re: Literate programming and Ruby

I use literate programming all the time.

http://rubyworks.github.com/qed

I have learned quite a bit from utilizing it, lessons from which I am
presently using to improve the system.

Caselle da 1GB, trasmetti allegati fino a 3GB e in piu’ IMAP, POP3 e
SMTP autenticato? GRATIS solo con Email.it http://www.email.it/f

Sponsor:

Capodanno a Riccione, Pacchetto Relax: Mezza Pensione + bagno turco +
solarium + massaggio. Wifi e parcheggio gratis. 2 giorni euro 199 a
persona

Clicca qui: http://adv.email.it/cgi-bin/foclick.cgi?mid=11978&d=29-12

-----Messaggio originale-----
Da: Michael S. [mailto:[email protected]]
Inviato: mercoled 16 novembre 2011 15:07
A: ruby-talk ML
Oggetto: Literate programming and Ruby

Hey there,

I’ve recently digged into Donald Knuth’s literate programming paradigm.
I
find it really interesting on an academic standpoint, and I from the
papers
I’ve read, the benefits are real (less bugs, easier maintenance, proper
documentation, etc…)

However, most of the articles I’ve read on that matter are from the
90’s.
It seems like there was a lost of momentum in that area.

Is anyone using literate programming tools like Noweb with real life
ruby
projects? I’m curious to know what’s the state of literate programming
in
the ruby community. I’m aware of Rocco which does a wonderful job at
“weaving” source files into literate-programing-style outputs.


Caselle da 1GB, trasmetti allegati fino a 3GB e in piu’ IMAP, POP3 e
SMTP autenticato? GRATIS solo con Email.it http://www.email.it/f

Sponsor:
Capodanno a Riccione, Pacchetto Relax: Mezza Pensione + bagno turco +
solarium + massaggio. Wifi e parcheggio gratis. 2 giorni euro 199 a
persona
Clicca qui: http://adv.email.it/cgi-bin/foclick.cgi?mid979&d)-12

I have added a pull request to add line directives to Ruby, so it will
be easier to debug litterate Ruby code. If you are intested in using
noweb with Ruby please make a comment in the Ruby IRC
http://irc.lc/freenode/ruby-lang or the feature request
https://bugs.ruby-lang.org/issues/11181 or the pull request
https://github.com/ruby/ruby/pull/911.

For example, a simple tutorial featuring Virtual File System for Ruby
(single united API for accessing Local FS, AWS S3, SFTP, …) written
using Literate Programming approach.
Huh, I forgot to add a link to it :), here it is
http://alexeypetrushin.github.com/vfs

But if we take out
macros from the equation, then what makes literate programming different
from writing code with comments?

  1. If You write a book that contains code, the API of libraries may
    changed over time and Your book will be outdated, with literate
    programming You can “execute” Your book and instantly check that all the
    code there is correct.
  2. It’s like a mental shift, like BDD vs TDD, looks similar but not
    quite the same. With comments You write “how code works” with literate
    programming You describe main idea “why this code exists and why it
    works this way”.

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs