29 ms·
If agents can generate text so easily, why would they be limited to Markdown instead of reStructuredText, AsciiDoc, or LaTeX which have rich features that help
by toastal 8mo ago
If agents can generate text so easily, why would they be limited to Markdown instead of reStructuredText, AsciiDoc, or LaTeX which have rich features that help users understand text? I can understand developers refusing to adopt proper formats for documentation, but this seems odd for the bots. It doesn’t even generate the correct syntax block in Markdown using “bash” instead of “sh-session”.
- giancarlostoro 8mo agoI think its primarily because that is the most common formatting in every editor now? I could be wrong. Markdown has become the standard for README files for over a decade now.
- toastal 8mo agoWinning a popularity contest doesn’t mean it’s good. That is the worst part of about these things as they just generate the most common denominator type code/tooling while also repeating anti-patterns/mistakes like the bash vs. sh-session/console issue I pointed out. Garbage in has been so much garbage out unfortunately.
- giancarlostoro 8mo agoNever said it was good, just making an observation that Markdown is most likely to be available to render OOTB in more editors. I don't think Markdown is bad necessarily either. It's "good enough" for simple document.
- toastal 8mo agoDocumentation isn’t as simple document. There are tons of rich elements missing from the spec specifically for documentation… which is why so many resort to adopting one of the many incompatible forks of Markdown to try to get features that were missing (but are a part of reStructuredText & AsciiDoc for instance). That has a real tradeoff since these forks are not going to be compatible & they aren’t going to be as well defined as the specs for these richer lightweight markup syntax choices.
- simonw 8mo agoMarkdown has the widest tool compatibility - GitHub renders it, so does VS Code and many other editors and file hosts. I didn't know about sh-session, is that documented anywhere?
- toastal 8mo agoMS GitHub can not only render rST & AsciiDoc (albeit pretty poorly since they the CSS is bad), but it also is employing its own fork of Markdown that isn’t compatible with other forks. “Just Markdown”, like the base spec, is so feature poor that everyone has their own incompatible fork which don’t make it render properly. console/shell-session/sh-session (parsers call them different names) are for shell sessions, terminal sessions. Bash syntax is for Bash scripts, & these aren’t scripts but something you run in your terminal session.
- simonw 8mo agoI'm not convinced Markdown's various flaws matter for the way I'm using it here. I want a simple, widely-enough supported format for mixing text, code samples and images. The non-standard (because what even is a standard when Markdown is in play?) subset of Markdown I've picked for this project works fine for what I need in Showboat. If it turns out to need more I can expand the format in the future - likely though embedding YAML in frontmatter but I could add sidecar JSON files instead if that proves to be more robust.
- bee_rider 8mo agoI dunno. I’ve written a bit of LaTeX but does it really shine in this context? IMO the real advantage it has is that it can allow the user to express more complicated intents than Markdown (weird phrasing—my natural instinct was to call LaTeX more precise than Markdown, but Markdown is pretty precise for describing the type of file that it is good at…). Anyway LLMs don’t have underlying intent so maybe it is fine to just let them express what they can in Markdown?