4 ms·

It's a good effort, but I'm afraid it isn't a good fit for me, three things stand out: 1) the use of # rather than underline for headings. That why I feel you

by e12e 6y ago

It's a good effort, but I'm afraid it isn't a good fit for me, three things stand out: 1) the use of # rather than underline for headings. That why I feel you loose the beauty of the source form - headers disappear visually without a smart editor - if you demand a smart/wysiwyg editor anyway... Might just use a sgml/xml/html subset. 2) one symbol references. This strikes me as overly limiting - why not alphanumeric string - or at the very least any number string? It feels a bit strange to be forced to count 1,2...9,a - and not be able to things like a1, a2, b11. 3) "no way to put backticks inside a code span." So, no (full) examples of restricted markdown in codeblocks? Not to mention the many languages that use backticks? I think you might be happier with reStructuredText than markdown: https://en.m.wikipedia.org/wiki/ReStructuredText https://en.m.wikipedia.org/wiki/ReStructuredText

gritzko 6y ago
3) That is for an inline code span only; can interrupt the span, put an escaped backtick, reopen the span. There is an example in the document. In fenced blocks, anything is accepted. 2) Yes, that mostly implies [1],[2]... pattern. Have to think of other solutions. 1) Well, yes. Aestetics is difficult to quantify. I use empty lines so headers stand out.
codethief 6y ago
> 1) the use of # rather than underline for headings. While in theory I understand the appeal of the "WYSIWYG" syntax of underlining headings, in practice I've always found it less readable than expected. Consider, for instance: I am a paragraph belonging to the previous section but it looks like the heading belongs to me. I am a heading indicating a new section ======================================= I am a paragraph belonging to the heading but the heading is weirdly separated from me. I am another paragraph belonging to the heading. In some editors/IDE, the underline even gets highlighted / boldfaced, thereby exacerbating this effect.
- chipotle_coyote 6y ago
  I very rarely see this style -- which comes from "Setext", IIRC, which might be patient zero of the "human readable plain text markup styles" -- in the wild anymore, and I suspect it's probably for the reasons you're describing here. I almost never use it myself, except in contexts where the "source file" is just as likely to be read as a rendered HTML version. README files are a good example. > In some editors/IDE, the underline even gets highlighted / boldfaced, thereby exacerbating this effect. I think a lot of editors just don't know about this style of heading, but they do know that a line of three or more dashes is used to create a horizontal rule, so they're trying to highlight that.
  - cannam 6y ago
    I had never heard of Setext! I do know that, before Markdown became popular, lots of programmers had their own similar format going on - this was mine, from 1998: Perl program https://sourceforge.net/p/rosegarden/code/HEAD/tree//branches/obsolete/oldtrunk-before-reorganisation/docs/web/support/faq/txt2html.pl https://sourceforge.net/p/rosegarden/code/HEAD/tree//branche... Documentation https://sourceforge.net/p/rosegarden/code/HEAD/tree//branches/obsolete/oldtrunk-before-reorganisation/docs/web/support/faq/txt2html.txt https://sourceforge.net/p/rosegarden/code/HEAD/tree//branche... I wonder now how much of this was picked up unknowingly from Setext-derived documents.
jasonpeacock 6y ago
There are many issues with the use of underline for headings: 1) Constantly fixing them to match the length of the heading, or just suck it up and always use the short form: My Heading ---- 2) You're typing twice as much. I can easily start a line with # to make a heading, vs write the heading line, then carriage return, then add a bunch of dashes to make it a heading. 3) This is the fatal flaw - you only get 2 levels of headings when using underlines.
layer8 6y ago
I always felt that the number of #s should increase with higher-level rather than with lower-level headings, for multiple reasons: - More #s mean a larger visual footprint, which would be more appropriate for higher-level headings (cf. larger font size in rich-text rendering, and of course the = and - underlines). This is what bothers me the most. - I tend to write documents bottom-up, starting with lowest-level headings, and higher-level headings are only introduced as the document evolves. Because I don’t know how many levels I’ll end up with, starting with a single # for the lowest level would work better. - Lower-level headings are more frequent than higher-level headings, so having to type less for them makes sense, as well as reducing the likelihood to get the # count wrong (because you usually know what is a bottom-level heading, or the next one up, and you don’t have to know how many levels there are overall). The existing convention mirrors the numbering levels of numbered headings, but I don’t find that visually convincing. It also matches the HTML h1-h6 elements of course, but nowadays that should be less of a concern. Another thought is that maybe the headings hierarchy should be unlimited in both directions, so that you are never forced to shift all headings. One possibility to achieve that could be: ### even higher level ## higher level # base level .# sub level .## sub-sub level .### sub-sub-sub level That syntax mirrors the magnitudes of decimal numbers. It’s just an idea I’ve been pondering, I’m not totally convinced myself. ;)
- gerikson 6y ago
  I like this idea, but that means you need to be able to decide what the "lowest" level is at the beginning (i.e. I seldom use anything below <h3>.)
  - layer8 6y ago
    Well, nothing keeps you from still starting with ###, so you have two spare levels to go down to if needed (## and #). Alternatively, that’s where the “negative” levels would come in (i.e. the .# levels above).

