Re: literate programming in D
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 ;)
Re: literate programming in D
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
Re: literate programming in D
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.
Re: literate programming in D
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?
Re: literate programming in D
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).
Re: literate programming in D
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).
Re: literate programming in D
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.
Re: literate programming in D
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
Re: literate programming in D
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
Re: literate programming in D
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).
literate programming in D
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?
Re: literate programming in D
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
Re: literate programming in D
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
Re: literate programming in D
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
Re: literate programming in D
That would work very fine, thanks sir!
