Sam

On Friday, 4 August 2017 16:04:08 UTC+1, John MacFarlane wrote:

I'd say the obvious thing to do is to create a program
preprocesses the C source file, converting it into a
Markdown document that you can pipe through pandoc.

Or write a standalone tool in Haskell, using pandoc
as a library.  (And language-c to parse the source
code.)

+++ Sam Liddicott [Aug 04 17 07:43 ]:
>   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
>
>   --
>   You received this message because you are subscribed to the Google
>   Groups "pandoc-discuss" group.
>   To unsubscribe from this group and stop receiving emails from it, send
>   an email to [1]pandoc-discus...@googlegroups.com.
>   To post to this group, send email to
>   [2]pandoc-...@googlegroups.com.
>   To view this discussion on the web visit
>   [3]https://groups.google.com/d/msgid/pandoc-discuss/36c4d1d4-2d9d-4919-
>   97ab-0eaf588b22a3%40googlegroups.com.
>   For more options, visit [4]https://groups.google.com/d/optout.
>
>References
>
>   1. mailto:pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
>   2. mailto:pandoc-...@googlegroups.com
>   3. https://groups.google.com/d/msgid/pandoc-discuss/36c4d1d4-2d9d-4919-97ab-0eaf588b22a3@googlegroups.com?utm_medium=email&utm_source=footer
>   4. https://groups.google.com/d/optout