[ANN] Literate programming tools for Go

[Alexander Sychev]

Hi,

I would like to introduce tools support "literate programming"
(http://en.wikipedia.org/wiki/Literate_programming) for Go.
This is an adaptation of the CWEB - the classic tools by Donald E.
Knuth and Silvio Levi, and it is called (surprise!) GOWEB.

The GOWEB can be found here: https://bitbucket.org/santucco/goweb and
can be installed by:
go get bitbucket.org/santucco/goweb
go install bitbucket.org/santucco/goweb/gotangle
go install bitbucket.org/santucco/goweb/goweave

After the installation in a file
$GOPATH/src/bitbucket.org/santucco/goweb/gowebman.pdf can be found
full user manual of the GOWEB system.
--
Best regards,
santucco

[Michael Jones]

Swoon! Thank you!

--
Best regards,
  santucco

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--

Michael T. Jones | Chief Technology Advocate  | m...@google.com |  +1 650-335-5765

[Hugh Myers]

Now if we could only have AI-literate programming. Given vague pseudo code, write out the working program in literate style :)

--hsm

[Kamil Kisiel]

You should be aware there's another active Go project by the name of goweb: https://github.com/stretchrcom/goweb

You may want to consider renaming to avoid confusion.

[Nate Finch]

I consider the name goweb to be extremely confusing for the literate programming tool, since it has nothing to do with what we now call the web.  I understand it is a nod to the original idea, but that idea was published long before most people had even heard of "The Information Superhighway", let alone "the web".  As a developer of 13 years, I had never heard of CWEB, so the name was lost on me, though I have heard of literate programming.

However, it's your thing, and obviously a passion... and perhaps people who are into literate programming will be less confused than me :)

[Michael Jones]

Silvio Levy's CWEB book is on my shelf next to Donald Knuth's WEB book (the programs are called weave and tangle.) There's nothing especially confusing about it to me...

--

You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Alexander Sychev]

About a naming of the GOWEB.
I was ready some of The Gophers will consider the name is like a
conflicting with already existed projects, just have forgotten to
point this out in the announce. But for me it is a kind of tradition.
At the beginning there was a Pascal-version of the system called WEB,
then was developed a C-version of the system - CWEB, also there is a
Fortran version of the system - FWEB. It was impossible for me to call
the project in a different way then the GOWEB :-). Also the GOWEB is
directly derived work from the CWEB.

Additionally, the GOWEB is not a package, just the name of the system
of structured documentation and this name will not appear in any
source code.


--
Best regards,
santucco

[Alexander Sychev]

You are welcome :-)

--
Best regards,
santucco

[Fred Janon]

Great! Thanks. I really think that we should have a fresh look at literate programming (a new generation?) with the new tools, GUI and CPU power, we have nowadays. Maybe programmers would be more inclined to documenting their code if we had an easier and more pleasant way to do it.

Fred

[Michael Jones]

The deeper benefit of Knuth's literate programming approach is that you have a place to say what you mean as you are writing it, in a "literary" form that obeys human communication, can present compound ideas in story order rather than compiler-driven language order, and the like. If you're naturally an explainer, then you'll know the pain of coding something tricky and wondering how to explain it properly when the logic is the result of past, nearby, and future parts of the code. Tangle pulls together remote parts based on semantic links you create so that the reader gets the program in problem-solving order along with descriptions and the compiler gets the program in language-order with any manipulation that is needed. (For Knuth's original Pascal version, there was quite a bit of this though with Go there is not much need of "for the compiler" wrangling.)

Anyway, to my taste the big win is not so much that the documentation is better but that the program is better--you code differently when you can do it in the problem solver's conceptual order. It also solves the "but the error handling boilerplate is too big and obscures my logic" complaint. Read Knuth's original introduction to literate programming for details.

--

You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[John Nagle]

On 2/4/2013 10:05 AM, Michael Jones wrote:
> The deeper benefit of Knuth's literate programming approach is that you

> have a place to say what you mean as you are writing it.

A standard place in Go where the comment for
a function goes would help. One that tools understand. Python has

def addone(n) :
"""
Adds one to n
"""
return(n+1)

Tools then extract that information to provide basic interface
documentation.

Go needs something comparable.

John Nagle

[Dan Kortschak]

Example tests? They exist.

[Patrick Mylund Nielsen]

Go already has that. http://godoc.org/github.com/pmylund/go-cache <- all those descriptions are just comments preceding the function declaration.

[Ian Lance Taylor]

On Mon, Feb 4, 2013 at 12:53 PM, John Nagle <na...@animats.com> wrote:
> On 2/4/2013 10:05 AM, Michael Jones wrote:
>> The deeper benefit of Knuth's literate programming approach is that you
>> have a place to say what you mean as you are writing it.
>
> A standard place in Go where the comment for
> a function goes would help. One that tools understand.

Already done.

http://golang.org/doc/articles/godoc_documenting_go_code.html

Ian