Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Noweb – A Simple, Extensible Tool for Literate Programming

cs.tufts.edu

Post reply on HN
Print view View original

41–50 of 54 posts

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#41

Post by someguydave »

akkartik wrote: post #29
someguydave wrote: post #25

Earlier quoted context omitted.

Thanks for your comment. Are you aware of a literate programming tool that primarily uses tags in source files to link with documentation in txt files? I guess I am thinking one could tangle the source with docs to produce the documentation, while the source is passed to the compiler unchanged.

https://github.com/nickpascucci/verso works like this. There's a syntax for creating tags in source files, and exposition for tags lives in a separate file.

yeah exactly, thank you.

I found that the leo editor does this too but I believe you must used the gui to tangle/weave, I would prefer cli for automation.

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#42

Post by stevekemp »

kmstout wrote: post #39
sidpatil wrote: post #3

Earlier quoted context omitted.

Obligatory shilling of Org-babel, for those using Emacs and Org-mode: https://orgmode.org/worg/org-contrib/babel/

I've been using Org for a little over a year, and it's actually quite nice. To support a blog post last year ( https://reindeereffect.github.io/2020/05/05/index.html ) I did my own quick and dirty rendition of chunk labels, chunk chain navigation, and clickable references. Lately I've built a faster, mostly drop-in replacement for org-babel-tangle (that doesn't unnecessarily clobber files that haven't changed); and I…

I keep meaning to experiment with bable/tangle in Emacs.

I setup a simple literate configuration of my init file via markdown, which worked out really well, but doing it "properly" in org-mode would be a nice evolution.

With markdown I just search for code-blocks, write them all sequentially to a temporary buffer and evaluate once done. So it is very simplistic, but also being able to write and group things is useful:

https://github.com/skx/dotfiles/blob/master/.emacs.d/init.md

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#43

Post by froh »

kmstout wrote: post #40

Required reading for anyone who wants to extend Noweb to do new things is "The noweb Hacker's Guide": http://www.literateprogramming.com/noweb_hacker.pdf This came in handy when I wanted syntax highlighting in a woven document.

noweb had two brilliant and one not so far sighted decision made.

The first plus was, as you point out, the extensibility of noweb, the pipeline architecture, which transforms the literate input into a documented plain text token stream, then does token stream transformation where you can insert your own transformations, like indexing, syntax highlighting, macro expansions if you wished, and then it reassembles the transformed token stream into output documents.

the other brilliant idea was to go for a minimalistic literate syntax and be language agnostic, for both the markup and the programming language.

This design decision was a focus on the absolute bare minimum, the gist of literate programming, and it still was open to all magic via user plug ins.

This decision also made noweb trivial to learn.

However. How noweb then chose to move to "icon" as scripting and extension language escapes me.

In my book, that was the design decision that killed it. And the rewrite to noweb3, lua based, remained in eternal 'beta'.

and LP as a whole always struggled with IDE / editor support.

literate programming as a discipline could resurrect with the advent of language server protocol. that might make literate programming accessible to contemporary IDEs again.

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#44

Post by HerrMonnezza »

I have used Noweb a few years ago [^1] for a small Python program; there were two major issues with it, from my PoV:

- I had to take care of writing each Python code chunk with the amount of indentation appropriate for where it had to end up, since Noweb does (did?) not respect relative indentation of chunks when tangling.

- Debugging the resulting script was more painful than plain Python sources, as all the debugging info (line numbers, etc.) referred to the tangled code and not to the actual noweb source file I was editing.

[^1]: Looking at the website, it doesn't seem to have changed much since then.

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#45

Post by HerrMonnezza »

Literate programming seems to becoming popular in the R community due to KnitR and Rmarkdown. This seems to have sparked a few similar-working tools with possibly broader scope and adoption. In my bookmarks I find:

- knot [1]: tangles source code from a text file formatted using plain markdown syntax, can use any markdown converter for weaving into a printable document

- snarl [2]: extends markdown code blocks with syntax used for tangling, its "weave" steps just removes the additional syntax and outputs plain markdown

- pylit [3] [4]: a bidirectional converter: code to formatted text and back. Uses reST for formatting, and preserves line numbers which is useful when debugging. Not an LP tool strictly, as it doesn't define/rearrange code blocks so you have to write your script in the order the compiler wants it, not in the order that would make the best exposition.

Both seem to preserve relative indentation of chunks, so would be useful for Python too.

[1]: https://github.com/mqsoh/knot [2]: https://blog.oddbit.com/post/2020-01-15-snarl-a-tool-for-lit... [3]: https://github.com/gmilde/PyLit [4]: https://github.com/slott56/PyLit-3

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#46

Post by chriswarbo »

mmcdermott wrote: post #2

Literate Programming is one of those ideas I keep coming to. There is an idea there that touches on something I find to be true about software development, namely that the communication of an idea to other humans is the most critical piece. There is a similar idea in Naur's paper "Programming as Theory Building." That said, I've never loved the LaTeX-centric nature of most tools. I don't like heavier markup systems w…

I use a couple of Pandoc scripts to run code during the render of my Web site: http://chriswarbo.net/projects/activecode

I originally tried Emacs org-mode babel, but it didn't really fit the 'batch pipeline' flow I wanted.

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#47

Post by kmstout »

someguydave wrote: post #25
kragen wrote: post #19

(BTW, Norman's server seems to be suffering under the load; https://web.archive.org/web/20210223015500/https://www.cs.tu... has your (Way)Back if you're suffering problems in accessing it.) I've been interested in literate programming for a long time; for my self-bootstrapping PEG parser https://github.com/kragen/peg-bootstrap/blob/master/peg.md I wrote my own noweb-like system called HandAxeWeb in Lua (5.x) https://…

Thanks for your comment. Are you aware of a literate programming tool that primarily uses tags in source files to link with documentation in txt files? I guess I am thinking one could tangle the source with docs to produce the documentation, while the source is passed to the compiler unchanged.

There's a variation called "elucidative programming" [1] wherein the source is marked with "anchors" that the documentation can reference. Since source code lives in traditional source files, all the regular development infrastructure continues to work. When the source/documentation bundle is processed, the output is a two-pane coordinated view of code and discussion.

[1] http://people.cs.aau.dk/~normark/elucidative-programming/

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#48

Post by fjfaase »

qbasic_forever wrote: post #12
fjfaase wrote: post #5

I am working on a tool, which can take a collection of MarkDown files with fragments of C code, and can combine these into a single C file, where all fragments are placed in an order, such that they can be compiled. Because defines can change the meaning of code depending where you place them, there are some restrictions on the input files. An example of the type of input file I have in mind, is given at https://gith…

Check out lit.sh, it's a super simple shell script that does what you're after: https://github.com/vijithassar/lit It's basically a one way markdown to commented source converter. One really slick thing is that since it just comments out the markdown you lose no information about line numbers and can interpret errors from your compiler, etc. with ease (something which is almost impossible with more complex literate p…

I would like to do a little more than this, as this script would still require you to enter the code fragments in an order in which they can be compiled. I also would like to use ellipses ('...') to allow to extend the definition of types and initialization functions. One of the ideas of LP is that you can present your code fragments in a non-linear fashion, explaining the code from inside-out and/or to delay the implementation details till the end. The problem with keeping the lines in sync, can also achieved by adding #line statements in the generated code.

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#49

Post by fjfaase »

nerdponx wrote: post #36
fjfaase wrote: post #5

I am working on a tool, which can take a collection of MarkDown files with fragments of C code, and can combine these into a single C file, where all fragments are placed in an order, such that they can be compiled. Because defines can change the meaning of code depending where you place them, there are some restrictions on the input files. An example of the type of input file I have in mind, is given at https://gith…

This sounds a lot like the R Markdown format. https://rmarkdown.rstudio.com/articles_intro.html

I understand that R Markdown format is not similar to the GitHub MarkDown format. (Correct me if I am mistaken.) I would like to use the basis format of GitHub, also because it compatible with the github.io documentation websites.

Re: Noweb – A Simple, Extensible Tool for Literate Programming

#50

Post by thyrsus »

froh wrote: post #43
kmstout wrote: post #40

Required reading for anyone who wants to extend Noweb to do new things is "The noweb Hacker's Guide": http://www.literateprogramming.com/noweb_hacker.pdf This came in handy when I wanted syntax highlighting in a woven document.

noweb had two brilliant and one not so far sighted decision made. The first plus was, as you point out, the extensibility of noweb, the pipeline architecture, which transforms the literate input into a documented plain text token stream, then does token stream transformation where you can insert your own transformations, like indexing, syntax highlighting, macro expansions if you wished, and then it reassembles the t…

I enjoyed the ideas and clarity of icon, but I've never had a colleague who would invest the time in learning it. The bus factor is larger when the language barrier is high. The small community is reflected in icon's sparse ecosystem.
Post reply on HN