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).

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).

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 ;)

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.

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

> 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.