The ###### is getting irritating since I've also been using the fenced code blocks with the language hints to get syntax highlighting.

Switch knot to requiring Pandoc's fenced code attributes. This is a far better way to annotate the code blocks since it allows for better integration with the front end. (I'm playing around with the idea of a literate program viewer.)

This means visible names on the code blocks is an option. I think this is good because it has been repetitive and not very useful for me in several documents.

http://johnmacfarlane.net/pandoc/README.html#extension-fenced_code_attributes

It still sucks. If there's a syntax error in the markdown file, this is what I get

{{badmatch,nomatch},
 [{knot,all_code,2,[{file,"src/knot.erl"},{line,41}]},
  {knot,process_file,1,[{file,"src/knot.erl"},{line,162}]},
  {knot,process_files,2,[{file,"src/knot.erl"},{line,189}]},
  {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,669}]},
  {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,438}]},
  {erl_eval,exprs,5,[{file,"erl_eval.erl"},{line,122}]},
  {knot,watch,3,[{file,"src/knot.erl"},{line,207}]}]}

Vim will delete and rewrite files (I forget the details of this). There's a race condition while knot is watching the file. If it tries to get the file info while it's deleted, the Erlang process gets an error an exits.

Hi @mqsoh I am really excited to find this repo. I am playing with literate programming and created a tool using js and md. As I was about to implement generating multiple files from a md, I encountered your repo.
Oh, what I want to say is that I am happy to see there are some people like you are practicing literate programming!

knot My\ File.md doesn't work. Probably just needs a change in the docker-entrypoint.sh.

The following line in knot.md is incorrect.

Now we can poll for changes. This function will take two different functions to perform work. One will be applied to each file and another for all files.

This is because the warning is printed when looking it up in the code map. That function is called five times to handle nested blocks.

Knot throws a one line error if the source file goes away and also if a destination directory doesn't exist.

escript: exception error: no match of right hand side value {error,enoent}

The all_code parser craps out with an unnamed, fenced code block. For example:

Some text.

```
Some code.
``` 

The problem.

Initially I supported indented and GitHub Flavored Markdown fenced code blocks and code blocks were denoted by the parser with H6 headers. With GFM you can give a language hint and their renderer will add syntax highlighting. There's no reason I would ever not use that feature, so I simplified the parser and supported only the fenced code blocks.

The H6 headers were irritating because sometimes it was too verbose in the rendered output. At the same time I started thinking ahead to a sort of literate program browser that would generate a table of contents and an index and I thought it would be nice if this was done with the rendered output, in JavaScript. The Pandoc style of Markdown has an interesting feature where you can provide the code hints and a name attribute that ends up on the code block's node in the HTML output. This makes the headers optional and gives adds some semantics in the output.

But...it's rare that I don't want the headers and now I've ended up making the following a habit:

###### Some piece of code.
```{.lisp name="Some piece of code."}
...code...
```

My justification was that the verbosity was permitting complete control of the output. However, my initial reasoning for writing this tool was that Markdown is a very legible markup language and, since it targets HTML directly, very convenient. The verbosity of this makes the source less legible.

The legibility is of primary importance because my primary goal was to avoid the weave step in the literate program tool (because Markdown is so widely used, we're guarenteed decent renderers).

Where am I going?

Weave?

Maybe I'm wrong not to weave. I could use a Markdown-esque markup that fit in more closely with typical literate program markup, i.e.

Typical *Markdown* documentation with

    a code block that is only an example, not part of the output source
    code.

<<*>>=
This is a root code block with a child.

<<More information.>>
@

More [Markdown](http://daringfireball.net/projects/markdown/), then

<<More information>>=
Foobar.
@

In this case, Knot would start to weave documents into Markdown.

Metadata inside the code block?

Instead of naming blocks before entering code blocks, maybe I can do so in the code block itself by establishing a rule that the first line of the code block should contain something special for named code blocks.

Documentation block.

```javascript
<<file:src/code.js>>=
...code...
<<Another code block.>>
```

More documentation.

```javascript
<<Another code block.>>=
...code...
```

That's not much less verbose, but if I preferred indented code blocks instead of fenced, it could be:

Documentation block.

    <<file:src/code.js>>=
    ...code...
    <<Another code block.>>

More documentation.

    <<Another code block.>>=
    ...code...

That's starting to look a little better, but what about syntax highlighting in the output? I'm not sure I need it. I've been writing code inside of Markdown documents without syntax highlighting for a while now and I'm not sure it's all that useful. I remember someone (I think Douglas Crockford) saying that syntax highlighting was childish and suggested that instead of highlighting keywords, function calls, etc. that it would be better to highlight scope. So -- maybe my ideal environment is a Markdown document with Rainbow Parentheses -- or maybe the ideal environment doesn't quite exist.

Other thoughts.

In a talk about improving Erlang, Joe Armstrong brought up a potential tool based on literate programming and some Haskell site where people comment on blocks of code. He said something about how, typically, programmers spend all their time researching a way to solve a problem, write down the solution (the code), then throw out all their research. ...which is a huge problem. He said he was working on something to fix it -- maybe it has ways to tag code, comment on code, generate hashes of code blocks so that they can be referenced from other tools... I hope he's still working on it. On the other hand, could I do any of this?

The Markdown syntax highlighter that I use for vim (not the core syntax file) kind of fall apart with fenced code blocks. For instance, with the extended version of the core syntax highlighter that I use, I have to set ft=markdown whenever I open a document even though I already do that with an autocmd. It's...weird. I saw an issue opened about it, but no one really solving the problem. I should go into more detail about it, but I don't feel like it right now. Do I want to just turn off all syntax highlighting? If so, that would suggest the second solution above using indented code blocks.

Screwing around with LFE; I couldn't start a file with this code block.

###### file:myscript
    #!/usr/bin/env lfescript
    ...

Change all instances of 'block' and 'macro' to 'section'. This will fit in with Knuth's terminology better. WEB is more robust and actually has parameterized macros; knot does not.

But...consider implementing macros. It might be doable in a way that integrates well with Markdown.

For example, with this source document.

###### file:myfile.txt
    ###### something
    ###### nothing

###### something
    I am something.

The output should be.

file:myfile.txt

I am something.

It might be nice to have two ways to define code sections. One way (how it is now) uses the line prefix and suffix and includes it on each line. The other could be simple insertion. It also occurred to me that a deduping code section might be cool each line is only included once.

Talk about an incredible tool. This is the best literate programming experience I've had outside of ORG-Mode. As org mode doesn't have much compatibility. I see this as a spectacular direct.

I'd like to be able to append to a file. Is there a way to do this?

For example if a page exposes a new function, you'd want to add it to your index file from the same page. If you want to add a dependency. Why not explain why you add it where you need it.

Thanks for all of what you've done so far.