by e12e 6y ago

gritzko 6y ago

3) That is for an inline code span only; can interrupt the span, put an escaped backtick, reopen the span. There is an example in the document. In fenced blocks, anything is accepted. 2) Yes, that mostly implies [1],[2]... pattern. Have to think of other solutions. 1) Well, yes. Aestetics is difficult to quantify. I use empty lines so headers stand out.

codethief 6y ago

> 1) the use of # rather than underline for headings. While in theory I understand the appeal of the "WYSIWYG" syntax of underlining headings, in practice I've always found it less readable than expected. Consider, for instance: I am a paragraph belonging to the previous section but it looks like the heading belongs to me. I am a heading indicating a new section ======================================= I am a paragraph belonging to the heading but the heading is weirdly separated from me. I am another paragraph belonging to the heading. In some editors/IDE, the underline even gets highlighted / boldfaced, thereby exacerbating this effect.

chipotle_coyote 6y ago
I very rarely see this style -- which comes from "Setext", IIRC, which might be patient zero of the "human readable plain text markup styles" -- in the wild anymore, and I suspect it's probably for the reasons you're describing here. I almost never use it myself, except in contexts where the "source file" is just as likely to be read as a rendered HTML version. README files are a good example. > In some editors/IDE, the underline even gets highlighted / boldfaced, thereby exacerbating this effect. I think a lot of editors just don't know about this style of heading, but they do know that a line of three or more dashes is used to create a horizontal rule, so they're trying to highlight that.
- cannam 6y ago
  I had never heard of Setext! I do know that, before Markdown became popular, lots of programmers had their own similar format going on - this was mine, from 1998: Perl program https://sourceforge.net/p/rosegarden/code/HEAD/tree//branches/obsolete/oldtrunk-before-reorganisation/docs/web/support/faq/txt2html.pl https://sourceforge.net/p/rosegarden/code/HEAD/tree//branche... Documentation https://sourceforge.net/p/rosegarden/code/HEAD/tree//branches/obsolete/oldtrunk-before-reorganisation/docs/web/support/faq/txt2html.txt https://sourceforge.net/p/rosegarden/code/HEAD/tree//branche... I wonder now how much of this was picked up unknowingly from Setext-derived documents.

jasonpeacock 6y ago

There are many issues with the use of underline for headings: 1) Constantly fixing them to match the length of the heading, or just suck it up and always use the short form: My Heading ---- 2) You're typing twice as much. I can easily start a line with # to make a heading, vs write the heading line, then carriage return, then add a bunch of dashes to make it a heading. 3) This is the fatal flaw - you only get 2 levels of headings when using underlines.

layer8 6y ago

I always felt that the number of #s should increase with higher-level rather than with lower-level headings, for multiple reasons: - More #s mean a larger visual footprint, which would be more appropriate for higher-level headings (cf. larger font size in rich-text rendering, and of course the = and - underlines). This is what bothers me the most. - I tend to write documents bottom-up, starting with lowest-level headings, and higher-level headings are only introduced as the document evolves. Because I don’t know how many levels I’ll end up with, starting with a single # for the lowest level would work better. - Lower-level headings are more frequent than higher-level headings, so having to type less for them makes sense, as well as reducing the likelihood to get the # count wrong (because you usually know what is a bottom-level heading, or the next one up, and you don’t have to know how many levels there are overall). The existing convention mirrors the numbering levels of numbered headings, but I don’t find that visually convincing. It also matches the HTML h1-h6 elements of course, but nowadays that should be less of a concern. Another thought is that maybe the headings hierarchy should be unlimited in both directions, so that you are never forced to shift all headings. One possibility to achieve that could be: ### even higher level ## higher level # base level .# sub level .## sub-sub level .### sub-sub-sub level That syntax mirrors the magnitudes of decimal numbers. It’s just an idea I’ve been pondering, I’m not totally convinced myself. ;)

gerikson 6y ago
I like this idea, but that means you need to be able to decide what the "lowest" level is at the beginning (i.e. I seldom use anything below <h3>.)
- layer8 6y ago
  Well, nothing keeps you from still starting with ###, so you have two spare levels to go down to if needed (## and #). Alternatively, that’s where the “negative” levels would come in (i.e. the .# levels above).