I use pandoc in my C source files.
C comments contain pandoc markup, or perhaps special C comments like this /*:pandoc
and the pandoc ends when the C comment ends.
Combined with goat (to convert ascii diagrams to SVG) this is a great way to document code.
The difficulty in doing this now is convincing pandoc that code outside of comments is a fenced code block, and that the start end end comment markers shouldn't be rendered.
For instance:
---8<------8<------8<------8<------8<------8<------8<---
/**
It's a shame that pandoc renders the leading /*
and now here is some code but it the comment markers sadly render:
~~~C
*/
int x() {
blag();
}; /*
~~~
etc.
*/
---8<------8<------8<------8<------8<------8<------8<---
This feature can't be implemented using the filters, because if pandoc treats the C source as pandoc markup, the start-comment might be halfway through an AST node that never should be there.
I think that it needs parser support; but it isn't a new input format either, as other variants of markdown might be used internally.
Ideally, this requires a new parsing mode to assume a fenced-code-block interspersed with other pandoc markup.
i think the method is:
based on the file extension or a runtime argument, set the default fenced code block type, and the comment start and end sequences.
1. If, (after skipping initial white space), the first text is not a comment-start-sequence, then the fence-code block is assumed before the white space, and all the input is inserted into that fenced code block in the AST until end-of-file or a comment-start-sequence.
2. At a comment-start-sequence, the sequence is thrown away and the parse acts as if a fenced-code-block-end was read.
3. Parsing continues as normal until a comment-end-sequence is read. This sequence is thrown away and the parser repeats from 1.
Now maybe the start-comment-sequence is always followed by a magic header like :pandoc and maybe by further attributes which ought to be applies to the previous fenced code block, and maybe the end-comment-sequence could have attributes to apply to the upcoming fenced-code-block. Maybe as a way to say: skip this code block until you next see a pandoc comment, don't even bother to emit it. Not all code wants to be part of the documentation, after all.
Maybe this would be better suited to an awk script to run manually and not be part of pandoc at all. I'm using this sed, which does the job somewhat.
sed -e '1!s/^\/\* */~~~\n\n/;/\/\*/!s/\*\/$/\n\n~~~C/' | pandoc --toc -s -S -o doc.html
What are others thoughts on this?
Sam