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


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.



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:




 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.



 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