Side-marked instead of fenced divs?

[jgm]

Fenced divs look like this:

::::
Paragraph

:::
Nested div.

Paragraph
:::
::::

Compare that with side-marked divs:

: Paragraph
:
:: Nested div.
::
:: Paragraph

The side-marked syntax has several advantages:

1. It is local. You can determine on a line by line basis whether you're in a div. With fences, this might depend on a line in a file 10,000 lines above...
2. It is consistent with other syntax for block containers in djot: block quotes and lists (neither of which uses fences).
3. Nesting is perspicuous. It's obvious right away that you have one div inside another; you don't need to look back at earlier lines or visually match up strings of columns that may look very similar.
4. We avoid the rough edge that a closing fence (unlike other block-indicating constructions) can interrupt a paragraph (The closing delimiter of a div block can interrupt a paragraph #291).

People generally prefer to write fenced divs, but of course our emphasis is on readability. Note that writing side-marked divs is not at all hard with proper editor support, and complex divs are not something one normally needs in, e.g. a web form, where one lacks proper editor support.

Thoughts?

[faelys]

FWIW, I love the idea, I find the advantages much stronger than the ease-of-writing drawback.

The advantage 2 is a bit weakened by the fenced verbatim blocks, but the special syntax is justified by the fact that they don't nest and keeping the verbatim bytes contiguous and unprocessed.

The advantage 3 is a bit weakened by the interaction with hard wrapping, if it works like block quotes. I don't expect to find the end of an inner div without syntax hilighting or writer cooperation.

But even with such weakening, I'm still massively in favor of side-marked divs, be it in addition or in replacement of fenced divs.

[vassudanagunta]

Don't some of those points make a similar case against lazy paragraph continuation, including the points about readability over writability and proper editor support?

Conversely, the main case for fenced divs, that they are easier to write, is the same justification for laziness.

Not trying to conflate separate issues, but wondering if there is philosophical or practical position that justifies one but not the other.

Note that nesting is no longer perspicuous for side-marked when laziness is occurs:

: Paragraph
:
:: Nested
: div.
:
: Paragraph

[bpj]

The main disadvantage with side-marking as far as I am concerned is that it makes it hard to reflow text/format paragraphs without first removing the side-marking, which shouldn't be needed. I already think side-marked block quotes a nuisance for this reason. It's not hard to write the first time, but to go back and edit is very hard! There is a reason why block comments were invented!

It is true that it is easier to see how side-marked blocks are nested but
it becomes hard to remove one level of nesting should you want to do that, especially in the middle. Imagine having to use something like :'<,'>s/^::\zs:\ze://!

[jgm]

That's a good point, though with proper editor support reflowing should be possible to do automatically. For example, in Emacs with markdown mode it "just works."

Similarly, removing a nesting level, even in the middle, is just a matter of selecting a vertical column and deleting it. Easy in any powerful editor.

[matklad]

This is quiet a departure from the existing syntax. I did a small informal test-drive on my blog (which has very few divs) and on my presentation (which uses divs (but not nested divs) heavily).

I must say that I like side-marked version quiet a bit more! Some things I've noticed:

• a verbatim block nested inside the side-marked div looks weird, but that's already so with quoted verbatims
• fences, I tend to add blank lines around the content for readability. With sidemarking, I now find that I can easily delete those extra lines. Vertical space is also saved because yuo don't need a line for closing :::
• additionally, another problem with fences is that if you have several short fenced divs one after another, you can't say which things are inside and which are outside of a div:

A
:::
B
:::
C
:::
D
:::
E

side marking makes that obvious:

A

: B

C

: D

R

• I love that fences have a nice syntactic place for class/tag name. Almost all my divs are marked as ::: note, ::: figure or some such, and

::: note
foo
:::

reads better than

{.note}
: fooo

I'd love the side-marked version to preserve this syntactic place for the main class.

[matklad]

Something like

:.note
: foo

would make sense to me I think. Having attributes syntactically inside the div also helps with disambiguation:

{.ineer_or_outer}
:: inner
:
: outer

vs

:.outer
::.inner
:: inner
:
: outer

[jgm]

Hm, I hadn't thought about the ambiguity in where the attribute belongs in a case like that. That may be a strike against the side-marking syntax. Bringing the attributes inside could in principle fix that, but I think there are some big drawbacks. The attribute syntax would have to be different, to distinguish this from the case where the attribute goes on the first block in the div. Your suggestion achieves that by introducing a special syntax for a single class only. Maybe one could expand this to something like a braceless attribute line. But then this breaks the uniformity of attribute syntax.

[faelys]

Maybe I'm weird or not thinking it through, but for me it's obvious:

{.obviously-outer}
:: inner
:
: outer

and

:{.obviously-inner}
:: inner
:
: outer

On the other hand, if we break backwards compatibility, I think a case could be made for attributes inside blocks rather than outside, maybe with a slightly different syntax if we want a transition period.

{.paragraph_class}
paragraph body

>{.side_marked_class}
> {.inner_paragraph_class}
> lorem ipsum

-{.list_item_class} item text
- second item
- but where should the list class go?

---{.class-for-contentless-block-which-breaks-things-a-bit}

```{.maybe-at-the-start}
verbatim doesn't fit that well either
```{.maybe-at-the-end}

ETA: maybe having the attributes on the inside but without the space between the marker and the {, to help disambiguate visually the side-marked-case and make it easier for the parser.

[jgm]

Maybe I'm weird or not thinking it through, but for me it's obvious.

You're right, it is obvious! (now that I think about it :)) Good.

I would like to avoid too much complexity, so currently not too keen on the attributes-inside idea.

[faelys]

I would like to avoid too much complexity, so currently not too keen on the attributes-inside idea.

I don't think it adds any intrinsic complexity, though I agree a transition with both syntax or re-learning the new syntax is a significant burden that might be too large for the advantages (I'm really bad at estimating such compromises, I leave to you).

I feel the main advantages are:

• attributes of a block are cognitively part of the block, so there is less cognitive load if they are also visually inside the block (the possible ambiguity a few comments above a good example)
• the construction of marker immediately followed by braces is consistent with inline attributes (maybe the consistency could be seen as a confusion if the distinction between block attributes and inline attributes matter, I feel they have enough in common to benefit from the consistency)
• it improves my earlier suggestion of attribute parsing without backtracking, if we close the brace implicitly at the end of the block and if we add fallback semantics to unrecognized attributes elements (e.g. treating words without = as null-valued keys, or a special "tag" set).
• the opening brace instead of the mandatory blank after markers is easy to parse
• in some parser architectures, adding attributes to an existing block object is easier than adding attributes to a "pending-attributes" special object before the corresponding block object even exists.

[rauschma]

I find both useful. For long stretches of text, fenced div blocks make editing easier and cause less visual clutter – e.g. when using CSS to layout HTML slides:

:::::: side-by-side

::: left
Several
lines
of
text
:::

::: right
Several
lines
of
text
:::

::::::

For things such as notes, this seems neat:

{.warning}
: **Don’t do this!**
:
: Things can go wrong!

With this kind of quoting, I’d avoid nesting, though.

[jgm]

I don't think I'd be inclined to offer both fenced and side marked divs. The idea would be to move to side-marked divs to avoid fenced divs, for the reasons noted above.

[rauschma]

If I had to choose, I’d vote in favor of fenced divs – for these reasons:

1. My experience with writing Markdown-based slides:
   • Side marks are a lot of visual clutter for longer texts.
   • It’s not as important to know I’m inside a div block.
2. I have always enjoyed writing HTML block elements and LaTeX environments – both are fenced constructs.

Interestingly, HTML elements and LaTeX environments have one benefit over both fenced divs and side-marked divs: When an HTML element or a LaTeX environment ends, its name is mentioned again. That’s important if you nest. In djot, that could look like this:

(.side-by-side)

(.left)
Several
lines
of
text
(/.left)

(.right)
Several
lines
of
text
(/.right)

(/.side-by-side)

Or like this:

[.side-by-side]

[.left]
Several
lines
of
text
[/.left]

[.right]
Several
lines
of
text
[/.right]

[/.side-by-side]

[jgm]

We handle nesting by using different length fences. It is a similar system.

[rauschma]

True, but I like seeing what a delimiter closes at the end.

Apologies for throwing all of these ideas out there: I’m experimenting a lot at the moment. You probably had that phase a long time ago. I appreciate the feedback!

[uvtc]

Two issues with using : as a side-marker for divs:

• it looks like the definition list item marker, and
• a : just does not look good as a side-marker.

There's no rule that says: "if there's both a fenced and a side-marked syntax for the same thing, then both should use the same marker character." In fact they should not, since a good fence character does not make a good side-marking character (for example, code blocks use backticks/tildes as a fence, but space/indentation as a side-marker).

The best-looking side-marking character is, hands down, the pipe |. I realize that it's already being used for pipe-tables, but there doesn't appear to be any ambiguity, since tables need at least 2 pipes on a line (and also ends the line with a pipe).

The | side-marker couldn't be used for divs in Pandoc since it was already used for "line blocks", but it can be used in djot, and I think it would be a perfect fit. I mean, just look at this:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
: eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
: enim ad minim veniam, quis nostrud exercitation ullamco laboris
: nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
: reprehenderit in voluptate velit esse cillum dolore eu fugiat
: nulla pariatur. Excepteur sint occaecat cupidatat non proident,
: sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

| Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
| eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
| enim ad minim veniam, quis nostrud exercitation ullamco laboris
| nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
| reprehenderit in voluptate velit esse cillum dolore eu fugiat
| nulla pariatur. Excepteur sint occaecat cupidatat non proident,
| sunt in culpa qui officia deserunt mollit anim id est laborum.

The | side-marker is so good I think it's reasonable to use it for two things (tables and divs). It's very natural to use for divs and I think would catch on quick.

[bpj]

I agree that side marking makes for a rather terrible editing experience, but IMNSHO so does indentation. Significant indentation in (nested) lists is already problematic enough!

All programmers have experienced how after more than three or four levels of indentation the indentation tends to crowd out the content! While it is especially bad for me because I have reduced lateral vision on my right eye I do think it easily becomes a problem for anyone. It already is with lists, especially definition lists where I often have to nest three or four levels deep and then item lists and sometimes divs inside them. Unfortunately deeply nested divs aren't that uncommon.

The experience with indented code blocks and even lists without nested code blocks in Markdown is that you tend to get confused as to how many levels of indentation/how many spaces are needed at any given point. When programming I generally can make do with two-space indentation levels but with Markdown or djot less than four spaces per level doesn't work in my experience, if only because you need to have room for at least one digit + punctuation list markers and sometimes two digits, not to speak about Roman numerals!

[chrisjsewell]

All programmers have experienced how after more than three or four levels of indentation the indentation tends to crowd out the content!

and, as per programming, I would suggest if your documentation starts to become this nested, then you're probably doing something wrong

Unfortunately deeply nested divs aren't that uncommon.

again I would suggest this is wrong, if you are nesting your comment at multiple levels, then this is a bad reading experience

[matklad]

To be a bit contrary, I have to say side-marked would be an absolutely terrible editing experience; no editors support this properly, and pragmatically they never will.

As a counter-argument, most programming languages use side-marking for documentation comments (//), and editing them just works? Reflowing text at column doesn't mess up side-markings, pressing enter adds // automatically, etc.

[chrisjsewell]

and editing them just works?

Well... I beg to differ 😅

Firstly, docstrings are generally not intended to be too big; you're not writing a whole document

Secondly, yes in most editors you can press enter and the new line will also have the comment prefix,
then the key-binding Cmd+/ comments out/in a block, i.e. adds/removes the comment prefix for that language,
Of note, this is only the case if it is set for that language

BUT as a counter-counter argument:

In Rust you have the idea of normal comments //, docstring comments ///, and module level docstrings //!
but since the editor has only one key-binding for commenting out/in things, which is bound to //,
it is flippin' infuriating, when you want to comment in/out docstring comments (you have to manually add/remove the extra /)

So... how is your editor going to deal with increasing/decreasing the nesting level of your divs?
with whitespace this is simple, you just use TAB / Backspace

[jgm]

The whitespace idea (treating divs as a kind of list) is an intriguing one indeed. I will have to think about that.

[uvtc]

Just an additional thought here: the more I think about it, the more I like and appreciate that, when there is a fenced syntax, you can use as long a fence as you like (of course, with the rule about how outer fences must be longer than nested inner ones):

Hi.

{.note}
::::::::::::::::::::::::::::::::::::::::::::::::::::
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip
ex ea commodo consequat.
::::::::::::::::::::::::::::::::::::::::::::::::::::

Some code here:

~~~~~~~~~~~~~~~~~~ my-lang
for i in arr {
    # comment
    print(i);
}
~~~~~~~~~~~~~~~~~~

Bye.

So, even if a given character isn't great as a fence marker, at least if you put a bunch of them, it looks pretty good regardless.

Aside: of course, just as the all-time best ascii side-marker character is the pipe |, the all-time best ascii fence character is the dash - (sorry, my hands are tied here -- these are simply incontrovertible facts, like how "Empire Strikes Back" is and always will be the best Star Wars movie). So, div could look like this:

Hi.

{.note}
----------------------------------------------------
Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et
dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip
ex ea commodo consequat.
----------------------------------------------------

Bye.

Anyhow, I mention this for 3 reasons:

1. Even fences using a suboptimal ascii character can look pretty good if you put in a long line of them.
2. Not that anyone suggested it, but it would be bad to ever remove the fenced code block syntax in favor of a side-marked syntax. This is not only because it's just too common and convenient to copy/paste in code blocks, but also because the ~~~ looks great as a fence, and arguably even better when a little longer ~~~~~~~~~~.
3. re. issue Metadata #35 , it would look pretty good to fence a metadata block with +, as in:

Hi.

++++++++++++++++++++++++++
author =   "Your Name"
title =    "Somesuch"
subtitle = "And so on and so forth"
date =     "2024-04-24"
intensity-level = "42"
++++++++++++++++++++++++++

Bye.

[terefang]

but IIRC --- is already a thematic break along with ***

[uvtc]

I think the syntax of a string of contiguous dashes is too valuable to use for a thematic break --- especially since we already have *** for that.

Aside: I like how some books have a centered * * * in between paragraphs that make a big jump in topic. Would be nice if djot did this:

• * * * be for that cool centered * * *, and
• - - - for an HR (horizontal rule)

(to me, the former is more what I'd call a "thematic break" rather than the latter).

[vassudanagunta]

@uvtc a thematic break is an abstract structural element while a horizontal rule is a concrete visual element. A thematic break could be render with a horizontal rule, or some special glyph such as fleuron, centered as you suggest. I think djot, like markdown, should stick to abstract elements.

The search results for "leaf glyph break text" shows that there are many ways to render breaks, and other than abstractly classifying different kinds of breaks using djot's attribute syntax, i don't think djot should get involved.

[terefang]

@uvtc a thematic break is an abstract structural element while a horizontal rule is a concrete visual element. A thematic break could be render with a horizontal rule, or some special glyph such as fleuron, centered as you suggest. I think djot, like markdown, should stick to abstract elements.

The search results for "leaf glyph break text" shows that there are many ways to render breaks, and other than abstractly classifying different kinds of breaks using djot's attribute syntax, i don't think djot should get involved.

i can only second that this separation of concerns should be kept as this keeps things more logical (at least for me).

[uvtc]

Thanks. Good point.

Back to @jgm 's comment about ------, I think it's better to use only the version with interspersed spaces (- - -) for the thematic break, and use the contiguous dashes as a fence marker for divs.