English words/commands in djot markup?

[uvtc]

I know that, with Markdown, the rule is to only use punctuation symbols for markup; the prime directive being "optimize for readability". The markup shouldn't look like markup!

Then folks wanted to add more features to markdown, which required no small amount of creativity in finding ways to use the limited set of ascii punctuation as syntax for these features. This entailed lots of discussion, sometimes resulting in epic multi-year threads on the best syntax for them.

On the other end of the spectrum is something like LaTeX or Texinfo, where you just have \command or @command for a given feature and you're done. These markup formats are easy to write, have more features, and I'm guessing are easier to implement/parse. But readability suffers.

I think readability is key to adoption. If people dislike reading a markup format, they won't write it (or, maybe other people will come along and create lightweight markup languages that compile/transpile to the less-readable but more-featureful markup lang).

I'm wondering where djot falls on this spectrum. My impression is that it's "markdown 2.0 ++" --- ambiguous syntax fixed, syntax simplified (or made more consistent) in some places. But with further ambitions...

If ambitions are to be able to write real academic papers and textbooks with djot (sounds good!), then in order to avoid ascii-soup syntax and decades-long discussions of "the right syntax for {feature}", is it acceptable to introduce some generic english command syntax into djot?

My guess is that the sweet spot is: optimize for readability for the most commonly-used markup, and also introduce a generic english command syntax (like, e.g. @this) to help implement the advanced features (while still striving for good readability).

Potential examples of where an @command might be used: issue #28, @caption, #35 @metadata, #32 @cite, #31 @figure.

[jgm]

I'd like to avoid English command words. On the other hand, if the alternative is Perl-like line noise, then it's a hard call.

[bpj]

It would only be "line noise" to those unfamiliar with the syntax, just as with Perl. Otherwise why not just use TeX or HTML/XML rather than light markup?

FWIW my DSL for conditional string interpolation uses only punctuation in its syntax precisely to be natural language neutral, except for identifiers for variables and functions, which are defined by the program using the library, which can use any language. Since they are embedded in text they are marked with sigils on use, but Bash style rather than Perl style, i.e. the sigil isn't an integral part of the variable/function name. Despite all this there is usually more or less text between the punctuation characters. It doesn't even look punctuation heavy when mixed with markdown (when used as a preprocessor.)

IMO the result is less intrusive than TeX/HTML where are \commands and <tag>s everywhere so it becomes hard to separate markup and text, i.e. the same reason that djot or markdown use punctuation for markup.