From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.text.pandoc/28988 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Benjamin Bray Newsgroups: gmane.text.pandoc Subject: Make fenced_divs extension more consistent with Markdown Directive Syntax Date: Tue, 10 Aug 2021 10:23:55 -0700 (PDT) Message-ID: <633f1aff-afa3-4191-8b69-909efa1ab5cen@googlegroups.com> Reply-To: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="----=_Part_156_1694299702.1628616235627" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="13398"; mail-complaints-to="usenet@ciao.gmane.io" To: pandoc-discuss Original-X-From: pandoc-discuss+bncBCOYXPVCWAIRBLHMZKEAMGQEMWAQIVA-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Tue Aug 10 19:24:00 2021 Return-path: Envelope-to: gtp-pandoc-discuss@m.gmane-mx.org Original-Received: from mail-oo1-f61.google.com ([209.85.161.61]) by ciao.gmane.io with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1mDVTr-0003HJ-Fh for gtp-pandoc-discuss@m.gmane-mx.org; Tue, 10 Aug 2021 19:23:59 +0200 Original-Received: by mail-oo1-f61.google.com with SMTP id k18-20020a4a94920000b029026767722880sf7639939ooi.7 for ; Tue, 10 Aug 2021 10:23:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20161025; h=sender:date:from:to:message-id:subject:mime-version :x-original-sender:reply-to:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-subscribe:list-unsubscribe; bh=bqYjU+ZmMz4p5KilEvEgRND7QxlilxJ/FswqYgMe4CY=; b=BVUIkwZYGyN1BHbEsWg4vRO9Cw6Om85htVuMrefaKfc3oJLLfiqO6HKT8Q1WDaXMqf D49FM22H61nAMYbfpogpifwxkS/Dste0urc7DxhTG0frac6/YSX8iakbqmEK/TH1sxAQ HyspbWbbx46lLW/SiA1wjfaGa6lpLAnt+D5h3IKaN+I8MEQ3VQruLo1mFQqfpk0LYQyP m2GPVS1VKwrv6SpwoT+oycrKHZYGskPyP35APzzuBIeMoiBaVOQSoZytlei8z8Sj5l4o gBY1Py2JiQmtz/ii1+aoabUgJPJ0uusfcD3CkVAbqjIVhEcG7P+cWnd9ZnbaK/WK8f1F UoTQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:message-id:subject:mime-version:x-original-sender :reply-to:precedence:mailing-list:list-id:list-post:list-help :list-archive:list-subscribe:list-unsubscribe; bh=bqYjU+ZmMz4p5KilEvEgRND7QxlilxJ/FswqYgMe4CY=; b=luQvxrIqQtRwsQy2cJ65ieXo3LRU1GIf7OoDh//2tgXBtCrq1n6inRp8QpjXjuZ4tw 0beGSzk/EHVaKWCdY7+hZlu3O6JYWTj48o6pwE4Tsp4IxOhwPmCBlvQ3Deg52SZHUZM+ XU1NOwJugbYhpNJdTbAUjU1cEEUPsFO6rExQkvH5zOWEgxuH2wuae9Ocup7cG5zAuA6G 0+Kq+R8DdPO3B37ghnlZPdMPOaOKqepLjfJ5En3Wpg3qOr5WPYHTUxwQflGStRLP2iQ1 OsZ6s0vrLBLF4rH4wFvB3W0Z0ydRRA9tPI3ysjlK07qiye/AnaonRxp1vM3q5AkdEORR 1hsA== 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: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=bqYjU+ZmMz4p5KilEvEgRND7QxlilxJ/FswqYgMe4CY=; b=F8eqbRIfwR5/Tpc8uXPHbYnQbtZBpqURAxCcv1lYJMkuR9cqSAMpMSNk/pFprGrJl5 mmAFris0z7SOZkV9/9tPDbIutOuVwyEqpAuKbDAEazdehufh5NROAQYcpHD5yeXOvYog /8yBlaKB/UsEjKaR/tETu4JIrqEYFPswMUtJ4OsqW5JuzJYcS3cURYXxXlXRncyWz59h Rh58ZgBApVGa5rm7aVnQXM9gWZ91tfqCvrknsm3/alJ5pPegRPHGSeczCHuFl8ITENt/ Iu7ONaHx6V2WBDl0N4mNye3Zn+kwJ47nXnBr4Y3BbBVkYt+HQTPKLMFYihithL9X90At NCGQ== Original-Sender: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org X-Gm-Message-State: AOAM532GCBE+7GdL4sdUDVfxJuqz3o6TZMV/NKcih1NojsWjdMeWcafU 2cgHb+DfMHAJP9FnyVbmCRw= X-Google-Smtp-Source: ABdhPJxoT4hdMfyQK9NCU4FPBISQCPi4t1bHVZ20Z945oNxsmRjKbLcY9H01ewRmc58SE4t0OG345g== X-Received: by 2002:a05:6830:2103:: with SMTP id i3mr11841807otc.363.1628616238118; Tue, 10 Aug 2021 10:23:58 -0700 (PDT) X-BeenThere: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org Original-Received: by 2002:a05:6830:19fd:: with SMTP id t29ls2691626ott.0.gmail; Tue, 10 Aug 2021 10:23:56 -0700 (PDT) X-Received: by 2002:a9d:7985:: with SMTP id h5mr22521452otm.283.1628616236162; Tue, 10 Aug 2021 10:23:56 -0700 (PDT) X-Original-Sender: benrbray-Re5JQEeQqe8AvxtiuMwx3w@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.io gmane.text.pandoc:28988 Archived-At: ------=_Part_156_1694299702.1628616235627 Content-Type: multipart/alternative; boundary="----=_Part_157_1046293166.1628616235627" ------=_Part_157_1046293166.1628616235627 Content-Type: text/plain; charset="UTF-8" (duplicated from pandoc#7480 on GitHub at the request of jgm) I'd like to collect feedback on a backwards-compatible change to the fenced_divs extension which will make it more compatible with Markdown Directive Syntax. Please let me know if you think this is a good idea, or if it might have any unintended consequences. *Pandoc's fenced_divs Extension* Pandoc's fenced_div extension currently supports the following syntax for creating divs: Example 1 (try pandoc ) ::::: {#special .sidebar key=value} Here is a paragraph. And another. ::::: Example 2 (try pandoc ) ::: Warning :::::: This is a warning. ::: Danger This is a warning within a warning. ::: ::::::::::::::::::

