From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.text.pandoc/18024 Path: news.gmane.org!.POSTED!not-for-mail From: Sam Liddicott Newsgroups: gmane.text.pandoc Subject: Re: Pandoc support for implicit fenced code blocks in source files Date: Mon, 7 Aug 2017 01:42:34 -0700 (PDT) Message-ID: <668512b2-3a37-4c33-a521-7e77f48e8e7a@googlegroups.com> References: <36c4d1d4-2d9d-4919-97ab-0eaf588b22a3@googlegroups.com> <20170804150352.GC74082@Johns-MacBook-Pro.local> Reply-To: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="----=_Part_3080_136968522.1502095354302" X-Trace: blaine.gmane.org 1502095356 22353 195.159.176.226 (7 Aug 2017 08:42:36 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 7 Aug 2017 08:42:36 +0000 (UTC) To: pandoc-discuss Original-X-From: pandoc-discuss+bncBDOYFR5FTILRB66PUDGAKGQEZN4CFQY-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Mon Aug 07 10:42:31 2017 Return-path: Envelope-to: gtp-pandoc-discuss@m.gmane.org Original-Received: from mail-io0-f192.google.com ([209.85.223.192]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dedcL-0005Sf-Di for gtp-pandoc-discuss@m.gmane.org; Mon, 07 Aug 2017 10:42:29 +0200 Original-Received: by mail-io0-f192.google.com with SMTP id m88sf60195iod.0 for ; Mon, 07 Aug 2017 01:42:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20161025; h=sender:date:from:to:message-id:in-reply-to:references:subject :mime-version:x-original-sender:reply-to:precedence:mailing-list :list-id:list-post:list-help:list-archive:list-subscribe :list-unsubscribe; bh=FvdSRflSOqO1F2gGAsyOeVGpFjn8CzLtkUFUZ8fIU3g=; b=fkY3fAO/56p1FWpFQlQzQM761X6VrQNED+VFeSm/12dGIGnMunVHN/7TWRgzaR7mTh a2mIm1clpLUwOuLh3Fm48PGnUO+YxfXsdAAsycxQniAPsf49JshkS5pOFHSeiEZTW8n5 fbe8MlNr6b7jviWJXjszB/W7LSerkEWPmUucRf8ilGnf1Fn00fF800IBKy7EHaFnJxMe ec9hZH3pdh8O/pShbpgZzkBTy+U5vffNYka11xoKmizWZwIvjlU410HW95s3DwE/xv4s hp73gTdwsNW6YX062OVeKn+vkp8ndr9di3j7T8JMnvAZ+Lt31wuf3ce4JmRpYtP+Heu7 Y26g== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=liddicott-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:message-id:in-reply-to:references:subject:mime-version :x-original-sender:reply-to:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-subscribe:list-unsubscribe; bh=FvdSRflSOqO1F2gGAsyOeVGpFjn8CzLtkUFUZ8fIU3g=; b=B3DVfdqm+STNNGooZiQjwgkXva1y4YuUiKHR3f9lk625AAKN+WuOpTUm0tiZhnXKWD su93TM5/MHilv2Xu1JVNnpKl3gmkCMKxNVweop6jSMIJGLapuAQ8Z00L5T+ffffHKHmn T81S5xtVjGeQnCu9OYeKhHuoyMdlXS1V3/xR09eEY+NY5MlLvZIJDyS2FoRM1p8uolrR +UQu48LzTUuvpeX2Khpxrt0Rs/NFLT5QYdeD7MnTn/B8NIy+/L6qsZDxDzS1cAXo34U2 nobJH/g+tVwvqFmwPAy6pbWmskGICzRPOSKDFDcVtmMYNu+GY5S0/zYA6LpuOyf8kyr8 kw6w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=sender:x-gm-message-state:date:from:to:message-id:in-reply-to :references:subject:mime-version:x-original-sender:reply-to :precedence:mailing-list:list-id:x-spam-checked-in-group:list-post :list-help:list-archive:list-subscribe:list-unsubscribe; bh=FvdSRflSOqO1F2gGAsyOeVGpFjn8CzLtkUFUZ8fIU3g=; b=mkon1WIGkoH5HnP5GOkRe8yuKfO9nnMqMOmb6EOoqDUepqP5iwhbfFU5Q7VR3iLmQV ShmvgEuTZmsZQHcJmgUfs9PDrXdHR6dLSo2zFRsjx44K4qP4OdVf/zDxL5dpimQE0hdD 25M7Ae3DpoGRIPyIdxW6mNI3LbN4Q1E28B6Jz9ppORFVZ3+4G6b2fCHjzJpJan4rNCyS cPkkcFC88yjx4KqVwOF3KrH6zOO60YmNekZfiItE9PGx2KYEL5Di2c1uhSG4ovsaN92h Fi+C65p2TuvB5gOhJ7BBEIc8qQSJ1eMePV3qLHdTTYIzedBMPJW3g68BrwF6n6+vih5J TxsQ== Original-Sender: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org X-Gm-Message-State: AHYfb5i6XazObjuZz7siSawTJIoflEQ3nG0hlYoGSNa6zwC816seFbUX 5WBRePCvRN2nBw== X-Received: by 10.36.57.69 with SMTP id l66mr7517ita.1.1502095355628; Mon, 07 Aug 2017 01:42:35 -0700 (PDT) X-BeenThere: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Original-Received: by 10.36.79.69 with SMTP id c66ls1498721itb.1.canary-gmail; Mon, 07 Aug 2017 01:42:34 -0700 (PDT) X-Received: by 10.36.39.140 with SMTP id g134mr7091ita.7.1502095354888; Mon, 07 Aug 2017 01:42:34 -0700 (PDT) In-Reply-To: <20170804150352.GC74082-9Rnp8PDaXcadBw3G0RLmbRFnWt+6NQIA@public.gmane.org> X-Original-Sender: sam-zQGKLn5Wc3Lby3iVrkZq2A@public.gmane.org Precedence: list Mailing-list: list pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org; contact pandoc-discuss+owners-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org List-ID: X-Google-Group-Id: 1007024079513 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , Xref: news.gmane.org gmane.text.pandoc:18024 Archived-At: ------=_Part_3080_136968522.1502095354302 Content-Type: multipart/alternative; boundary="----=_Part_3081_1839752155.1502095354303" ------=_Part_3081_1839752155.1502095354303 Content-Type: text/plain; charset="UTF-8" Thanks, John, for both your replies. 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...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org . > > To post to this group, send email to > > [2]pandoc-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org . > > 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-...-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org > > 3. > https://groups.google.com/d/msgid/pandoc-discuss/36c4d1d4-2d9d-4919-97ab-0eaf588b22a3-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org?utm_medium=email&utm_source=footer > > 4. https://groups.google.com/d/optout > > -- 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/668512b2-3a37-4c33-a521-7e77f48e8e7a%40googlegroups.com. For more options, visit https://groups.google.com/d/optout. ------=_Part_3081_1839752155.1502095354303 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Thanks, John, for both your replies.

Sa= m

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. =C2=A0(And language-c to parse the source
code.)

+++ Sam Liddicott [Aug 04 17 07:43 ]:
> =C2=A0 I use pandoc in my C source files.
> =C2=A0 C comments contain pandoc markup, or perhaps special C comm= ents like
> =C2=A0 this /*:pandoc
> =C2=A0 and the pandoc ends when the C comment ends.
> =C2=A0 Combined with goat (to convert ascii diagrams to SVG) this = is a great
> =C2=A0 way to document code.
> =C2=A0 The difficulty in doing this now is convincing pandoc that = code outside
> =C2=A0 of comments is a fenced code block, and that the start end = end comment
> =C2=A0 markers shouldn't be rendered.
> =C2=A0 For instance:
> =C2=A0 ---8<------8<------8<------8<------8<--= ----8<------8<---
> =C2=A0 /**
> =C2=A0 It's a shame that pandoc renders the leading /*
> =C2=A0 and now here is some code but it the comment markers sadly = render:
> =C2=A0 ~~~C
> =C2=A0 */
> =C2=A0 int x() {
> =C2=A0 =C2=A0 blag();
> =C2=A0 }; /*
> =C2=A0 ~~~
> =C2=A0 etc.
> =C2=A0 */
> =C2=A0 ---8<------8<------8<------8<------8<--= ----8<------8<---
> =C2=A0 This feature can't be implemented using the filters, be= cause if pandoc
> =C2=A0 treats the C source as pandoc markup, the start-comment mig= ht be
> =C2=A0 halfway through an AST node that never should be there.
> =C2=A0 I think that it needs parser support; but it isn't a ne= w input format
> =C2=A0 either, as other variants of markdown might be used interna= lly.
> =C2=A0 Ideally, this requires a new parsing mode to assume a fence= d-code-block
> =C2=A0 interspersed with other pandoc markup.
> =C2=A0 i think the method is:
> =C2=A0 based on the file extension or a runtime argument, set the = default
> =C2=A0 fenced code block type, and the comment start and end seque= nces.
> =C2=A0 1. If, (after skipping initial white space), the first text= is not a
> =C2=A0 comment-start-sequence, then the fence-code block is assume= d before the
> =C2=A0 white space, and all the input is inserted into that fenced= code block
> =C2=A0 in the AST until end-of-file or a comment-start-sequence.
> =C2=A0 2. At a comment-start-sequence, the sequence is thrown away= and the
> =C2=A0 parse acts as if a fenced-code-block-end was read.
> =C2=A0 3. Parsing continues as normal until a comment-end-sequence= is read.
> =C2=A0 This sequence is thrown away and the parser repeats from 1.
> =C2=A0 Now maybe the start-comment-sequence is always followed by = a magic
> =C2=A0 header like :pandoc and maybe by further attributes which o= ught to be
> =C2=A0 applies to the previous fenced code block, and maybe the
> =C2=A0 end-comment-sequence could have attributes to apply to the = upcoming
> =C2=A0 fenced-code-block. Maybe as a way to say: skip this code bl= ock until
> =C2=A0 you next see a pandoc comment, don't even bother to emi= t it. Not all
> =C2=A0 code wants to be part of the documentation, after all.
> =C2=A0 Maybe this would be better suited to an awk script to run m= anually and
> =C2=A0 not be part of pandoc at all. I'm using this sed, which= does the job
> =C2=A0 somewhat.
> =C2=A0 =C2=A0 sed -e '1!s/^\/\* */~~~\n\n/;/\/\*/!s/\*\/$/\n\<= wbr>n~~~C/' | pandoc --toc
> =C2=A0 -s -S -o doc.html
> =C2=A0 What are others thoughts on this?
> =C2=A0 Sam
>
> =C2=A0 --
> =C2=A0 You received this message because you are subscribed to the= Google
> =C2=A0 Groups "pandoc-discuss" group.
> =C2=A0 To unsubscribe from this group and stop receiving emails fr= om it, send
> =C2=A0 an email to [1]pandoc-discus...@googlegroups.com.
> =C2=A0 To post to this group, send email to
> =C2=A0 [2]pandoc-...@googlegroups.com.
> =C2=A0 To view this discussion on the web visit
> =C2=A0 [3]http= s://groups.google.com/d/msgid/pandoc-discuss/36c4d1d4-2d9d-4919-<= /a>
> =C2=A0 97ab-0eaf588b22a3%40googlegroups.com.
> =C2=A0 For more options, visit [4]https:= //groups.google.com/d/optout.
>
>References
>
> =C2=A0 1. mailto:pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
> =C2=A0 2. mailto:pandoc-...@googlegroups.com
> =C2=A0 3. https://groups.google.com/d/msgid/pandoc-discuss/36c4d1d4-2= d9d-4919-97ab-0eaf588b22a3@googlegroups.com?utm_medium=3Demail&am= p;utm_source=3Dfooter
> =C2=A0 4. https://groups.google.com/d/optout

--
You received this message because you are subscribed to the Google Groups &= quot;pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an e= mail to pand= oc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/= msgid/pandoc-discuss/668512b2-3a37-4c33-a521-7e77f48e8e7a%40googlegroups.co= m.
For more options, visit http= s://groups.google.com/d/optout.
------=_Part_3081_1839752155.1502095354303-- ------=_Part_3080_136968522.1502095354302--