www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - literate programming in D

reply "nikki" <nikkikoole gmail.com> writes:
I've been googling without luck, is there a way to do literate 
programming in D?, similar to how it's done in Coffeescript ?

http://www.coffeescriptlove.com/2013/02/literate-coffeescript.html

basically me writing comments around code and some parser that 
creates styled documents from that (with highlighted source 
code), the current documentation system doesn't export the source 
code.

anybody done this before?
Aug 26 2014
next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
nikki:

 I've been googling without luck, is there a way to do literate 
 programming in D?
D1 had built-in support for literate programming, but it was removed from D2 because it was regarded as not useful enough: http://digitalmars.com/d/1.0/html.html I find literate Haskell programs all the time: gist.github.com/nooodl/e23337d0175ad66ea5f0 Or F# ones: http://tomasp.net/blog/2014/puzzling-fsharp/ Bye, bearophile
Aug 26 2014
parent "nikki" <nikkikoole gmail.com> writes:
Aha, then It's quite safe to assume it won't be coming back I 
guess, then I might need to cook up some homebrew alternative.

thanks for the info
Aug 26 2014
prev sibling next sibling parent reply "bachmeier" <no spam.com> writes:
On Tuesday, 26 August 2014 at 14:55:08 UTC, nikki wrote:
 I've been googling without luck, is there a way to do literate 
 programming in D?, similar to how it's done in Coffeescript ?

 http://www.coffeescriptlove.com/2013/02/literate-coffeescript.html

 basically me writing comments around code and some parser that 
 creates styled documents from that (with highlighted source 
 code), the current documentation system doesn't export the 
 source code.

 anybody done this before?
Would org-mode in Emacs work for you? That's what I use. http://orgmode.org/worg/org-contrib/babel/intro.html
Aug 26 2014
parent reply "nikki" <nikkikoole gmail.com> writes:
That would work very fine, thanks sir!
Aug 26 2014
parent reply "nikki" <nikkikoole gmail.com> writes:
I wasn't too happy about it and I wrote my own little parse 
thingie and have a literate version nice and meta and small and 
sloppy ;)

http://nikkikoole.github.io/docs/dokidokDOC.html

I use it to change my d sourcefile slightly (into valid markdown)
then I use a node module (ghmd) to make sortof sexy html from 
that.
Aug 29 2014
next sibling parent reply "bearophile" <bearophileHUGS lycos.com> writes:
nikki:

 I use it to change my d sourcefile slightly (into valid 
 markdown)
 then I use a node module (ghmd) to make sortof sexy html from 
 that.
Are you going to add popups of the types as in the F# page I have linked? Bye, bearophile
Aug 29 2014
parent "nikki" <nikkikoole gmail.com> writes:
On Friday, 29 August 2014 at 23:41:00 UTC, bearophile wrote:
 nikki:
 Are you going to add popups of the types as in the F# page I 
 have linked?

 Bye,
 bearophile
Now then you could remove the sortof from that sexy
Aug 29 2014
prev sibling parent reply "Philippe Sigaud" <philippe.sigaud gmail.com> writes:
On Sat, Aug 30, 2014 at 1:37 AM, nikki wrote:
 I wasn't too happy about it and I wrote my own little parse 
 thingie and have
 a literate version nice and meta and small and sloppy ;)

 http://nikkikoole.github.io/docs/dokidokDOC.html

 I use it to change my d sourcefile slightly (into valid 
 markdown)
 then I use a node module (ghmd) to make sortof sexy html from 
 that.
Nice. Maybe you could strip the initial whitespaces in the code parts: due to blocks, your code lines are shifting to the right. If you document something that's inside a method inside a class, you're bound to have problems :) Right now, you're documenting your code in a linear way. That's good, but for me, most of LP is based around the idea of naming snippets and referring to them in code, to be explained elsewhere: ``` Here is the main loop: <Main>= void main() { <Initialize Variables> <Precompute State> foreach(i; 0..max) { <Do Computation> } } Before doing all this, we need to initialize the variables: <Initialize Variables>= ... ``` Of course, snippets can refer to other snippets, recursively. Do you have any plan to go there?
Aug 30 2014
next sibling parent "nikki" <nikkikoole gmail.com> writes:
On Friday, 29 August 2014 at 23:41:00 UTC, bearophile wrote:
 nikki:

 I use it to change my d sourcefile slightly (into valid 
 markdown)
 then I use a node module (ghmd) to make sortof sexy html from 
 that.
Are you going to add popups of the types as in the F# page I have linked? Bye, bearophile
Slowly an idea is forming to try to write the whole thing using D and vibe.d instead of a tiny D script and alot of prewritten JS, I think I like the popups and I imagine the data that would go in those popups would be findable at the standard ddoc location for every function class and etc. So I guess I might eventually ;)
Sep 04 2014
prev sibling parent reply "nikki" <nikkikoole gmail.com> writes:
On Saturday, 30 August 2014 at 07:24:39 UTC, Philippe Sigaud 
wrote:
 On Sat, Aug 30, 2014 at 1:37 AM, nikki wrote:
 I wasn't too happy about it and I wrote my own little parse 
 thingie and have
 a literate version nice and meta and small and sloppy ;)

 http://nikkikoole.github.io/docs/dokidokDOC.html

 I use it to change my d sourcefile slightly (into valid 
 markdown)
 then I use a node module (ghmd) to make sortof sexy html from 
 that.
