djot
djot copied to clipboard
verbatim blocks tildes syntax supported?
I notice that, in addition to triple-backticks, I can get verbatim blocks with tildes as well:
~~~
works for
code blocks
~~~
but it's not mentioned in the syntax reference.
Will djot continue to support the triple-tilde syntax for code blocks?
Incidentally, if triple-tilde delimiters were no longer used for code blocks, maybe they could be used for figures (see #31).
Not sure. On the one hand, there's an argument for keeping it simple and just having one form.
I've always thought that the tildes look way better for fencing than the backticks, especially when viewed with lines/paragraphs around them:
this
~~~
line won
line too
line tree
~~~
vs
```
line won
line too
line tree
```
bye
The backticks are floating up too high on the top of the block, and too squeezed in on the bottom. Any time I write them I have to go back and check, "wait, did I add a blank line under that block?" The tildes look pleasingly symmetric.
Although I usually push for max consistency, this is one case where one syntax looks superior enough to another that I'd support and actively promote the ~~~
syntax (while only possibly supporting the ```
syntax for legacy compatibility with other markdowns).
I think that any glyphs used for fencing (block delimiters) should be "vertically balanced", and at least a little wide, for example:
===
alpha beta
gamma delta
===
---
alpha beta
gamma delta
---
~~~
alpha beta
gamma delta
~~~
or even
@@@
alpha beta
gamma delta
@@@
&&&
alpha beta
gamma delta
&&&
and not
,,,
alpha beta
gamma delta
,,,
...
alpha beta
gamma delta
...
^^^
alpha beta
gamma delta
^^^
___
alpha beta
gamma delta
___
Yes, the vertical balance issue was why in our original discussions of fenced code blocks (long before GitHub implemented them), the PHP Markdown designer and I decided on tildes.
However, there are a couple things to be said in favor of backticks:
- well established now
- we already use backticks for inline code, so it "makes sense'
- you don't have to press shift to type a ` (at least on US keyboards)
Against backticks, there is a potential ambiguity between inline and block code interpretations in markdown:
Is this a
``` hard
wrapped
``` inline
code span or
a code block?
However, djot avoids that ambiguity by requiring blank lines around the code block.
[backticks are] well established now
Github md has supported the tildes too, as far back as I can remember.
we already use backticks for inline code, so it "makes sense'
Yeah, I see that it's consistent in that way. But I think when you have both an inline syntax and a fenced block syntax for a particular style, it makes sense to use a different character for the fences if it doesn't look right as a fence.
I think the success of light markup languages is directly proportional to how much people like reading them in plain text.
Two very valuable fences still available for djot syntax are ---
and ===
. Those both look excellent for fences, and I hope djot uses them for something.
In principle we could use ---
instead of ```
for code blocks, if we were willing to remove that as a possible syntax for thematic breaks.
I've never used ---
for a thematic break / HR. I thought using either ***
or * * *
was pretty universal. Also, dashes are used in a few other places already (en-dashes, em-dashes, table separator line). I think it would be good to remove them from thematic break syntax, and then use ---
as some kind of block delimiter.
Do you prefer ---
to ~~~
for verbatim blocks? (Since -
is more plain and straight than ~
, it does make me think of verbatim more than ~
does... I could get used to ---
pretty quickly.)
If you went with ---
for verbatim blocks, then maybe ~~~
could be used for figures (#31).
Or maybe :::
could be expanded into a more general syntax pattern for blocks, like:
:::[&] figure-3
some stuff
about the figure
:::
:::[@] some-citation
some stuff about
the citation
:::
:::[+]
metadata
block here
:::
:::[|]
A line block is here.
This one line is indented.
And now we are done.
:::
Re. metadata block ideas, see #35.
In the above example ideas, I don't include a list-table block (#27) because I think @bpj 's idea of using ===
is good.
I think it's — for better or worse — best to stick with backticks for verbatim blocks since that is what most Markdown implementations use, to avoid confusion. Given that ---
is used for em-dash it should perhaps not be used for anything else.
As for thematic breaks it would probably be a good idea to make whitespace between the characters mandatory.
Given that --- is used for em-dash it should perhaps not be used for anything else.
Since djot requires blank lines around blocks, and since it's unlikely to use a ---
on a line by itself — especially at the start or end of a paragraph — I'd say there's little to no ambiguity using ---
to fence at least some sort of block. I think it's too good of a fence marker not to use.
Anyhow, I'm happy if I can at least keep using ~~~
for a code fence marker (and raw content block fences). I think the ```
looks bad for block fencing and avoid it.
@jgm wrote:
In principle we could use
---
instead of```
for code blocks, if we were willing to remove that as a possible syntax for thematic breaks.
I think it's a great idea to remove ---
from thematic break syntax. The stars work fine, and by rule/goal # 11, djot doesn't need multiple ways to get an HR — especially since ---
doesn't look any better for an HR than ***
.
Following the argument of consistency between single and triple backticks, it's worth noting that the syntax for generic blocks could also be made more consistent with that of generic inline spans, [lorem ipsum]{foo="bar"}
, if they used the same delimiters for the content, instead of :::
— like this:
{foo="bar"}
[[[
lorem ipsum
]]]
But I'm not sure the consistency would be worth the additional compatibility break from the ```
and :::
as block indicators, which are common in various markup languages by now.
In principle we could use
---
instead of```
for code blocks, if we were willing to remove that as a possible syntax for thematic breaks.
I've never used
---
for a thematic break / HR. I thought using either***
or* * *
was pretty universal.
Cross-referencing #59, which proposes the reverse, i.e. keeping ---
and removing ***
as syntax for thematic breaks. That said, the premise of that issue (having two syntaxes for the same thing being a violation of goal 11/TIMTOWTDI) is consistent with removing ---
in favor of ***
as suggested here.
Whenever I encounter alternative ways to delimit code I always assume that they are there to help you avoid the use-mention problem, something which is especially easy to run into for code content. But I haven’t seen that as a justification of this feature anywhere (it’s not in the design rationale part of the readme).
So an alternative to using X amount of backticks. Which inline looks especially bad. (Five backticks and two spaces in order to display one, is it? In StackOverflow MarkDown anyway, which I guess is CommonMark.)
I would formulate that as a design rationale:
- It should always be simple to quote arbitrary code.
And design rationale № 11 (last in the list) accomodates such rules:
- The syntax should be kept as simple as possible, consistent with these goals.
you don't have to press shift to type a ` (at least on US keyboards)
On my layout, the only way to type backtick is AltGr+,
(which is not marked on most keyboards), and then space, because it's a dead key. Anecdotally, a lot of people around me can't figure out how to type a backtick without help.
Typing a backtick fenced block for me involves pressing AltGr+,
six times (needs to be an even number because dead key), left arrow three times, type language name and enter. Tilde blocks are way more straightforward.
On my layout, the only way to type backtick is
AltGr+
On French keyboards, backtick is AltGr+7
and tilde is AltGr+2
-- so none are "straightforward" (though marked on the keyboard). That's true too for brackets (curly and squared). I am not sure, however, that the design of a (markup or not) language should favor a given keyword localization/layout. And there are solution to re-map a keyword layout, notwithstanding editor's auto-completion suggesting the next 2 backticks or tildes once one is typed at the beginning of the line, etc.
I am not sure, however, that the design of a (markup or not) language should favor a given keyword localization/layout.
The only way to do that for code blocks is to give some options. Because (as the discussion has revealed) backticks are hard to write on some keyboards.
It's not my personal experience since I don't use dead keys, but I can't imagine interspersing some diacritic-heavy language (using dead keys) and things like code blocks without some assistance like textual insertion.