Rule for Horizontal Rule, Table, or YAML delimiter

Rule for Horizontal Rule, Table, or YAML delimiter

[Pranesh Prakash]

[-- Attachment #1.1: Type: text/plain, Size: 1379 bytes --]

Dear all,
This e-mail is prompted by troubles my text editor had been having with 
understanding Pandoc syntax regarding `---`.  I then realized I didn't know 
the precise rules myself.

I'd like to know how Pandoc distinguishes between `---` as a horizontal 
rule, as a table row demarcator for simple_tables, or as a YAML metadata 
block delimiter.

Searching through the manual I only found the following rules, which didn't 
fully answer my question:
1. For YAML: "if it [---] is not at the beginning, it must be preceded by a 
blank line"
2. For simple_table: "The table must end with a blank line, or a line of 
dashes followed by a blank line." and "The column header row may be 
omitted, provided a dashed line is used to end the table."  (So it is 
possible for a table to have a single row.)
3. Horizontal rules: "A line containing a row of three or more *, -, or _ 
characters (optionally separated by spaces) produces a horizontal rule".

Regards,
Pranesh

-- 
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/6a595498-2d21-4a73-833c-5d7e57363833n%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 1902 bytes --]

Re: Rule for Horizontal Rule, Table, or YAML delimiter

[Albert Krewinkel]

Pranesh Prakash writes:

> Dear all,
> This e-mail is prompted by troubles my text editor had been having with
> understanding Pandoc syntax regarding `---`.  I then realized I didn't know
> the precise rules myself.
>
> I'd like to know how Pandoc distinguishes between `---` as a horizontal
> rule, as a table row demarcator for simple_tables, or as a YAML metadata
> block delimiter.

There is even a fourth possibility: as part of a setext header:

    fun
    ---

Pandoc uses the following order, trying the next only if the
previous failed: YAML block, header, table, hrule. So basically, all
other alternative take precedence, and treating it as a horizontal
rule is the last resort.

What might be missing from the docs is that the `---` line may not
be followed by a blank line when demarking a YAML block.

Does that answer your question?

--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124

Re: Rule for Horizontal Rule, Table, or YAML delimiter

[BPJ]

[-- Attachment #1: Type: text/plain, Size: 2113 bytes --]

You can always use four asterisks, which should unmistakably be an
horizontal rule.

****

/bpj

-- 
Better --help|less than helpless

Den sön 1 nov. 2020 22:00Albert Krewinkel <albert+pandoc-9EawChwDxG8hFhg+JK9F0w@public.gmane.org>
skrev:

>
> Pranesh Prakash writes:
>
> > Dear all,
> > This e-mail is prompted by troubles my text editor had been having with
> > understanding Pandoc syntax regarding `---`.  I then realized I didn't
> know
> > the precise rules myself.
> >
> > I'd like to know how Pandoc distinguishes between `---` as a horizontal
> > rule, as a table row demarcator for simple_tables, or as a YAML metadata
> > block delimiter.
>
> There is even a fourth possibility: as part of a setext header:
>
>     fun
>     ---
>
> Pandoc uses the following order, trying the next only if the
> previous failed: YAML block, header, table, hrule. So basically, all
> other alternative take precedence, and treating it as a horizontal
> rule is the last resort.
>
> What might be missing from the docs is that the `---` line may not
> be followed by a blank line when demarking a YAML block.
>
> Does that answer your question?
>
> --
> Albert Krewinkel
> GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124
>
> --
> 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/87eelclrnh.fsf%40zeitkraut.de
> .
>

-- 
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/CADAJKhBVUELH6EzGMh-riZXSOrXLQi-n%2BrMe4iLy8%3DC5fGSBng%40mail.gmail.com.

[-- Attachment #2: Type: text/html, Size: 3189 bytes --]

Re: Rule for Horizontal Rule, Table, or YAML delimiter

[Pranesh Prakash]

[-- Attachment #1.1: Type: text/plain, Size: 2441 bytes --]

On Monday, 2 November, 2020 at 2:29:55 am UTC+5:30 Albert Krewinkel wrote:

> Pandoc uses the following order, trying the next only if the 
> previous failed: YAML block, header, table, hrule. So basically, all 
> other alternative take precedence, and treating it as a horizontal 
> rule is the last resort. 
>
> What might be missing from the docs is that the `---` line may not 
> be followed by a blank line when demarking a YAML block. 
>
> Does that answer your question? 
>
>
It does to a large extent.  Thanks!

But it would still be helpful to know what (apart from a blank line after 
`---`) would make a YAML block fail. Would a YAML block fail if there is no 
`...` or `---` in the rest of the body?

And what would make a sextext level 2 heading indicator fail?  (From my 
tests, even a single `-` can be a heading indicator.)  (The manual only 
says: A setext-style heading is a line of text “underlined” with a row of = 
signs (for a level-one heading) or - signs (for a level-two heading))  And 
what prevents this from being read as hrule + setext header (given that 
setext > table, though table > hrule)?

```
---
text
---
```

Similarly, what would make a simple_table fail?

One could very justifiably note that this level of detail doesn't belong in 
the manual, and to know this one must read the code.

But I feel it would be useful to have it documented *somewhere*, perhaps in 
the Github wiki?

On a separate note, given that since 2014,[1] Jekyll has supported `...` as 
the end delimiter for a YAML block, and every Markdown parser that 
understands YAML metadata blocks (i.e., MultiMarkdown and pandoc) 
understands `...` as a block demarcator,[2] perhaps the manual should 
indicate a preference for being unambiguous and in line with the YAML specs?

Regards,
Pranesh


[1]: 
https://github.com/jekyll/jekyll/commit/52ac2b3850e25c783ec31c46eda948cffd861452
[2]: https://johnmacfarlane.net/babelmark2/?text=---%0Akey%3A+value%0A...%0A


-- 
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/5f68cf42-966d-4f0c-b752-68c146894dd1n%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 3336 bytes --]

Re: Rule for Horizontal Rule, Table, or YAML delimiter

[Albert Krewinkel]

Pranesh Prakash writes:

> On Monday, 2 November, 2020 at 2:29:55 am UTC+5:30 Albert Krewinkel wrote:
>
>> Pandoc uses the following order, trying the next only if the
>> previous failed: YAML block, header, table, hrule. So basically, all
>> other alternative take precedence, and treating it as a horizontal
>> rule is the last resort.
>>
>> What might be missing from the docs is that the `---` line may not
>> be followed by a blank line when demarking a YAML block.
>>
>> Does that answer your question?
>>
>>
> It does to a large extent.  Thanks!
>
> But it would still be helpful to know what (apart from a blank line after
> `---`) would make a YAML block fail. Would a YAML block fail if there is no
> `...` or `---` in the rest of the body?
>
> [⋮]
>
> But I feel it would be useful to have it documented *somewhere*, perhaps in
> the Github wiki?

I'd have to read the code to answer these.

John mentioned that he intends to replace the current Markdown reader
with the commonmark_x reader over time. The switch should resolve the
documentation issue, as CommonMark has a spec.


--
Albert Krewinkel
GPG: 8eed e3e2 e8c5 6f18 81fe  e836 388d c0b2 1f63 1124

-- 
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/878sbitn9l.fsf%40zeitkraut.de.