Who is this for? I use markdown when I’m getting text from humans. *This* is just 10x easier than this, because I’m typing on my phone.
Markdown is holding you back
151–160 of 194 posts
Re: Markdown is holding you back
#152Reading all these debates about document structure and formatting and so on is so wearying. I predict as long as we have text written by people the debates will continue. Truly a case of the taste of the writers and producers being a key variable that no one system will uniformly satisfy.
Re: Markdown is holding you back
#153The main point of Markdown is that it has a very important feature that other languages don't have: it's supported in a lot of places. Most of the alternatives mentioned in this thread or in the article are things that require custom tools, that can't be used in most of the places that currently do support markdown. It's common in a lot of places. Even Google Docs has a well hidden feature that allows you to paste ma…
> Markdown could be improved in a similar way over time
I think that is unlikely to happen any time soon.
The problem is there isn't any kind of authority that can improve it. The closest we have is commonmark, which is more of a deacriptive specification rather than prescriptive.
Re: Markdown is holding you back
#154Earlier quoted context omitted.
As far as custom shortforms for fully tagged angle-bracket markup is concerned, people are reinventing SGML which can handle markdown and other custom syntaxes since 1986.
I've been meaning to see how close I can come to Markdown syntax using SGML's SHORTREF and perhaps architectural forms.
Markdown inline syntax is straightforward to capture using SGML SHORTREF. What's more difficult (impossible) are things such as reference links where a markdown processor is supposed to pull text (the title of a link) from wherever it's defined before or after its usage.
Haven't heard about archforms in a while ;) but it's not a technique for custom syntax, and since markdown is specified as a Wiki syntax with canonical mapping to HTML, there's no need for the kind of simplistic element and token renaming possible with archforms.
Re: Markdown is holding you back
#155The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format. Markup formats in my opinion need to be defined in terms of a proper grammar, so that we can easily adapt that grammar in any programming language to build a parser and have support for that format in another language. The Org format in Emacs also suffered from this, but now there is an effort to…
> The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format. The same is true of Markdown (the canonical parser being John Gruber's at https://daringfireball.net/projects/markdown/ ) but that didn't stop third parties from extending it in their own implementations. For example, canonical Markdown doesn't support tables at all, but GitHub added custom mark…
Oh, I am surprised the original didn't include tables. Guess it has been too long, since I looked at his page.
reStructuredText of course has support for tables[1].
I think writing a grammar for reStructuredText is a larger effort of course than writing one for Markdown, which is not to be underestimated.
Though extending reStructuredText is way less necessary, because it already includes a concept for custom "directives" (iirc that is what they are called). For example I have once made a custom directive to link to other documents, so that I have a local "wiki" like structure made out of files and folders. In Markdown no specific syntax exists for things to be implemented as extensions. Customization authors need to include special things in their parser instead, or come up with an extensibility concept themselves.
I think the point you are trying to make is, that there seems to be something else making the difference in adoption of the formats. Do I interpret your comment correctly?
[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/...
Re: Markdown is holding you back
#156You can include arbitrary HTML tags in Markdown at any place you need them.[0] I am not aware of any Markdown tooling that does not support this. So, no, Markdown is not holding me back. It is perfectly capable of what the author claims it isn't. [0]: https://daringfireball.net/projects/markdown/syntax#html
> I am not aware of any Markdown tooling that does not support this. Reddit surely doesn't, and I'd be very surprised if github did. In practice, in any place you want untrusted users writing markdown stuff for formatting, you cannot allow arbitrary HTML for security reasons.
Github has a very limited subset of html that is allowed.
Slack doesn't allow html (although it also doesn't allow all markdown).
If you are converting to something other than html, such as a manpage, using html tags generally doesn't work.
Re: Markdown is holding you back
#157Earlier quoted context omitted.
Yes, the author conflates two different use-cases. Markdown is the answer for "how do we enable people that don't want to invest a lot of time into producing content that's somewhat better than plain text?". It's not trying to solve the problem of "how do we enable people that are willing to invest time into learning to produce the best possible and most structured content possible?" and I doubt that there will be la…
The problem in practice is that quickly one merges into the other. You start with a markdown readme, then you have markdown documentation for a small project. But then one day you need full documentation for your project with cross links, translations, accessibility. With Markdown you end up bolting these things on and each flavor does it a bit differently. Perhaps some of the blame can be laid with the poor UX of te…
> does have the issue of feeling like a markdown-ish alternative that's just a bit different for no clear reason.
Asciidoc is older than markdown. Kind of hard to be design something to be the same as something that isn't invented yet.
Re: Markdown is holding you back
#158Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great. For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me. But in the end, no markup language will make you write bette…
Djot is another interesting alternative that tries to make Markdown more parsable and coherent: https://github.com/jgm/djot#rationale
Unfortunately it doesn’t seem to have a formal spec.
Re: Markdown is holding you back
#159> If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices. This is dumb. If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about sem…
> If I'm writing developer documentation I'm not writing it for a machine. And if the aim here is to expose it to a LLM, then the LLM needs to get smarter about semantics, not force us back to formats that are more technically complex to write and maintain AsciiDoc is much better than Markdown for docs intended for humans that are more than short, README type of documents. Any advantage it has for documents intended…
The history of tech is full of "X is better than Y. We should use X", only for X to die. It doesn't matter what is better; it matters what is used. For better or worse, Markdown is what is used.
Re: Markdown is holding you back
#160Earlier quoted context omitted.
As long as your unstructured hassle-free writing just happens to be in the same format accepted by the viewer.
A generic ASCII capable text viewer is enough to read markdown, that's the point ;)
only if the markdown consists of 100% ASCII... unless you have a different definition of "view" than me