Proposal: default to ATX-style headings in markdown output

Proposal: default to ATX-style headings in markdown output

[John MacFarlane]

Currently in writing markdown (and commonmark) pandoc emits
Setext-style (underlined) headings for levels 1 and 2, ATX_style
(#) for the rest, unless the `--atx-headers` option is used
to force ATX.

Proposal: given that setext headings are becoming more
uncommon, and in view of the ugliness of switching heading
styles at level 3, default instead to ATX-style headings,
unless a new `--setext-headings` option is used.

Comments?

Note: in principle we could also change the default just
for commonmark/gfm output, not for default markdown.
However, this would still require adding a --setext-headings
option.

Re: Proposal: default to ATX-style headings in markdown output

[Anton Shepelev]

John MacFarlane:

> Currently in writing markdown (and commonmark) pandoc
> emits Setext-style (underlined) headings for levels 1 and
> 2, ATX_style (#) for the rest, unless the `--atx-headers`
> option is used to force ATX.
>
> Proposal: given that setext headings are becoming more
> uncommon, and in view of the ugliness of switching heading
> styles at level 3, default instead to ATX-style headings,
> unless a new `--setext-headings` option is used.
>
> Comments?

In my opinion, *any* uniform heading style is better than the
current inconsistent behavior.  I prefer the ATX header
format even though it does not support the breaking of long
heading into multiple lines.

Re: Proposal: default to ATX-style headings in markdown output

[BPJ]

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

Den tors 3 sep. 2020 18:07Anton Shepelev <anton.txt-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> skrev:

> John MacFarlane:
>
> > Currently in writing markdown (and commonmark) pandoc
> > emits Setext-style (underlined) headings for levels 1 and
> > 2, ATX_style (#) for the rest, unless the `--atx-headers`
> > option is used to force ATX.
> >
> > Proposal: given that setext headings are becoming more
> > uncommon, and in view of the ugliness of switching heading
> > styles at level 3, default instead to ATX-style headings,
> > unless a new `--setext-headings` option is used.
> >
> > Comments?


> In my opinion, *any* uniform heading style is better than the
> current inconsistent behavior.


I concur emphatically.

I prefer the ATX header
> format


So do I.

even though it does not support the breaking of long
> heading into multiple lines.
>

It could, if blank lines before and after were required (as I believe they
are by default in Pandoc's Markdown.) Headings should be short though!
However I have run into potentially troublesome cases when transcribing
older texts. It would be good if at least hard linebreaks worked (which I
believe is currently not the case.)


> --
> 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/20200903190619.e924ccd888daca8cef4460ea%40gmail.com
> .
>

-- 
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/CADAJKhAM7MbY3GExs38hrApHrSntg87X04sKbJTnSb1bWzQPGA%40mail.gmail.com.

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

Re: Proposal: default to ATX-style headings in markdown output

[Leonard Rosenthol]

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

I'll also add my +1/me too to having a common style for headings.    And
given a choice, ATX.

Leonarsd

On Thu, Sep 3, 2020 at 12:21 PM BPJ <melroch-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> Den tors 3 sep. 2020 18:07Anton Shepelev <anton.txt-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> skrev:
>
>> John MacFarlane:
>>
>> > Currently in writing markdown (and commonmark) pandoc
>> > emits Setext-style (underlined) headings for levels 1 and
>> > 2, ATX_style (#) for the rest, unless the `--atx-headers`
>> > option is used to force ATX.
>> >
>> > Proposal: given that setext headings are becoming more
>> > uncommon, and in view of the ugliness of switching heading
>> > styles at level 3, default instead to ATX-style headings,
>> > unless a new `--setext-headings` option is used.
>> >
>> > Comments?
>
>
>> In my opinion, *any* uniform heading style is better than the
>> current inconsistent behavior.
>
>
> I concur emphatically.
>
> I prefer the ATX header
>> format
>
>
> So do I.
>
> even though it does not support the breaking of long
>> heading into multiple lines.
>>
>
> It could, if blank lines before and after were required (as I believe they
> are by default in Pandoc's Markdown.) Headings should be short though!
> However I have run into potentially troublesome cases when transcribing
> older texts. It would be good if at least hard linebreaks worked (which I
> believe is currently not the case.)
>
>
>> --
>> 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/20200903190619.e924ccd888daca8cef4460ea%40gmail.com
>> .
>>
> --
> 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/CADAJKhAM7MbY3GExs38hrApHrSntg87X04sKbJTnSb1bWzQPGA%40mail.gmail.com
> <https://groups.google.com/d/msgid/pandoc-discuss/CADAJKhAM7MbY3GExs38hrApHrSntg87X04sKbJTnSb1bWzQPGA%40mail.gmail.com?utm_medium=email&utm_source=footer>
> .
>

-- 
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/CALu%3Dv3LKDJpsEL-WoK8vre3uJAgrWrOeaRM0gy4RH1%2BkLm8Qkg%40mail.gmail.com.

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

Re: Proposal: default to ATX-style headings in markdown output

[Joseph Reagle]

On 9/3/20 12:51 PM, Leonard Rosenthol wrote:
> I'll also add my +1/me too to having a common style for headings.    And given a choice, ATX.

I always use ATX.

-- 
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/76597644-2488-3455-c21a-847e180e3b0c%40reagle.org.

Re: Proposal: default to ATX-style headings in markdown output

[Dmitry Safronov]

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

I also prefer ATX headings.

On Thursday, 3 September 2020 17:57:59 UTC+2, John MacFarlane wrote:
>
>
> Currently in writing markdown (and commonmark) pandoc emits 
> Setext-style (underlined) headings for levels 1 and 2, ATX_style 
> (#) for the rest, unless the `--atx-headers` option is used 
> to force ATX. 
>
> Proposal: given that setext headings are becoming more 
> uncommon, and in view of the ugliness of switching heading 
> styles at level 3, default instead to ATX-style headings, 
> unless a new `--setext-headings` option is used. 
>
> Comments? 
>
> Note: in principle we could also change the default just 
> for commonmark/gfm output, not for default markdown. 
> However, this would still require adding a --setext-headings 
> option. 
>

-- 
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/3baeae13-8eca-4464-ac84-84c988f7a91do%40googlegroups.com.

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

Re: Proposal: default to ATX-style headings in markdown output

[Denis Maier]

Am 03.09.2020 um 17:57 schrieb John MacFarlane:
> Proposal: given that setext headings are becoming more
> uncommon, and in view of the ugliness of switching heading
> styles at level 3, default instead to ATX-style headings,
> unless a new `--setext-headings` option is used.
>
> Comments?
>
Yes, please! I always use ATX-style headings. IMO, making this the 
default would be the better approach.

Re: Proposal: default to ATX-style headings in markdown output

[MyriaCore]

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

This is pretty sound to me, I get the sense that most markdown users tend 
to prefer ATX headings. 

On Thursday, September 3, 2020 at 4:28:27 PM UTC-4 Denis Maier wrote:

>
>
> Am 03.09.2020 um 17:57 schrieb John MacFarlane:
> > Proposal: given that setext headings are becoming more
> > uncommon, and in view of the ugliness of switching heading
> > styles at level 3, default instead to ATX-style headings,
> > unless a new `--setext-headings` option is used.
> >
> > Comments?
> >
> Yes, please! I always use ATX-style headings. IMO, making this the 
> default would be the better approach.
>

-- 
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/d8df1ef0-7a5a-4a07-8758-909a262e6119n%40googlegroups.com.

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

Re: Proposal: default to ATX-style headings in markdown output

[Pranesh Prakash]

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

I guess I'm in the minority — in that I don't always use atx-style 
headings.  I switch between atx-[1] and setext-style headings depending on 
the context.  In e-mails and in (plaintext) e-mail newsletters, I generally 
use setext-style headings since those are easily understood even by those 
who don't know about Markdown/atx.  However, in all my other writings, I 
use atx-style headings.  I would support making atx-style headings the 
default.

[1]: I've noticed that all Pandoc and CommonMark documentation uses "ATX", 
whereas the original 2002 blog post by Aaron Swartz uses "atx" as does John 
Gruber's 2004 blogpost on Markdown.

-- 
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/39d45d2d-952a-4af3-8f3b-e9af667f2a49n%40googlegroups.com.

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

Re: Proposal: default to ATX-style headings in markdown output

[Albert Krewinkel]

Pranesh Prakash writes:

> I guess I'm in the minority — in that I don't always use atx-style
> headings.  I switch between atx-[1] and setext-style headings depending on
> the context.  In e-mails and in (plaintext) e-mail newsletters, I generally
> use setext-style headings since those are easily understood even by those
> who don't know about Markdown/atx.  However, in all my other writings, I
> use atx-style headings.  I would support making atx-style headings the
> default.

I second this. Setext headers are great whenever it is likely that the
text will be read as unrendered plaintext. It's still what I prefer for
README files. But given the growing popularity of atx headers, it would
seem reasonable to make the latter the default.


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

Re: Proposal: default to ATX-style headings in markdown output

[Anton Shepelev]

Albert Krewinkel:

> Setext headers are great whenever it is likely that the
> text will be read as unrendered plaintext. It's still what
> I prefer for README files.

When I write true plain text that is not intended as the
source for a document processor, I dislike both Setex and
ATX headers.  My plain-text headers are usually one of these
forms:

   1. A simple numbered heading

                A CENTERED UPPERCASE HEADING

unless I go for something fancy, like this from a RedCode
newsletter:

This issue covers silk step interactions with a focus on the  tiny  set-
ting. Warm up your emulator!
_______
THEORY \________________________________________________________________

Barkley Vowk's new warriors 7b15f4b8-..., 4b0804b3-..., and 7fe57f81-...
have set the new standard for tiny papers, taking the 1st, 2nd  and  5th
places  at Koenigstuhl at the moment of publication. [...]

Whenever it is not markup, one need limit oneself to a pre-
existing format.

Re: Proposal: default to ATX-style headings in markdown output

[Anton Shepelev]

I wrote:

> Whenever it is not markup, one need limit oneself to a
> pre-existing format.

but meant "need not" instead of "need".

Re: Proposal: default to ATX-style headings in markdown output

[BPJ]

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

Den fre 4 sep. 2020 11:43Anton Shepelev <anton.txt-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> skrev:

> I wrote:
>
> > Whenever it is not markup, one need limit oneself to a
> > pre-existing format.
>
> but meant "need not" instead of "need".
>

So I understood, but README files on GitHub are a little special: they need
to look good both when rendered as Markdown on the website and when read as
plain text by someone who has cloned the repository locally. I however
usually assume that in the latter case people will know Markdown and how it
works.


> --
> 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/20200904124240.5d93260af90b10618677d8cb%40gmail.com
> .
>

-- 
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/CADAJKhD4VrGag2_tX_geU9au-1fi%3DQMb_BfW5fD342WQFMXv-Q%40mail.gmail.com.

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

Re: Proposal: default to ATX-style headings in markdown output

[John MacFarlane]

Seems to be a landslide in favor of changing the default.
I've added an issue:
https://github.com/jgm/pandoc/issues/6662