This is a warning.

This is a warning within a warning.

*Limitations of fenced_divs / Proposed Behavior* Strangely, Pandoc does not allow you to combine the two fenced_div syntax styles: :::: container {.theorem #id key=value} :::::: This is a theorem. ::::

:::: container {.theorem #mytheorem key=value} :::::: This is a theorem. ::::

I think this is a perfectly natural thing to do. Personally, I like to use this syntax when "container" is a common class that will be matched by CSS, and .theorem / .lemma / .corollary / etc are secondary classes that determine the contents of a ::before element (for instance). Given the current behavior, I would expect the output to be something like this:

This is a theorem.

*Proposed Implementation* Here's a simple rewrite (see benrbray@8a20611 ) of the divFenced parser that allows for the proposed change. Seems to work locally and all tests currently pass. I can make a PR if this is a desirable change. Some guidance on code style and how to write appropriate tests for this would be helpful. Thanks! divFenced :: PandocMonad m => MarkdownParser m (F Blocks) divFenced = do guardEnabled Ext_fenced_divs try $ do string ":::" skipMany (char ':') skipMany spaceChar -- begin change name <- option [] $ pure <$> (many1Char nonspaceChar) skipMany spaceChar (ident, classes, keyval) <- option nullAttr attributes let attribs = (ident, name ++ classes, keyval) guard (attribs /= nullAttr) -- end change skipMany spaceChar skipMany (char ':') blankline updateState $ \st -> st{ stateFencedDivLevel = stateFencedDivLevel st + 1 } bs <- mconcat <$> manyTill block divFenceEnd updateState $ \st -> st{ stateFencedDivLevel = stateFencedDivLevel st - 1 } return $ B.divWith attribs <$> bs Background: Markdown Directive Syntax Some markdown implementations support the following de-facto standard for directive syntax , with syntax for inline, leaf, and block directives. Perhaps in a future proposal it would be desirable to add these to the Pandoc AST for further processing, but for now I would be satisfied if the syntax for the fenced_div extension were updated to more closely align with the directive syntax. Inline Directive :name[content]{#id .class1 .class2 key=val} Leaf Directive :: name [content] {key=val} Block Directive ::: name [inline-content] {key=val} contents, which are sometimes further block elements ::: *Alternatives* - Instead of modifying the behavior of fenced_divs, create a separate extension directive_divs - Incorporate Markdown directive syntax into the pandoc AST instead of converting to divs (this would be a much larger change -- maybe more appropriate for a future PR if this one is merged) - Re-write any directive syntax in my markdown documents to use the format expected by pandoc (quite undesirable) *Questions* - What do you think of this behavior? - Will this have any unintended consequences? - Has the adoption of directive syntax in Pandoc been discussed before / any conclusions reached? - This proposal leaves out the "inline content" section of the markdown directive syntax. It could be easily included, but it's not obvious where it should go (an attribute? a span?). Perhaps it's more appropriate to save for a later date if Pandoc ever properly adopts directive syntax. *References* Directive Syntax - Talk.CommonMark, "Generic directives/plugins syntax" - RemarkJS, remark-directive plugin - markdown-it, markdown-it-directive plugin Possibly Related Issues - GitHub, Make fenced_divs more consistent with Markdown Directive Syntax #7480 - GitHub, Documentation: Clarify fenced_divs #4037 - pandoc-discuss, New extension generic directives Thank you for your consideration! - Ben -- 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 view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/633f1aff-afa3-4191-8b69-909efa1ab5cen%40googlegroups.com. ------=_Part_157_1046293166.1628616235627 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
(duplicated from pandoc#7480 on GitHub at the request of jgm)

<= div>I'd like to collect feedback on a backwards-compatible change to the fe= nced_divs extension which will make it more compatible with Markdown Direct= ive Syntax.  Please let me know if you think this is a good idea, or i= f it might have any unintended consequences.

Pandoc's fenced_divs Extension

Pandoc= 's fenced_di= v extension currently supports the following syntax for creat= ing divs:

Example 1 (try pandoc)

::::: {#spec= ial .sidebar key=3Dvalue}
Here = is a paragraph.
And another.
:::::

<div id=3D"special" class=3D"sidebar" data-key=3D"val= ue">
<p>Here is a para= graph.</p>
<p>And a= nother.</p>
</div>

Example 2 (try pandoc)

::: Warning := :::::
This is a warning.=
::: Danger
This is a warning within a warning.
:::
::::= ::::::::::::::

<div class=3D"Warning">
<p>This is a warning.</p>
<div class=3D"Danger">
<p>This is a warning within a warning.</p&g= t;
</div>
</div>

Limitations of fenced_divs / Proposed Behavior

Strangely= , Pandoc does not allow you to combine the two fenced_div syntax = styles:

:::: container {.theorem #id key= =3Dvalue} ::::::
This is a theo= rem.
::::

<p>:::: container {.theorem #mytheorem key=3Dvalue= } :::::: This is a theorem. ::::</p>

I think this is a perfectly natural thing to do. Personally= , I like to use this syntax when "container" is a common class th= at will be matched by CSS, and .theorem / .lemma / .corollary / etc are sec= ondary classes that determine the contents of a ::before element = (for instance).

Given the current behavior, I would expect the output= to be something like this:

<div id=3D= "mytheorem" class=3D"container theorem" data-key=3D"value">
=
<p>This is a theorem.</p>=
</div>

Proposed Implementation

Here's a simple rewri= te (see benrbra= y@8a20611) of the divFenced

divFenced :: PandocMonad m =3D> MarkdownParser m (F Blocks)
divFenced =3D do<= /div>
  guardEnabled Ext_fen= ced_divs
  try = $ do
    s= tring ":::"
  &= nbsp; skipMany (char ':')
    skipMany spaceChar

    -- begin change
    name <- option [] $ pure <$> (many1Cha= r nonspaceChar)
&nbs= p;   skipMany spaceChar
    (ident, classes, keyval) <- option nullAttr attri= butes
    = let attribs =3D (ident, name ++ classes, keyval)
    guard (attribs /=3D nullAttr)
    -- end c= hange

    skipMany spaceC= har
    sk= ipMany (char ':')
&n= bsp;   blankline
      st{ stateFencedDivLevel =3D stateF= encedDivLevel st + 1 }
    bs <- mconcat <$> manyTill block divFenceEnd
    updateStat= e $ \st ->
 =     st{ stateFencedDivLevel =3D stateFencedDivLevel st - 1 }
    return $ = B.divWith attribs <$> bs

Background:  Markdown Directive Syntax

Some mark= down implementations support the following de-facto standard for = directive syntax, with syntax for inline, leaf, and block directives. P= erhaps in a future proposal it would be desirable to add these to the Pando= c AST for further processing, but for now I would be satisfied if the synta= x for the fenced_div extension were updated to more closely align= with the directive syntax.

Inline Directive

:name[content]{#id .class1 .class2 key=3Dval}

Leaf Directive

:: name [= content] {key=3Dval}

Block Directive

::: name= [inline-content] {key=3Dval}
c= ontents, which are sometimes further block elements
:::

Alternatives
    =
  • Instead of modifying the behavior of fenced_divs, create a separat= e extension directive_divs
  • Incorporate Markdown directive synt= ax into the pandoc AST instead of converting to divs (this would be a much = larger change -- maybe more appropriate for a future PR if this one is merg= ed)
  • Re-write any directive syntax in my markdown documents to use t= he format expected by pandoc (quite undesirable)
Questions
  • What do you think of this be= havior?
  • Will this have any unintended consequences?
  • Has the= adoption of directive syntax in Pandoc been discussed before / any conclus= ions reached?
  • This proposal leaves out the "inline content" section= of the markdown directive syntax.  It could be easily included, but i= t's not obvious where it should go (an attribute? a span?).  Perhaps i= t's more appropriate to save for a later date if Pandoc ever properly adopt= s directive syntax.
References

Directive Syntax

Possibly Related Issues

Thank you for y= our consideration!

- Ben

--
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 view this discussion on the web visit https://groups.google.com/d= /msgid/pandoc-discuss/633f1aff-afa3-4191-8b69-909efa1ab5cen%40googlegroups.= com.
------=_Part_157_1046293166.1628616235627-- ------=_Part_156_1694299702.1628616235627--