In recent years I have been thinking a lot more about tools vs. conventions. Once upon a time, the ubiquitous means of transferring arbitrary data structures was XML. It was a perfectly fine...
In recent years I have been thinking a lot more about tools vs. conventions.
Once upon a time, the ubiquitous means of transferring arbitrary data structures was XML. It was a perfectly fine standard; a bit verbose, but you could do so much interesting things with them. It was an important early web technology with many interesting add-ons like DTDs and XSL-T.
But it absolutely sucked to write out. And so the web decided to go with the barely-a-standard JSON instead. Nowadays there are many projects that think that even that is too hard and we have things like YAML. And I was all for it because it was easy to adopt those conventions.
And then a short while ago I learned that XML wasn’t something you were supposed to write. It was something that was supposed to be written for you with tools. Looking into enterprise Java applications, I could see there were plenty of tools to deal with exporting and importing XML data; doing so was very commonplace and there were parts of Java that were dedicated specifically to making the creation of those tools as easy as possible.
Looking at document markup languages makes me wonder about the tools versus conventions idea again. We already have a ton of very mature tools for writing HTML - the usual endpoint of these markup languages. Not only do you have the ability to write directly in HTML markup very quickly with tools built into most code editors, but you also have the ability to use a multitude of WYSIWYG editors and avoid actually needing to touch any code.
But of course if you’re trying to have multiple endpoints, or in some cases if HTML doesn’t work for you, that is when new conventions make sense. Documentation in code makes more sense because of this.
Both tools and conventions have their own sets of strengths and limitations. Tools are rigid in what they can do for you, and conventions force you to do things in particular manners. That’s what got me down this train of thought, in a way; Djot would not exist if the conventions of other text markup systems made sense for the people who work on it. Heck, that’s part of why there are so many different variations of markdown to begin with.
… Well, I don’t think I said anything productive here. Goodnight everyone.
I gotta agree with random quoted guy, sublist newlines make this project dead to me. Weird design decision — I wonder what they did that for.
Exactly, the sublist newline stuff is a total nonstarter for me. Sorry, I guess I’ll run a markdown parser that takes an extra second or whatever to run.
I gotta agree with random quoted guy, sublist newlines make this project dead to me. Weird design decision — I wonder what they did that for.
On Djot's GitHub page under the Rationale section it says this: It later says this: I don't like it either, to be honest. To me it feels like they're prioritizing hard-wrapping over the actual...
The syntax should be friendly to hard-wrapping: hard-wrapping a paragraph should not lead to different interpretations, e.g. when a number followed by a period ends up at the beginning of a line. (I anticipate that many will ask, why hard-wrap at all? Answer: so that your document is readable just as it is, without conversion to HTML and without special editor modes that soft-wrap long lines. Remember that source readability was one of the prime goals of Markdown and Commonmark.)
It later says this:
Block-level elements can't interrupt paragraphs (or headings), because of goal 7. So in djot the following is a single paragraph, not (as commonmark sees it) a paragraph followed by an ordered list followed by a block quote followed by a section heading:
My favorite number is probably the number
1. It's the smallest natural number that is
> 0. With pencils, though, I prefer a
# 2.
I don't like it either, to be honest. To me it feels like they're prioritizing hard-wrapping over the actual syntax of the language and that seems like a bad choice. Thankfully the language isn't anywhere near a 1.0 version yet, and there has been a lot of pushback against this design decision, so maybe it will be revised in the future?
It shows that, at least back then, they used Doom Emacs. That's annoying, because I also use Emacs, and I can confidently say text wrapping is a solved problem there (and in pretty much every other editor ever, including Notepad on Windows).
In the maintainer's screenshot, they show two examples, of three sentences each. In the first example, the three sentences are soft-wrapped lines with toggle-word-wrap enabled. Specifically, the soft-wrapped lines are two ordered-list lines and a blockquote line. Notice how, for each of those three sentences, the second line of each sentence (the part of the sentence that has been wrapped) starts at the absolute left edge of the frame (or "window", in today's parlance).
In the second example, the sentences are hard-wrapped. The maintainer specifically pressed return to enter a newline after it, an, and how. The maintainer also manually prefixed the second lines of each sentence with tabs and, in the blockquote sentence, a > character.
This sort of manual formatting is stupidly tedious and, more importantly, not needed. Emacs has built-in functions that handle all of these things. I would know, because I have them set to automatically enable every time I am editing a Markdown file, and that's how I am writing this comment: in a Markdown file using Emacs.
I would much rather have Emacs handle soft-wrapping for me, than have to hard-wrap everything myself, which becomes extremely annoying to manage when you go back and edit large paragraphs of text.
(Emacs does have a function, fill-region, that automatically hard-wraps (inserts line breaks) into a region of text you have highlighted. It decides at what length (aka column) to insert a break based on the value of the fill-column variable, which I believe defaults to 78. I have it set to 95, because I have an ultrawide display. This function is very useful in situations where you need to write a lot of text, but don't want to soft-wrap it, such as an extensive comment or explanation in a code file. I don't think regular text files, like Markdown, make sense for hard-wrapping though.)
Just for fun, here's a list of screenshots I took with various Emacs modes enabled and disabled, to hopefully show what the effect of each mode is:
Emacs with toggle-word-wrap disabled. It looks pretty ugly. Emacs only wraps lines after they reach the end of the frame, even if that means cutting a word in half.
Emacs with visual-line-mode enabled. Visually, this just seems like it gets rid of the arrows on the fringes of the frame, but visual-line-mode also automatically enables toggle-word-wrap and changes how some commands function to be more consistent with visual (versus logical) lines.
Emacs with visual-wrap-prefix-mode enabled. This was recently integrated into Emacs 30, and automatically handles indenting and prefixing the second and subsequent wrapped lines of any paragraph.
Emacs with visual-fill-column-mode enabled. This is an external package for Emacs that I find very useful. Notice in this image how my Emacs frame (again, what most people call a "window" today) is very wide, but Emacs still soft-wraps the text at a defined length (in my case, 95-ish columns).
I have an ultrawide monitor, and usually reserve two-thirds of it for Emacs during a writing session. When I don't have a second window open in Emacs, like in that screenshot, then my text would normally span the entire width of the frame, and be too long to edit comfortably. Visual Fill Column solves that problem. It also provides an easy way to visually center text, like a lot of the "zen modes" in other editors.
You don't even need hard-wrapping to want a blank line preceding lists. Your editor can soft-wrap a piece of text to look like the above example and now it looks all ambiguous if you don't require...
You don't even need hard-wrapping to want a blank line preceding lists. Your editor can soft-wrap a piece of text to look like the above example and now it looks all ambiguous if you don't require a blank line to precede a list. In general, I feel that block-level elements should be preceded by a blank line, with the exception of list items (which are even occasionally used as span-level elements in old-timey texts!)
My beef is probably with the tight/loose list distinction, where I don't see how you can specify whether a list with a single list item should be tight or loose. My first thought is that list items should be tight by default unless they contain multiple paragraphs or block-level elements, in which case that item is necessarily loose.
In recent years I have been thinking a lot more about tools vs. conventions.
Once upon a time, the ubiquitous means of transferring arbitrary data structures was XML. It was a perfectly fine standard; a bit verbose, but you could do so much interesting things with them. It was an important early web technology with many interesting add-ons like DTDs and XSL-T.
But it absolutely sucked to write out. And so the web decided to go with the barely-a-standard JSON instead. Nowadays there are many projects that think that even that is too hard and we have things like YAML. And I was all for it because it was easy to adopt those conventions.
And then a short while ago I learned that XML wasn’t something you were supposed to write. It was something that was supposed to be written for you with tools. Looking into enterprise Java applications, I could see there were plenty of tools to deal with exporting and importing XML data; doing so was very commonplace and there were parts of Java that were dedicated specifically to making the creation of those tools as easy as possible.
Looking at document markup languages makes me wonder about the tools versus conventions idea again. We already have a ton of very mature tools for writing HTML - the usual endpoint of these markup languages. Not only do you have the ability to write directly in HTML markup very quickly with tools built into most code editors, but you also have the ability to use a multitude of WYSIWYG editors and avoid actually needing to touch any code.
But of course if you’re trying to have multiple endpoints, or in some cases if HTML doesn’t work for you, that is when new conventions make sense. Documentation in code makes more sense because of this.
Both tools and conventions have their own sets of strengths and limitations. Tools are rigid in what they can do for you, and conventions force you to do things in particular manners. That’s what got me down this train of thought, in a way; Djot would not exist if the conventions of other text markup systems made sense for the people who work on it. Heck, that’s part of why there are so many different variations of markdown to begin with.
… Well, I don’t think I said anything productive here. Goodnight everyone.
I gotta agree with random quoted guy, sublist newlines make this project dead to me. Weird design decision — I wonder what they did that for.
On Djot's GitHub page under the Rationale section it says this:
It later says this:
I don't like it either, to be honest. To me it feels like they're prioritizing hard-wrapping over the actual syntax of the language and that seems like a bad choice. Thankfully the language isn't anywhere near a 1.0 version yet, and there has been a lot of pushback against this design decision, so maybe it will be revised in the future?
What kind of editor is this guy using for this to be an issue? I struggle to think of what environment this is an issue for.
Back in November 2022, the maintainer responded to an issue about this with a screenshot of their editor:
https://user-images.githubusercontent.com/3044/203364236-22465172-ed55-404c-9926-23ca29d883e2.png
It shows that, at least back then, they used Doom Emacs. That's annoying, because I also use Emacs, and I can confidently say text wrapping is a solved problem there (and in pretty much every other editor ever, including Notepad on Windows).
In the maintainer's screenshot, they show two examples, of three sentences each. In the first example, the three sentences are soft-wrapped lines with
toggle-word-wrapenabled. Specifically, the soft-wrapped lines are two ordered-list lines and a blockquote line. Notice how, for each of those three sentences, the second line of each sentence (the part of the sentence that has been wrapped) starts at the absolute left edge of the frame (or "window", in today's parlance).In the second example, the sentences are hard-wrapped. The maintainer specifically pressed
returnto enter a newline afterit,an, andhow. The maintainer also manually prefixed the second lines of each sentence with tabs and, in the blockquote sentence, a>character.This sort of manual formatting is stupidly tedious and, more importantly, not needed. Emacs has built-in functions that handle all of these things. I would know, because I have them set to automatically enable every time I am editing a Markdown file, and that's how I am writing this comment: in a Markdown file using Emacs.
Here is what my editor looks like right now: https://i.horizon.pics/AGbXq05Z8g.png
I would much rather have Emacs handle soft-wrapping for me, than have to hard-wrap everything myself, which becomes extremely annoying to manage when you go back and edit large paragraphs of text.
(Emacs does have a function,
fill-region, that automatically hard-wraps (inserts line breaks) into a region of text you have highlighted. It decides at what length (aka column) to insert a break based on the value of thefill-columnvariable, which I believe defaults to78. I have it set to95, because I have an ultrawide display. This function is very useful in situations where you need to write a lot of text, but don't want to soft-wrap it, such as an extensive comment or explanation in a code file. I don't think regular text files, like Markdown, make sense for hard-wrapping though.)Just for fun, here's a list of screenshots I took with various Emacs modes enabled and disabled, to hopefully show what the effect of each mode is:
toggle-word-wrapdisabled. It looks pretty ugly. Emacs only wraps lines after they reach the end of the frame, even if that means cutting a word in half.toggle-word-wrapenabled. This looks better, and I think is what most people expect when they hear "word wrap".visual-line-modeenabled. Visually, this just seems like it gets rid of the arrows on the fringes of the frame, butvisual-line-modealso automatically enablestoggle-word-wrapand changes how some commands function to be more consistent with visual (versus logical) lines.visual-wrap-prefix-modeenabled. This was recently integrated into Emacs 30, and automatically handles indenting and prefixing the second and subsequent wrapped lines of any paragraph.visual-fill-column-modeenabled. This is an external package for Emacs that I find very useful. Notice in this image how my Emacs frame (again, what most people call a "window" today) is very wide, but Emacs still soft-wraps the text at a defined length (in my case, 95-ish columns).I have an ultrawide monitor, and usually reserve two-thirds of it for Emacs during a writing session. When I don't have a second window open in Emacs, like in that screenshot, then my text would normally span the entire width of the frame, and be too long to edit comfortably. Visual Fill Column solves that problem. It also provides an easy way to visually center text, like a lot of the "zen modes" in other editors.
You don't even need hard-wrapping to want a blank line preceding lists. Your editor can soft-wrap a piece of text to look like the above example and now it looks all ambiguous if you don't require a blank line to precede a list. In general, I feel that block-level elements should be preceded by a blank line, with the exception of list items (which are even occasionally used as span-level elements in old-timey texts!)
My beef is probably with the tight/loose list distinction, where I don't see how you can specify whether a list with a single list item should be tight or loose. My first thought is that list items should be tight by default unless they contain multiple paragraphs or block-level elements, in which case that item is necessarily loose.