From: Sam Liddicott <sam-zQGKLn5Wc3Lby3iVrkZq2A@public.gmane.org>
To: pandoc-discuss <pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org>
Subject: Pandoc support for implicit fenced code blocks in source files
Date: Fri, 4 Aug 2017 07:43:21 -0700 (PDT) [thread overview]
Message-ID: <36c4d1d4-2d9d-4919-97ab-0eaf588b22a3@googlegroups.com> (raw)
[-- Attachment #1.1: Type: text/plain, Size: 3189 bytes --]
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 pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/36c4d1d4-2d9d-4919-97ab-0eaf588b22a3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
[-- Attachment #1.2: Type: text/html, Size: 4394 bytes --]
next reply other threads:[~2017-08-04 14:43 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-08-04 14:43 Sam Liddicott [this message]
[not found] ` <36c4d1d4-2d9d-4919-97ab-0eaf588b22a3-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org>
2017-08-04 15:03 ` John MacFarlane
[not found] ` <20170804150352.GC74082-9Rnp8PDaXcadBw3G0RLmbRFnWt+6NQIA@public.gmane.org>
2017-08-07 8:42 ` Sam Liddicott
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=36c4d1d4-2d9d-4919-97ab-0eaf588b22a3@googlegroups.com \
--to=sam-zqgkln5wc3lby3ivrkzq2a@public.gmane.org \
--cc=pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).