Nice. Maybe you could strip the initial whitespaces in the code parts: due to blocks, your code lines are shifting to the right. If you document something that's inside a method inside a class, you're bound to have problems :) Right now, you're documenting your code in a linear way. That's good, but for me, most of LP is based around the idea of naming snippets and referring to them in code, to be explained elsewhere: ``` Here is the main loop: <Main>= void main() { <Initialize Variables> <Precompute State> foreach(i; 0..max) { <Do Computation> } } Before doing all this, we need to initialize the variables: <Initialize Variables>= ... ``` Of course, snippets can refer to other snippets, recursively. Do you have any plan to go there?
Ah that sounds interesting too! Immediately I start thinking in terms like tidlywiki http://tiddlywiki.com/ or something similar, I guess the emacs way described earlier also would support this. I personally always enjoy reading the readthedocs stuff http://docs.readthedocs.org/en/latest/ is that the sort of stuff you mean? My current usage of the little script is just for small projects which basically are written in one or a few files (I am only just dipping my toe in D ;) ) but I imagine larger projects would need some linking in the docs anyhow so I definitely will look into that eventually.
Sep 04 2014
next sibling parent "nikki" <nikkikoole gmail.com> writes:
I should have read your post more carefully, the 'tagging' in the 
code is not really what I am after, I want the file including the 
documentation to just be a valid d file, does'nt mean however 
that there aren't ways of solving the issue without such precise 
tagging I guess
Sep 04 2014
prev sibling parent Philippe Sigaud via Digitalmars-d-learn writes:
 Ah that sounds interesting too! Immediately I start thinking in terms like
 tidlywiki http://tiddlywiki.com/ or something similar, I guess the emacs way
 described earlier also would support this. I personally always enjoy reading
 the readthedocs stuff http://docs.readthedocs.org/en/latest/ is that the
 sort of stuff you mean?
Tiddlywiki is interesting, but I'm really talking about the way LP was used by Knuth WEB/CWEB in his explanation of TeX and METAFONT. The Wikipedia article explains it pretty well (http://en.wikipedia.org/wiki/Literate_programming) You write a document combining documentation and code. Then two different programs (weave and ? for WEB) create the resulting documentation for one (HTML, pdf, whatever) and the code (a .d file) for another. I discovered LP through the incredible book "Physically-based Ray-Tracing". The book is one program, explained and documented using literate progamming. It's an incredible achievement (1000+ pages of explanations!). See: www.pbrt.org and more precisely: http://www.pbrt.org/chapters/pbrt_chapter7.pdf The code begins at page 18 of the pdf. For example, at page 22: <Sample Method Definitions> ≡ Sample::Sample(SurfaceIntegrator *surf, VolumeIntegrator *vol, const Scene *scene) { surf->RequestSamples(this, scene); vol->RequestSamples(this, scene); <Allocate storage for sample pointers 301> <Compute total number of sample values needed 302> <Allocate storage for sample values 302> } The snippet <Sample Method Definitions> introduces three new snippets, that will be explained elsewhere. Other snippets might also use the same references, if needed. It's not complicated to write a D tool for that, I did that some time ago. Once you define your begin/end token for snippet definitions, you can parse them to extract the way they are linked.
Sep 04 2014
prev sibling parent reply "Chris Cain" <zshazz gmail.com> writes:
On Tuesday, 26 August 2014 at 14:55:08 UTC, nikki wrote:
 I've been googling without luck, is there a way to do literate 
 programming in D?, similar to how it's done in Coffeescript ?

 http://www.coffeescriptlove.com/2013/02/literate-coffeescript.html

 basically me writing comments around code and some parser that 
 creates styled documents from that (with highlighted source 
 code), the current documentation system doesn't export the 
 source code.

 anybody done this before?
I used https://www.npmjs.org/package/literate-programming (+ pandoc) to do this when writing https://dl.dropboxusercontent.com/u/2206555/uniformUpgrade.pdf in markdown (which transformed to both a .d source file and a pdf document as shown in the link). literate-programming has since been improved since the last time I used it (before, I had to do a few tricks to get the pandoc flavored markdown to work well, but from what I can see, those tricks aren't necessary anymore).
Aug 29 2014
parent reply "Philippe Sigaud" <philippe.sigaud gmail.com> writes:
On Friday, 29 August 2014 at 23:58:19 UTC, Chris Cain wrote:
 I used https://www.npmjs.org/package/literate-programming (+ 
 pandoc) to do this when writing 
 https://dl.dropboxusercontent.com/u/2206555/uniformUpgrade.pdf 
 in markdown.
Do you remember if some snippets can be hidden in the final documented output (I don't find that in this package)? I know the goal of LP is to explain your code, but I remember using that with other systems: that's useful when you don't want to show some plumbing (for a tutorial for example, where you want to concentrate on the main suject).
Aug 30 2014
parent "Chris Cain" <zshazz gmail.com> writes:
On Saturday, 30 August 2014 at 07:33:38 UTC, Philippe Sigaud 
wrote:
 On Friday, 29 August 2014 at 23:58:19 UTC, Chris Cain wrote:
 I used https://www.npmjs.org/package/literate-programming (+ 
 pandoc) to do this when writing 
 https://dl.dropboxusercontent.com/u/2206555/uniformUpgrade.pdf 
 in markdown.
Do you remember if some snippets can be hidden in the final documented output (I don't find that in this package)? I know the goal of LP is to explain your code, but I remember using that with other systems: that's useful when you don't want to show some plumbing (for a tutorial for example, where you want to concentrate on the main suject).
From what I remember, I don't think it could do that (or, at least, it wasn't obvious/documented). I kinda wanted to do something like that with the performance test section (setting up the main function, importing, and such is just noise).
Aug 30 2014