[HN Gopher] I prefer rST to Markdown
___________________________________________________________________
I prefer rST to Markdown
Author : BerislavLopac
Score : 307 points
Date : 2024-07-31 15:49 UTC (1 days ago)
(HTM) web link (buttondown.email)
(TXT) w3m dump (buttondown.email)
| PaulHoule wrote:
| I was looking at RST as an answer for a documentation system with
| similar complexity to the system he's building and an intense
| need to mark stuff up with definite semantics, both in the case
| of capturing structures in the RST file in a database _and_
| mixing database results into the content.
|
| Two problems I had were: (1) common with a lot of systems, the
| RST tools don't contain an RST unparser. I really wanted to be
| able to generate RST files automatically by merging content from
| other RST files and other sources and working with them via a
| document API. The RST tools don't support that. (2) The RST tools
| expect a certain defined set of blocks for a particular document;
| it would be very possible for a system to represent blocks in a
| generic way which would make possible tools that can transform
| documents without necessarily knowing the definitions of blocks
| inside it.
|
| These are problems w/ the tools, not problems with RST itself but
| every time I'm forced to strip my code back to the walls is an
| opportunity to think about some other markup system such as
| something HTML-based.
| zdw wrote:
| I don't think this is the case.
|
| In python, rST is just one of many supported input formats for
| docutils: https://docutils.sourceforge.io/README.html#purpose
|
| The entire point docutils is to parse formats and convert using
| an API: https://www.docutils.org/docs/index.html#api-reference-
| mater...
| PaulHoule wrote:
| My beef is that it doesn't have an RST writer. What I want is
| a central hub where I can suck in documentation that was
| originally in different formats and then manually edit it in
| a format where I can capture essential semantics and then
| feed it through the system again to produce output documents.
|
| If it had that it would be a 200 foot tall giant robot, as it
| is it's just another documentation generator.
| zdw wrote:
| Ah, you want something like pandoc, but you can manipulate
| the internals as needed?
| PaulHoule wrote:
| Yes, and with a somewhat different focus. I wish I could
| throw in 1000 pages of reference documentation, align it
| semantically with a few pages of documentation about a
| particular topic and then enrich those pages with
| snippets pulled out of the reference material. And things
| like that.
| Eisenstein wrote:
| Sounds like an actually good use case for an LLM with
| RAG.
| hgs3 wrote:
| > something HTML-based
|
| Instead of HTML you can use XML to write structured documents.
| With XML you can define whatever custom tags you need with
| schema validation if desired. The advantage of this approach is
| you have full control over the input schema and output, but the
| downside is XML is much more syntactically noisy compared to
| Markdown or RST and you will need a script to parse & convert
| the XML to your preferred output format(s).
| giantrobot wrote:
| > Markdown or RST and you will need a script to parse &
| convert the XML to your preferred output format(s).
|
| XSLT will happily output any number of formats from an XML
| doc. There's also a number of existing and very capable XML
| schemas for documentation like DocBook. You can even go from
| a lightweight markup like RST or Markdown to DocBook and then
| have an XSLT pipeline that delivers that intermediary to any
| number of formats. There's also very capable graphical
| editors that will spit out DocBook directly.
|
| I find the aversion to XML very strange. It was definitely
| applied in some places poorly by products with "Enterprise"
| somewhere in the name but the language itself is very useful.
| The aversion to XML has led to a lot of work re-learning of
| the lessons that led to some XML features. It's also led to
| implementing XML features poorly in other languages.
| SoftTalker wrote:
| Yeah I always liked XML as a data format and combined with
| XSLT it is quite powerful.
| PaulHoule wrote:
| What I really like with XSLT is what you can do with
| user-defined functions. Not only are they helpful in
| implementing transforms but you can also write stateful
| functions that insert rows into a database or something.
| wpm wrote:
| You're not alone. I find XML to be massively more readable
| and flexible. I work in the macOS/iOS IT space, and our
| bread and butter is the Property List, which tends to
| either actually be XML underneath or is at the very least
| rendered like XML, all just conforming to the plist DTD
| (which is pretty short). These plists that conform to this
| fairly simple DTD are enough to describe every init task
| and background process to the OS, every preference in
| applications that use UserDefaults and CFPrefs (which is
| most), and I use them for storing structured data in and
| out of scripts that I throw together.
|
| Loads of other systems I work with still output XML, and I
| have fast, powerful tools to work with them pre-installed
| on any Mac I work on, and it doesn't even matter that Apple
| hasn't updated them in a while since XML hasn't really been
| changed either. I can look at an XML doc and have so much
| information about the data inside just telegraphed into my
| head, just by the way the things are shaped. I don't have
| to _read_ the tags like a book, I can just gloss over them
| and still get enough to understand the strings /numbers
| inside. Yet, they're still on the page, out of focus, in my
| periphery, providing anchoring and structure and
| navigation, I can find my place. Maybe I'm just a freak, or
| that comes from 20 years of staring at them. Whatever
| reason, I just can't do that with JSON as easily or as
| fast.
|
| I don't hate on any of the other formats (save for YAML,
| not interested), and I really appreciate JSON's brevity
| sometimes for simple data and small responses, but that
| brevity quickly turns into wisps of formatting and text
| seemingly floating out in the middle of nowhere.
| giantrobot wrote:
| > I don't hate on any of the other formats (save for
| YAML, not interested), and I really appreciate JSON's
| brevity sometimes for simple data and small responses,
| but that brevity quickly turns into wisps of formatting
| and text seemingly floating out in the middle of nowhere.
|
| Same. Every back end project I work on I recommend XML as
| the transport and every time I get a reflexive "ugh,
| XML". Then I spend an inordinate amount of time making
| Swagger endpoints so a consumer can figure out how the
| JSON output is supposed to behave.
| lmm wrote:
| > the language itself is very useful.
|
| It really isn't. Both namespaces and schema cause far more
| problems than they solve. And the theoretical advantages of
| having a declarative language for expressing
| transformations (and schema) is outweighed by how awful it
| actually is to write XSLT (and schema).
| PaulHoule wrote:
| People hate namespaces wherever they are used, but they
| are one of the keys to "programming in the large". The
| first year after Java came out the official docs for
| namespaces weren't complete and I had to go to a web page
| at NASA to understand exactly how they work, particularly
| in the strange case where you don't include a package
| statement -- people got used it though. (I'll make the
| case that Java was a software reuse revolution not
| because it was OO or had a particular implementation of
| OO but because of getting a bunch of "little" features
| right such as namespaces and memory management.)
|
| If we had namespaces for classes and id's in CSS we'd be
| able to transclude content from one HTML to another HTML
| page easily but we don't so we can't. (Shadow DOM helps a
| bit though) The "hygenic macro problem" is one of the
| many barriers people face doing metaprogramming. In the
| RDF world it's refreshing to be able to import facts from
| multiple systems into multiple namespaces so you can put
| data you got from different sources into the same
| database and "it just works".
| lmm wrote:
| A certain amount of namespacing is useful, but the XML
| model where you can't even write a hello world xpath
| query until you've set up all your namespaces and used
| them in your query is something that clearly does more
| harm than good. Java is I think widely recognised as
| having gone too far on the namespacing front; most post-
| Java languages have a much less strictly hierarchical
| namespacing model and I don't think any other package
| registry has adopted the fully nested style that Maven
| does. And even Java's heavyweight namespacing is much
| easier to work with than XML's thanks to things like
| auto-import in IDEs.
|
| I don't think namespaces solve the macro hygiene problem,
| because if you're going to have macros then they need to
| be able to interact with and manipulate your namespaces,
| and sooner or later you need your macro to e.g. generate
| a fresh identifier for use within an existing namespace
| and then you're right back where you started.
|
| Being able to disambiguate when you have one document
| including another would be useful. But the cost/benefit
| on XML-style big namespacing up-front just doesn't stack
| up.
| _heimdall wrote:
| Once you get that far, XSLT is waiting for you if you need to
| render XML to HTML.
| andrewflnr wrote:
| Yes, waiting in the dark, with teeth.
|
| (I kid, mostly. It was a mild pain in the projects I used
| it for, and I've heard much worse horror stories than
| mine.)
| _heimdall wrote:
| Same. I've used it for small projects, like styling an
| RSS feed. I imagine it gets tricky fast in anything
| larger.
| PaulHoule wrote:
| My take is that XSLT comes from a different universe
| where Prolog became a mainstream programming language.
|
| That is, XSLT is based on pattern matching rules that
| most people find strange and unfamiliar. It wouldn't be
| so strange to people if this kind of system was more
| widespread, but as an island that's different from
| everything else I think people struggle to wrap their
| heads around it.
| tannhaeuser wrote:
| Pro-tip: use SGML which has it all:
|
| - is a superset of XML (XML is derived from SGML as a
| simplified, proper subset)
|
| - can parse HTML precisely with all bells and whistles such
| as tag omission, enumerated attributes and other shortforms
| (which are based on SGML after all)
|
| - can define markdown syntax as an SGML SHORTREF
| customization (note that SGML can not cover _all_ of markdown
| syntax; for example, defining reference links somewhere at
| the end of a document and expecting SGML to pull a href URL
| into the place where the link is referenced won 't work with
| SGML SHORTREF)
|
| The combination of markdown-as-sgml and inline HTML or HTML
| blocks is particularly nice and predictable, and also informs
| further customization such as using entities (text
| variables), custom elements, and other advanced SGML stuff
| with markdown that comes up frequently as a requirement.
| euroderf wrote:
| rST and Asciidoc seem roughly equivalent in terms of
| capabilities. Are they roughly equivalent in terms of
| weaknesses and missing features, I wonder.
| bobbylarrybobby wrote:
| I think they're about equal, although asciidoctor has bold
| italics, which rST does not.
| complex_pi wrote:
| I can't test (no computer right now) but can't include
| directives achieve what you want?
| __mharrison__ wrote:
| I am (was?) a committer to docutils (the main tooling for rST).
| One of the reasons I moved my tooling to md was because
| docutils was such a pain to work with (refusing to move to
| something like GitHub illustrates how hostile working with it
| is).
| benji-york wrote:
| I lament the lack of rST support in much of modern tooling.
|
| I'm reminded of all of the alternate worlds that didn't quite
| come to fruition, but could have (Lisp, Smalltalk, BeOS, etc.).
| bunderbunder wrote:
| An interesting commonality among the three examples you listed:
| they're all designed for a world when computing was a more
| solitary activity than it is now.
|
| For Lisp and Smalltalk, image-based development is a genuine
| hurdle in the modern world. It complicates many aspects of
| modern highly-collaborative software development, including
| version control and continuous integration. I think that the
| language's respective hacker ethoses might also be a challenge
| in light of how often people switch jobs nowadays. I haven't
| used Smalltalk for pay money, but my experience has been that
| initially getting settled into a large pre-existing Lisp
| project does take more brain effort than it seems to with a
| language like Java. (In the long run I'd rather inherit a Lisp
| project, but I also acknowledge that first impressions are
| important.)
|
| And BeOS was not a multiuser OS and didn't seem to have a clear
| path to becoming one. I'm pretty sure the main thing preventing
| it from becoming as much of a cybersecurity disaster as Windows
| 95 was is the simple fact that there wasn't any honey in that
| pot.
| marcosdumay wrote:
| Image-based development was never good. So we pushed it back
| again and again, so that we nowadays have a single image
| component we named "database" and most of the work is free
| from its problems.
|
| That doesn't mean we stopped doing it.
| Macha wrote:
| This largely occurs because the only real spec of rST is the
| Python implementation. And tools written in other languages are
| loath to include a Python library just to support one document
| format. While writing a new compatible implementation is much
| more work given the larger scope than it is for Markdown.
|
| So every language has a markdown implementation, but if you
| want to use rst in your Rust based static site generator or
| your PHP based CMS or whatever, it's a lot more work.
| bluGill wrote:
| Every language has its down markdown - but they are not
| compatible with each other unless you stick to the very basic
| which doesn't do much. Which is why every implementation has
| extensions - it isn't hard to add extensions and there are a
| lot of obviously missing things from the basic.
| Macha wrote:
| Yet at the same time I'm able to write Markdown that parses
| and renders correctly in VS Code, Obsidian, and the Rust-
| based static site generator I use. Sure, Obsidian has
| incompatible features I could use like [[Wiki Links]] but I
| don't have to.
| bluGill wrote:
| That is easy enough as long as you are only writing a
| simple one page readme type document. To be fair that is
| the majority of what people write. However if you write
| anything more complex you will run into issues.
| jcranmer wrote:
| Is there any rich text format which is well-supported
| across multiple languages? The closest I can think of is
| HTML, but even that has its fair number of issues...
| osmarks wrote:
| CommonMark mostly fixes this.
| xigoi wrote:
| At the expense of being extremely complex.
| marcosdumay wrote:
| People don't add it because it is ugly and verbose.
|
| And then people don't create any new format for its use case
| because it already exists.
|
| Almost everything good we have only exists because some person
| irrationally decided to do it, against all common sense and
| logic.
| jawns wrote:
| > markdown is a lightweight representation of html, while rst is
| a midweight representation of an abstract documentation tree
|
| To me, the whole point of markdown is to allow you to do simple
| things faster than writing raw HTML, but with the ability to
| intersperse raw HTML when needed.
|
| In projects where I've needed the power of RST over markdown,
| I've felt more comfortable just writing raw HTML directly.
| strongpigeon wrote:
| That's pretty much how I feel. When the author writes:
|
| > This means you can extend Sphinx with new text objects! Say
| you that instead of an <image>, you want a <figure> with a
| <figcaption>. In basic markdown you have to manually insert the
| html
|
| I can't help but wonder what's wrong with just writing HTML if
| you want those features? Why the extra layer?
| scott_s wrote:
| The author wrote an entire article explaining their use case
| which answers your question. Short version: they're writing a
| book which they want to render to multiple formats with
| semantic linking between items and different rendering based
| on formats.
| strongpigeon wrote:
| I get that, but why not use HTML as the base to render to
| other formats? I guess I'm not 100% clear what you mean by
| semantic linking and how could that not be achieved through
| HTML.
| ryan-c wrote:
| Convenience? I have a "spoiler" role for rST, for example,
| which works like this: # state class to
| contain the counter class _spoiler: count
| = defaultdict(lambda: 0) def id(src):
| _spoiler.count[src] += 1 src_hash =
| sha256(src.encode()).hexdigest()[:7] return
| f'spoil-{src_hash}{_spoiler.count[src]:03}'
| def spoiler_role(name, rawtext, text, lineno, inliner,
| options={}, content=[]): src =
| inliner.document.attributes['source'] html = (
| '<input id="{id}" type="checkbox" class="spoiler" checked
| />'+\ '<label for="{id}"
| class="spoiler">{text}</label>'
| ).format(text=text, id=_spoiler.id(src)) return
| [nodes.raw('', html, format='html')], []
|
| I don't want to do that manually, and this lets me write
| :spoiler:`Rosebud was the name of his sled`.
| mmcdermott wrote:
| Just out of curiosity, why not use HTML5's built-in
| details/summary tags (https://developer.mozilla.org/en-
| US/docs/Web/HTML/Element/de...)?
| eddd-ddde wrote:
| That's like saying why use C++ templates if you can just
| write the same function for every type that needs it. Now you
| don't need template instantiation!
|
| The point is that it's objectively better when you want to
| separate the concerns of writing content and rendering it. It
| makes writing much easier and keeping the layout consistent
| as well.
| osmarks wrote:
| Preserving the semantic content is helpful if you think you
| might want to switch the rendering later.
| teamspirit wrote:
| Isn't this just a case of different tools for different jobs (or
| the right tool for the right job)? Rst clearly has some
| advantages for this use case but, at least for me, markdown is
| much faster and clearer to understand when jotting down my daily
| notes.
| hwayne wrote:
| Absolutely. I prefer rst for the use case of _writing a
| technical book_ , because of the specific benefits I get from
| its additional complexity. My blog is still in markdown.
| bluGill wrote:
| Having done a little of both, I find RST is faster just because
| I can lookup whatever syntax I need to keep going while with
| markdown I often stop to scream because I can't make it do what
| I want. Either is easy enough to understand when reading raw
| text - this is mostly about good style though, RST gives you
| more options for bad style that is hard to read.
| BerislavLopac wrote:
| > markdown is a lightweight representation of html
|
| This is my main problem with the article, as this is decidedly
| incorrect.
|
| Markdown was designed as a tool of conversion of _de facto_
| standard of formatting text in email messages and Usenet posts of
| early nineties. The basic 7-bit ASCII nature of those
| technologies inspired people to informally annotate the text with
| special signs to denote formatting like emphasis, section titles
| and the like.
|
| True, HTML shares a lot of similarities with that nameless
| standard, so John Gruber in 2004 wrote a basic script [0] to
| convert the latter to the former, never expecting it to become
| such a universally used actual standard.
|
| [0] https://daringfireball.net/projects/markdown/
| simonw wrote:
| I disagree. Markdown has always been about HTML - to the point
| that Markdown parsers support dropping actual HTML tags mixed
| in the the markup.
|
| The fact that Markdown was inspired by email conventions
| doesn't make the statement "markdown is a lightweight
| representation of html" any less correct.
| SoftTalker wrote:
| I thought a goal of Markdown was to be a set of conventions
| that were readable on their own as well as being
| transformable to a rich text/HTML representation.
|
| You can read a Markdown document pretty easily using "less"
| or any other character-based interface.
|
| The same is not really true of reST.
|
| Maybe I'm confusing that with some other plain-text markup
| convention?
| paiute wrote:
| The article convinced me that markdown is better for its
| purpose.
| Spivak wrote:
| reST is also designed to have human readable source. You
| might not like it compared to markdown but it has to serve
| as a the docstring format of Python and does so fairly
| well.
| woodrowbarlow wrote:
| all of that is true, but markdown targets HTML as its
| "native backend", if you will. it is not feasible to render
| markdown -> pdf without having an intermediate HTML
| representation.
|
| this is clear from the fact that HTML can be inlined in a
| markdown document; this is part of the spec (in so much as
| there even is a "spec" for markdown, anyway).
| latexr wrote:
| > to the point that Markdown parsers support dropping actual
| HTML tags mixed in the the markup.
|
| _Some_ Markdown parsers support _some_ HTML. You cannot, for
| example, add a YouTube video embed to a GitHub comment.
| Webpages that allow Markdown quite reasonably limit what's
| accepted.
| samatman wrote:
| Usually, the colloquial conflation of Markdown with
| CommonMark and the numerous Markdown-esque dialects is
| helpful language, I've defended it here before.
|
| On this question, it isn't.
|
| Markdown _qua_ Markdown, unambiguously supports HTML tags.
| You can verify that yourself:
| https://daringfireball.net/projects/markdown/
|
| The introduction being:
|
| > _Markdown is a text-to-HTML conversion tool for web
| writers. Markdown allows you to write using an easy-to-
| read, easy-to-write plain text format, then convert it to
| structurally valid XHTML (or HTML)._
|
| It's not possible to read the original specification
| without agreeing that, yes, Markdown is specifically a way
| to generate HTML. It also has a nice syntax which has
| become popular in contexts where embedding HTML isn't a
| good idea, and there are some tools which allow Markdown to
| be converted to other formats as well (usually, but not
| always, these disallow most HTML tags, meaning that they
| aren't Markdown _sensu stricto_ either).
|
| I would say that all of this supports Hillel's basic point
| here: Markdown is in fact tied to HTML semantics, in a way
| which makes it painful to do things with it which aren't
| tied to those semantics in the same way. Dialects in the
| Markdown family exist which make this less painful, and
| they do so by diverging from the original Markdown spec.
| latexr wrote:
| > Markdown _qua_ Markdown, unambiguously supports HTML
| tags.
|
| The section I quoted (and responded to) didn't say
| "Markdown supports HTML tags", it said (emphasis added)
| "Markdown _parsers_ support (...)".
|
| So unless you're arguing that a tool cannot be considered
| a true Markdown parser1 unless it parses HTML, the
| distinction is irrelevant. I wasn't making a general
| argument, I was responding to a specific claim.
|
| > You can verify that yourself
|
| Yes, I am quite familiar with that subpar piece of code
| and specification. I have spent some time implementing a
| Markdown parser myself (the output wasn't HTML) and
| Gruber's resources were _by far_ the worst. For various
| reasons he has been an awful steward of Markdown; its
| ubiquity is _despite_ him, not because of. Forgive me if
| I don't find the author to be _the_ authoritative source
| anymore.
|
| 1 https://en.wikipedia.org/wiki/No_true_Scotsman
| travisjungroth wrote:
| I think you've kinda lost the thread. From the top
| comment:
|
| > Markdown was designed...
|
| Surely Gruber is an authority on that.
|
| And anyway, " markdown is a lightweight representation of
| html" is _true enough_ that calling it "decidedly
| incorrect" is wrong. Certainly it's not a point that's
| supported by going to author intent.
| latexr wrote:
| > And anyway, " markdown is a lightweight representation
| of html" is true enough that calling it "decidedly
| incorrect" is wrong.
|
| Yes, I completely agree with that.
|
| And that wasn't the point I quoted or responded to.
|
| > From the top comment
|
| Again, I wasn't replying to the top comment, I was
| replying to _what I quoted, from the comment I replied
| to_.
| The_Colonel wrote:
| Gruber:
|
| > Markdown's syntax is intended for one purpose: to be used
| as a format for writing for the web.
|
| Both Gruber's original and CommonMark (the closest thing to
| a standard) support inline HTML.
|
| Both Gruber and CommonMark specs are defined in terms of
| its HTML output.
| latexr wrote:
| Yes, that's why I said "some". I don't understand what's
| ambiguous about that.
| The_Colonel wrote:
| The question is whether these are even Markdown
| implementations, or rather something like "Markdown-like
| format".
| velcrovan wrote:
| The very first sentence in that link says "Markdown is a text-
| to-HTML conversion tool for web writers."
|
| Gruber did not take a "de facto standard" from Usenet and
| simply write an HTML converter for it. He designed his own
| markup, borrowing from Usenet and other conventions. The
| "Acknowledgements" section at the bottom of your link alludes
| to this fact.
|
| Markdown was from the beginning intended as a markup syntax for
| web CMSs. To say it is a lightweight representation of HTML is
| correct. The whole point was that every part of the syntax
| produce a direct HTML equivalent.
| CharlesW wrote:
| Gruber writes that Markdown is two things: (1) a plain text
| formatting syntax; and (2) a software tool, written in Perl,
| that converts the plain text formatting to HTML.
|
| > _To say it is a lightweight representation of HTML is
| correct._
|
| It's correct in the context of (2) but not (1). In the
| context of (1), Markdown is a lightweight markup language for
| rich text. For example, Pandoc can convert Markdown to
| formats like PDF, LaTeX, and ePub.
| The_Colonel wrote:
| Isn't inline HTML valid within Markdown? You could say that
| Markdown is a superset of HTML.
| CharlesW wrote:
| That's an excellent point. Time to update
| https://www.wikiwand.com/en/Markdown. :^)
| NekkoDroid wrote:
| It depends on the dialect you are using. Some support a
| limited subset of HTML, some allow all and some allow
| none (maybe HTML/XML comments).
| rpdillon wrote:
| It's also true in the context of (1), since the syntax
| specification specifically falls back to HTML for difficult
| things like tables.
|
| This is made abundantly clear on the Syntax page[0]:
|
| > Markdown's syntax is intended for one purpose: to be used
| as a format for writing for the web.
|
| > Markdown is not a replacement for HTML, or even close to
| it. Its syntax is very small, corresponding only to a very
| small subset of HTML tags. The idea is not to create a
| syntax that makes it easier to insert HTML tags. In my
| opinion, HTML tags are already easy to insert. The idea for
| Markdown is to make it easy to read, write, and edit prose.
| HTML is a publishing format; Markdown is a writing format.
| Thus, Markdown's formatting syntax only addresses issues
| that can be conveyed in plain text.
|
| > For any markup that is not covered by Markdown's syntax,
| you simply use HTML itself. There's no need to preface it
| or delimit it to indicate that you're switching from
| Markdown to HTML; you just use the tags.
|
| Markdown is very coupled to HTML, and is hobbled as a
| result compared to formats like Tiddlywiki and Org that not
| only have sophisticated syntax for all kinds of content
| like tables, but also directives to the parser itself to
| render particular blocks using an external tool. I wrote a
| bit about this in 2021 in response to query about why Org
| mode doesn't use Markdown[1].
|
| [0]: https://daringfireball.net/projects/markdown/syntax
|
| [1]: https://rpdillon.net/why-doesnt-emacs-org-mode-just-
| use-mark...
| lmm wrote:
| > Markdown was from the beginning intended as a markup syntax
| for web CMSs.
|
| As a matter of history you're right, just as JSON was
| intended as nothing more than the literal syntax for
| JavaScript programs. But it turned out to be a lot more
| widely applicable.
|
| > To say it is a lightweight representation of HTML is
| correct.
|
| No, it's a representation of writing. It represents the input
| not the output.
| chrismorgan wrote:
| Markdown, _Markdown_ , is nothing to do with email and Usenet
| formatting. It was a specific syntax, poorly defined, which has
| since become a broad family of mostly similar syntaxes; and it
| was _inspired by_ various conventions from things like email
| and Usenet, some of which predate _computers_ (e.g. pretty sure
| I've seen or heard of asterisks being used for italics in old
| typewritten stuff); but Markdown is all about HTML, its syntax
| is _extremely_ constrained by HTML, and any attempts to
| separate it from HTML are fairly thoroughly doomed.
| masklinn wrote:
| Saying that it has _nothing to do_ with email /usenet is a
| bridge too far in the other direction, it was very much
| inspired by such formatting, something it never hid:
| https://daringfireball.net/projects/markdown/
|
| > the single biggest source of inspiration for Markdown's
| syntax is the format of plain text email
| chrismorgan wrote:
| Yeah, it was _inspired_ by those things, as I said, but it
| was never connected to them, and is quite incompatible with
| them.
|
| I also express things that strongly because I've observed a
| distinct tendency to interpret Markdown as the successor of
| those things or the inventor of such syntax ideas. Whereas
| in fact, Markdown was not the first lightweight markup
| language, and is not the only one, and isn't even the LML
| unquestionably closest to plaintext email conventions
| (reStructuredText is an obvious contender; overall, I'd
| consider reStructuredText a little closer than Markdown,
| but it's subjective).
|
| Perhaps my intent would be more clearly expressed by
| inverting it: _email formatting_ has nothing to do with
| _Markdown_.
| masklinn wrote:
| > Yeah, it was inspired by those things, as I said, but
| it was never connected to them
|
| You seem to have a very peculiar interpretation of the
| word "connection"
|
| > and is quite incompatible with them.
|
| It can't be incompatible with ad-hoc unspecified and
| informal formatting habits.
|
| > Perhaps my intent would be more clearly expressed by
| inverting it: email formatting has nothing to do with
| Markdown.
|
| That's just as inane for the same reasons.
| keybored wrote:
| You're both right. The original implementation was a superset
| of HTML. Do the lightweight syntax for the common stuff and
| HTML for the rest.
| js2 wrote:
| Dear HN: stop leaving comments like this. It's arguing over
| semantics and makes for boring conversation. It also violates
| HN guidelines for leaving comments:
|
| - Please respond to the strongest plausible interpretation of
| what someone says, not a weaker one that's easier to criticize.
| Assume good faith.
|
| - Please don't pick the most provocative thing in an article or
| post to complain about in the thread. Find something
| interesting to respond to instead.
|
| https://news.ycombinator.com/newsguidelines.html
|
| If you disagree with the substance of the article, say you
| prefer Markdown to rST, then address that. Explain why despite
| the author's preference for rST, you prefer MD. It's silly to
| argue over this single sentence about exactly what Markdown is
| or isn't.
| tombert wrote:
| Yeah, that's what I feel gives markdown an edge over nearly
| anything else; markdown is adopting conventions that were meant
| to be readable without any kind of rendering. I can very easily
| tell what my markdown document is going to look like before I
| render it with Pandoc, because it's basically just taking stuff
| people were using with plain text that was meant to be read
| directly anyway.
|
| I haven't used rST, but looking at the examples it looks
| considerably less readable out of the box.
| Spivak wrote:
| Oh it's not that bad. * one * two
| * buckle my shoe | inspiring quote | -
| some famous guy foo a kind of bar
| bar part of a foo :red: stop
| :yellow: speed up :green: go - code::
| python def fun(): pass
| Go here_ for more info. - :: here: https://google.com
| My **strong** text is well *emphasized*. Very ``literally``.
| simonw wrote:
| A few years ago I wrote up some notes on the subset of
| reStructuredText that's worth committing to memory:
| https://simonwillison.net/2018/Aug/25/restructuredtext/
|
| I've started using MyST for my more recent projects, which gives
| me the features I care about from reStructuredText - references
| and table of contents - but lets me use markdown syntax, which is
| easier for contributors.
| smore wrote:
| Great points about links, especially external links -- it makes
| a lot more sense in the context of a documentation site where
| you might have the same external link referenced multiple times
| in the site, but you only want to have to update it once if it
| changes.
|
| The real gamechanger is for internal links (rST+Sphinx) and the
| use of the `:ref:` and `:doc:` directives so that you can
| reference an anchor or a doc link in the same content without
| having to type the header manually (which will inevitably go
| stale).
|
| https://www.sphinx-doc.org/en/master/usage/referencing.html#...
|
| that is one of the things I miss most about writing in rST, for
| sure.
| jasonpeacock wrote:
| Lemons vs limes. They're both markup languages, but they have
| different purposes.
|
| Yeah, using markdown to write a book is very limiting and doesn't
| offer the control needed for typesetting.
|
| OTOH, using markdown to write is liberating - you only get a few
| markup options, so you can focus on the content:
| [It is] notable that the Feynman lectures (3 volumes) write about
| all of physics in 1800 pages, using only 2 levels of
| hierarchical headings: chapters and A-level heads in the
| text. It also uses the methodology of sentences which
| then cumulate sequentially into paragraphs, rather than the
| grunts of bullet points. Undergraduate Caltech physics is very
| complicated material, but it didn't require an elaborate
| hierarchy to organize. Edward Tufte, forum post,
| 'Book design: advice and examples' thread
| louwrentius wrote:
| The one-line summary is:
|
| > I think Restructured Text is better for writing books than
| Markdown.
|
| That would be a better title.
| Karellen wrote:
| Any sufficiently complicated lightweight markup format contains
| an ad-hoc, informally-specified, bug-ridden, and only slightly
| easier to use implementation of half of either DocBook or TeX.
| nequo wrote:
| Yes but Djot is pretty good though! Wouldn't call it informal
| nor bug-ridden, it's well thought out and doesn't have many
| corner cases:
|
| https://djot.net/
|
| Designed by one of the authors of CommonMark, an attempt to
| specify a standardized flavor of Markdown.
| 0cf8612b2e1e wrote:
| I just wish it would move along already. I get it, some tough
| calls need to be made on edge cases that do not have a
| correct answer. Yet I want a 1.0 release so I can feel
| confident that the language will have staying power.
|
| Then again, it is already in pandoc, so I suppose you can
| trivially move out of it.
| keybored wrote:
| Djot insists that this nesting of bullet points is wrong:
| - first - second
|
| Instead you need this: - first
| - second
|
| I'm very picky about the aesthetics of lightweight MLs so
| this is tough to swallow.
|
| EDIT: By the way, recent comment from the primary developer:
| https://github.com/jgm/djot/discussions/310#discussioncommen.
| ..
| kps wrote:
| Not having used djot myself, does "rethink tight/loose
| lists" refer to that?
| the__alchemist wrote:
| Indeed; Github will now render TeX in markdown documents, eg
| when displayed as a repo's readme. Very convenient.
| breck wrote:
| Here is how you would do your image example in Scroll:
|
| rst: .. image:: example.jpg :alt:
| alttext
|
| scroll: image example.jpg caption
| alttext
|
| "Directives" in rST are "Parsers" in Scroll. The item above would
| be parsed by the `imageParser`, which at ~50 lines of code (https
| ://github.com/breck7/scroll/blob/b8fd72aa38742cc6cd575f...), is
| actually more code than the average parser.
|
| To write your "exercise extension" in Scroll, you would just need
| to write a few lines of code definining an "exerciseParser". You
| could put that in the same file you use it in, or in a file named
| "exercise.parsers".
|
| I think you should explore Scroll -- https://scroll.pub/ -- might
| do everything you need in a simpler way!
| eviks wrote:
| Out of curiosity, would you be able to write a parser that uses
| the markdown style for image links?
| breck wrote:
| Yes, you could do that. At some point soon (perhaps this
| already works today), you could probably just copy/paste the
| entire Scroll Parsers code
| (https://try.scroll.pub/scroll.parsers) into a ChatGpt or
| Claude.ai prompt and ask it to write one.
| bluGill wrote:
| The problem with RST is the same with everything else: it isn't
| supported everywhere. I wrote a bunch of nice RST documentation
| at work, the next month some company wide team announced a new
| standard for documentation (backstage) which is markdown based,
| and has all the problems of markdown. (In their defense I'm not
| aware of any tool that would compete with backstage for what we
| need in a company wide documentation system)
| f1shy wrote:
| One solution:
|
| https://pandoc.org/
|
| Or "how I stopped caring about doc formats"
| morbicer wrote:
| RST might be technologically superior but markdown is easy to
| write and has a huge ecosystem.
|
| For hobby usage, use whatever. But I would strongly oppose anyone
| who would try to make RST standard at my workplace.
|
| A scrum-master, PO or marketing can write markdown. RST would be
| a hard sell.
| numlock86 wrote:
| > markdown is a lightweight representation of html
|
| Never before on an article I've felt the vibes of the "I stopped
| reading there"-meme harder than here.
| psychoslave wrote:
| >The most important difference between rst and markdown is that
| markdown is a lightweight representation of html, while rst is a
| midweight representation of an abstract documentation tree.
|
| Not really. Quoting https://en.wikipedia.org/wiki/Markdown
|
| >Its key design goal was readability, that the language be
| readable as-is, without looking like it has been marked up with
| tags or formatting instructions, unlike text formatted with
| 'heavier' markup languages, such as RTF, HTML, or even wikitext
|
| So, for use cases that don't make a good match of this chief
| constraint, Markdown might not be the most relevant option. It's
| just as meaningful as saying that we prefer TeX over Markdown
| because fine typographical tuning is an important concern of our
| specific usecase.
|
| I admit I already dealt with a screw using a hammer, not having
| the right toolset at hand. But when the situation don't call for
| adhoc heterodox actions, I prefer to match a screwdriver with a
| screw and a hammer with a nail.
| queuebert wrote:
| Personally, besides it being a nice format, I use Markdown to
| honor Aaron Swartz.
| Ericson2314 wrote:
| Haha on one hand its probably Aaron Swartz's worst work. On the
| other hand, this is definitely the best reason to use markdown.
|
| RIP
| mg wrote:
| Markdown: 
|
| RST: .. image:: example.jpg :alt:
| alttext
|
| The author prefers RST because: ... you can
| extend Sphinx with new text objects! Say you that instead
| of an <image>, you want a <figure> with a <figcaption>
| ...
|
| What I would do:
| [caption]
|
| And write a renderer which supports this syntax to create a
| figure with a figcaption. A markdown renderer is simple enough to
| write your own or extend an existing one.
| eichin wrote:
| Exactly - does anyone (well, maybe the author does since he did
| use markdown in previous works) use "basic" markdown anyway?
| There are always some extensions (either front-text metadata or
| syntax extensions like this one) in the "interesting" apps.
| (The python markdown module API kind of feels like it's
| _entirely_ about extension and only a little bit about actually
| parsing, but that did make it easy to add an `ASIN()` token for
| a review site without needing a preprocessing stage...) That
| does make it a little worse for interchange, but that 's maybe
| less important for markdown anyway.
| eichin wrote:
| (Even with pandoc, https://pandoc.org/MANUAL.html#extensions
| lists a bunch of syntax for things like this, brought in from
| github, php, and other places - for the example above,
| `implicit_figures` and `link_attributes` are a good starting
| point.)
| Ericson2314 wrote:
| OK that specific example works, but what about his later
| problem vs solution one? One runs out of hacks pretty quickly.
| romanovcode wrote:
| Honestly I stopped reading article after this example. No,
| thank you. RST syntax looks confusing and overly explicit. I'd
| stick with MD thankyourverymuch.
| smlavine wrote:
| I think commenters are missing that the author is talking about
| this in the context of typesetting their own book. They aren't
| claiming that rST is better than Markdown in the general case; in
| general, Markdown's simplicity is a reason why it is so widely
| used. But that's not what the author is talking about.
| tristor wrote:
| I use Markdown constantly, every single day, and I have tried
| multiple times to switch to RST and failed. Ultimately the reason
| Markdown works the best for me is that it gets out of my way. I
| can just type, I don't have to invest significant effort in
| formatting structures and can just write. This makes Markdown
| ideal for my primary use case, which is note-taking live during
| meetings, and because I already use it there, I also use it for
| writing blog posts, documentation, and most other document
| writing purposes. I will freely acknowledge RST is better for
| writing documentation and formal structured documentation, but
| the learning curve/barrier for RST is enough higher than
| Markdown, that it's not worth it for me to use both systems.
| mjburgess wrote:
| I believe the big selling point is supposed to be the directives
| syntax of rST. I had a similar need to extend markdown, but
| pandoc already supports directive syntax -- and so do some
| libraries, eg., the marked library, which I use to render MD as
| HTML in-browser rather than with pandoc.
|
| The iirc, syntax is :inline{property} and :::
| block-directive {options} contents :::
|
| It doesnt nest well, so I applied any document-level styles using
| the filename; but I'd imagine the yaml-style lead-in tags should
| be the correct way to do it.
| kaycebasques wrote:
| Context: I've been a technical writer for ~12 years. I actually
| started out my career migrating a startup's docs from Word to
| Sphinx. Then I did a lot of time on Google's proprietary
| CMS/platform for developer docs. Then a few years on Eleventy-
| based sites. For the last two years I've been back on a Sphinx-
| based site (pigweed.dev). I've also done some odd jobs for
| readme.com-based startups and have dabbled in Docusaurus, Astro,
| and Hugo.
|
| reStructuredText (reST) by itself can be pretty rough. reST
| combined with Sphinx is pretty great. I.e. the strengths of
| Sphinx _far_ outweigh the weaknesses of reST. For big,
| professional docs sites (+100 pages, +10 contributors) I have
| pretty strong opinions that Sphinx is probably the most
| responsible choice, long-term.
|
| > The most important difference between rst and markdown is that
| markdown is a lightweight representation of html, while rst is a
| midweight representation of an abstract documentation tree.
|
| Yes, what this means in practice is that it's easy to customize
| common aspects of your site (such as how images are displayed). A
| teammate of mine on Pigweed recently created a shortcut for
| linking to bugs consistently. You type :bug:`59385981` and the
| link gets transformed into https://pwbug.dev/59385981. If we ever
| need to mass-migrate all of our bug links, it's now trivial.
| Another profoundly important consequence of this architecture:
| all internal links are guaranteed to always resolve (you get
| warnings/errors if you link somewhere that doesn't exist). I
| previously wrote about how baffling it is that this is not the
| industry standard for docs sites:
| https://technicalwriting.dev/src/link-text-automation.html
|
| The other thing that Sphinx excels at: well-defined extension and
| theme APIs. It's not exactly _easy_ to build extensions or
| themes, but lots of people have figured it out (including me).
| There 's a pretty rich ecosystem of extensions and themes on
| PyPI.
|
| Lately I've been calling Sphinx the sleeping giant of docs
| systems. It's already pretty great and with a little concerted
| effort I think we can collectively make it absolutely phenomenal.
| The upstream Sphinx repo now has a GitHub Discussions section
| that gets a little traffic; a lot of us seem to congregrate on
| the #sphinx channel in the Write The Docs Slack.
| ak217 wrote:
| Agreed that Sphinx is extraordinary and wildly underrated.
| Sphinx is the only _architecturally sound_ , extensible, widely
| used documentation framework that I know of. Its plugin
| ecosystem is amazing and gives me incredible leverage to
| improve documentation for teams and projects.
|
| I'm not a fan of reStructuredText, but nowadays it's possible
| to do most things that previously tightly coupled Sphinx to RST
| in Markdown, courtesy of MyST-Parser:
| https://github.com/executablebooks/MyST-Parser
| bluGill wrote:
| Except that the plugins are not compatible with each other or
| the latest version. That means I'm seeing some bugs that are
| fixed in the latest but I can't get the fix because my
| doxygen plugin doesn't work with the latest, and even if it
| did is the mermaid plugin updated yet? (please don't ask
| which versions of each I'm using - I believe there are at
| least 2 different ones that can do both of the above and they
| all have different abilities...)
| skybrian wrote:
| Some drive-by feedback on pigweed.dev: It seems like it's
| missing a "What is Pigweed" section? I was wondering what
| Pigweed does and eventually found the Github README, which is
| somewhat better. (I've used Arduino, but I'm not quite sure
| what I'm looking at.)
| kaycebasques wrote:
| Thanks. It's basically middleware for large, professional
| embedded development teams creating mass market products,
| usually consumer electronics. The four pillars in the "What
| is Pigweed?" section on the homepage [1] really do sum up a
| lot of what we do, but the reality is that it's a difficult
| "product" to explain in general. But rest assured that it's
| definitely on my radar that there is huge room for
| improvement in our "What is Pigweed?" content.
|
| [1] https://pigweed.dev/#what-is-pigweed
| skybrian wrote:
| Apparently I'm bad at skimming. I _did_ see that section,
| though apparently not the heading :)
|
| The first part didn't really do it for me because it seemed
| too meta:
|
| "Over 150 libraries" - to do what? (Actually, some good
| examples are in the next section.) "Automation" - to build,
| test, and lint what? "Environments" - to make builds
| reproducible, to do what? "Frameworks" - turnkey solutions
| for what?
|
| They are clickable, though, so maybe I should have clicked.
| :)
|
| > We provide libraries (modules) for strings, time,
| assertions, logging, serial communication, remote procedure
| calls (RPC), and much more.
|
| Maybe put that up front?
|
| Looks like "frameworks" are still work in progress; maybe
| I'll check back someday when they get to Raspberry Pi Pico
| support.
| shepherdjerred wrote:
| Why do you like Sphinx so much? Have you ever used
| MkDocs/Material for MkDocs? How do they compare?
|
| At my last job I spent a fair amount of time on documentation,
| but I don't have a great understanding of what technical
| writers like/dislike, or what documentation systems are best.
| bluGill wrote:
| I like sphinx because I can make it do all the weird links
| between documents that I want. Markdown can't do that. I've
| never used MkDocs so I cannot comment.
| irskep wrote:
| I've used both extensively. (Material for) MkDocs is easy to
| set up and gives very good UX for users. Sphinx is hard to
| set up and provides better UX in some ways (internal links
| are on another level entirely), and worse UX in others (the
| themes are all worse than Material for MkDocs, every single
| one).
| einpoklum wrote:
| > reStructuredText (reST) by itself can be pretty rough. reST
| combined with Sphinx is pretty great.
|
| So, you've made a convincing argument of why we should prefer
| Markdown to reST, 9 times out of 10. If we're working with
| Sphinx we'll give it serious consideration.
| Spivak wrote:
| I'm not really sure what your point is. What you're saying
| agrees with both the parent and the OP.
| einpoklum wrote:
| My point is that the reason GP prefers rST is a reason not
| to prefer it, usually.
| kaycebasques wrote:
| I heard recently that MyST [1] now has full feature parity
| with everything that reST provides. If I were starting a new
| project today I would seriously look into Markdown-based
| Sphinx site powered through MyST. For Pigweed we collectively
| don't seem to hate reST enough to justify the huge project of
| migrating everything over from reST to Markdown.
|
| So yeah, I don't really have strong opinions on sticking with
| rest per so. I only have strong opinions about Sphinx being
| probably the best choice out there for large docs sites.
|
| [1] https://myst-parser.readthedocs.io/en/latest/
| eska wrote:
| _Yes, what this means in practice is that it 's easy to
| customize common aspects of your site (such as how images are
| displayed)._
|
| I found this to be very easy using Markdown+pandoc. I turned
| image tags containing youtube links to thumbnails with video
| tag and alt text, hooked up image tags to local video files to
| ffmpeg to optimize and resize videos to then do the same, etc
| in a few lines of code.
| pbowyer wrote:
| > Another profoundly important consequence of this
| architecture: all internal links are guaranteed to always
| resolve (you get warnings/errors if you link somewhere that
| doesn't exist). I previously wrote about how baffling it is
| that this is not the industry standard for docs sites:
| https://technicalwriting.dev/src/link-text-automation.html
|
| This, so much this.
|
| It's a problem in an even more general form (for you're writing
| about linking to sections within a page): the number of CMS
| systems or static site builders that make you insert the final
| URL when you write is _insane_.
|
| If the slug changes, you reorganise your site - now you have to
| do a search and replace through the site to update all your
| links.
|
| Static site generators could enable linking like
| [Hello](../hello.md) and resolve the link at build time,
| instead of expecting everyone to type [Hello](/why/hello/). And
| yet the popular ones I've used or looked at don't do this.
|
| It seems to be a marmite feature (you love it or you don't):
| I've raised it with static site builder team members and
| received a "Why would you want that?" response. Explanations
| got nowhere. I'm not sure if it's a niche feature, you have to
| have experienced the problem to appreciate the solution, or
| people are used to writing once and not maintaining for a
| decade or longer, but it'd be great to see wider support.
| throw310822 wrote:
| Ok, what about DITA?
| kaycebasques wrote:
| Also very powerful. Haven't worked with it in years; need to
| revisit.
| mixmastamyk wrote:
| I liked it as well. But many years ago I tried to get them to
| implement parts of a book, and they never did. You can work
| around somewhat by hardcoding chapter numbers--but I don't feel
| sphinx is suitable for book-length docs without that simple
| feature.
| dlivingston wrote:
| If you want Sphinx to achieve that breakout success, priority
| #1 should be to get high-quality, beautiful themes.
|
| At least for me, aesthetics are a high-priority factor when
| deciding which site generator to use. Hugo and Gatsby have
| great built-in themes, and I have chosen them for projects
| before based largely on this fact.
|
| The Sphinx themes here [0] and here [1] are various levels of
| "meh" to bland.
|
| Look at the standard Sphinx RTD theme: https://sphinx-rtd-
| theme.readthedocs.io/en/stable/
|
| Now, compare it to documentation sites like:
|
| - Apple's:
| https://developer.apple.com/documentation/swift/array
|
| - Fluent UI: https://react.fluentui.dev/?path=/docs/concepts-
| developer-po...
|
| RTD looks dated in comparison.
|
| [0]: https://sphinx-themes.org/
|
| [1]: https://sphinxthemes.com/#featured-themes
| 0xedd wrote:
| Looking at Fluent UI VS featured-themes, I don't see a
| difference.
|
| I'll ignore Apple because: 1) It loads _extremely_ slowly
| (10+ seconds). 2) Just looks like a dark theme and nothing
| more.
| dlivingston wrote:
| Apple's site loads for me in under 1 second with a clean
| cache force-reload.
|
| The featured themes, in general, have poor typography and
| whitespace, poor formatting and alignment, and uninspired
| colors and design. Furo [0] is the best-designed of them
| and would make a solid foundation for a proper theme.
|
| [0]: https://sphinxthemes.com/themes/furo
| danpalmer wrote:
| I don't disagree that themes are an important part of
| marketing a tool. The engineer in me doesn't want that to be
| the case, but I recognise that people like pretty things, it
| makes a difference.
|
| However I'd push back a little. That Fluent UI doc site looks
| like every other doc site from an open source project started
| since ~2020 that I've seen, and this means that I have
| certain expectations: I expect the project to be immature, I
| expect the docs to be incomplete or out of date, I expect the
| search to be an annoying AI search that does a worse job than
| the basic full text search that I expect elsewhere, I expect
| that to get anything of substance done I'm going to have to
| hang out on a Discord server. When I see a ReadTheDocs site
| though with that default theme, I expect the project to be
| somewhat mature, I expect it to basically work. I expect the
| docs to be fairly complete.
|
| Are these expectations fair? Not really, but that's the whole
| point here. Open Source projects are not immune from
| marketing, and when marketing, what other similar projects do
| will affect how people respond to your marketing. Nothing
| exists in isolation.
|
| In my experience, engineers think marketing doesn't apply to
| them, but these impressions really do matter.
| kaycebasques wrote:
| I agree that more stellar, super-visually-appealing themes
| will help Sphinx get to the next level.
|
| One nit: I called Sphinx a sleeping giant because it's
| already majorly successful in the Python ecosystem. Pretty
| much all big Python docs sites are built on top of Sphinx,
| including docs.python.org. But I think it's fair to say that
| when Sphinx starts getting major adoption outside of the
| Python ecosystem then we can start calling it a breakout
| success.
| __mharrison__ wrote:
| Until you need to make a physical book with Sphinx or write
| custom tooling with it...
| kelsey98765431 wrote:
| When you call a book v0.2 and say "now with epub, get it here" in
| the first line of your blog on why not to use the most popular of
| a thing, I am assuming we are going to be having a above board
| conversation about pros and cons, and I an receptive to your
| position.
|
| When the first link is also the second link, and both are to BUY
| a 15 dollar book with the default "pay anything price" bar set to
| 20, I am just clicking out and ignoring literally everything in
| your marketing post.
|
| Others can discuss this RST thing I have never heard about, I am
| just here to point out you have now alienated one of your
| potential converts. Put the book link at the bottom, and dont
| double link to the same purchase page in the same paragraph. FFS.
| blt wrote:
| If the author is here: Before the first code display, where you
| write: > Here's how to make an image in html:
|
| I think you meant "markdown" instead of "html".
| betaby wrote:
| asciidoc anyone?
| schaefer wrote:
| I keep my journal in a blend of asciidoc and markdown. In
| asciidoc, I love xref soooo much, which lets you make cross-
| document links to .adoc files that still work after being
| translated to html.
|
| But I'm so sad that asciidoc isn't supported by pandoc.
| argonaut68 wrote:
| +1. My current workaround is the use of asciidoctor to
| convert my docs to docbook. This format is supported by
| pandoc.
| papascrubs wrote:
| Right? So many features, and much easier to write than RST in
| my opinion. You can do things like dynamically reference other
| files to build tables: [%header,format=csv]
| |=== include::tracks.csv[] |===
|
| What about only including specific lines? Say from a log file
| or a separate piece of code? You can do that!
| [source,python] |===
| include::example.py[lines="1..10,15..20"] |===
|
| Asciidoc solves nearly every problem I've ever run into with
| markdown and RST. I really wish it were more widely adopted.
| joekrill wrote:
| The thing I like about markdown is that it's very readable as
| just a raw format. With the bonus that it's easily converted to
| HTML. But it doesn't _need_ to be converted to HTML.
|
| I guess this sort of falls under the "But I hate the syntax"
| section of the article, but I don't think it quite gets the
| point. I can look at a Markdown file and read or write it without
| even really thinking. Which is not really the case with rST (or
| even HTML, for that matter).
| bluGill wrote:
| I can look at a rST file and read it, and I think you will have
| no problem reading every rST file I've ever looked at. Sure it
| will take you a few seconds to realize you can ignore various
| syntax things, but that isn't a big deal and then the whole
| makes sense. Of course rST gives a lot more options to write
| documents that are not human readable, but it isn't that hard
| to make them readable.
| prpl wrote:
| Sphinx + markdown (Myst) is a nice middle ground here I think,
| with the sphinx directives implemented as code blocks.
| karaterobot wrote:
| I thank the author for explaining their reasoning. I still
| disagree, but I appreciated reading the argument.
|
| Apart from the ugliness of the syntax from a devex perspective, I
| think one of the big advantages of Markdown is that it's highly
| readable even without being interpreted, which rST is not. So if
| you have a markdown document and no markdown interpreter, an
| average person can still make more or less perfect sense of the
| contents, including the hierarchy and emphasis.
| Morizero wrote:
| > You just need a regex to transform it into <img alt="alttext"
| src="example.jpg"/>.
|
| Is this what the author means by markdown being lightweight,
| since the inverse isn't true except trivially?
| insane_dreamer wrote:
| I would say which is better depends on the use case. For note
| taking and most simple documents, Markdown wins hands down due to
| its readability and speed. For complex document sets where custom
| rendering may be required, rST+Sphinx is probably what you want.
| thesnide wrote:
| Rst is technically vastly superior to MD. Yet I predict that MD
| will prevail. VHS style.
|
| I hugely prefer to write in RST, but as soon as I'm not alone we
| always switch to MD, given enough coworkers.
| 12_throw_away wrote:
| Yep, it seems like the platonic ideal of a "worse is better"
| situation.
|
| I do think this is, ironically, partly a documentation problem
| - when I last tried to create docs for a python codebase
| (several years ago), I found the rST docs to be sorely lacking
| in basic, introductory "here are the core mental models for how
| this works" sorts of content. Maybe the situation is better
| now? (Or maybe I just missed them, but not for lack of trying)
|
| But I feel like then, it's obvious README.md prevailed and will
| continue to be the standard - you can use markdown for a very
| long time _without ever reading any documentation at all_.
| Worse is better, I guess.
| bloopernova wrote:
| In my opinion, I don't think it's "worse", just simpler. Plus
| it's more ubiquitous, supported by Github etc etc.
|
| Although Github may not be the best yardstick there, because
| they render documents written in Emacs' org-mode too! (which
| I very much appreciate, I prefer writing in org to writing in
| Markdown)
|
| I'm hoping that LLMs will make it more streamlined when
| documenting existing code. Not so much as a replacement for
| text written by experts, but in converting code into
| diagrams. LLMs or similar "understand" a codebase by
| tokenizing it (as is my understanding), so turning that into
| a nice documentation skeleton should be possible.
| paxys wrote:
| IMO the most important feature of markdown is that any random
| person, whether they are technical or not or know what markdown
| is or not, can view markdown-formatted text and understand it
| perfectly fine. A UI layer added on top is nice to have, but not
| at all necessary. Most alternative formats miss that critical
| point.
| IshKebab wrote:
| I would _strongly_ recommend using Asciidoc over Restructured
| Text. Even though Asciidoctor is written in Ruby which IMO is
| much worse than even Python, the actual RST codebase is a total
| incomprehensible mess. You _can_ extend it with custom processing
| etc, but... fuck, I really want to never have to do that again.
|
| Asciidoc just seems to be much higher quality in general.
| jszymborski wrote:
| I echo your sentiments, but sadly the Asciidoc python compiler
| (as far as I can tell) is deprecated and no longer supported. I
| think that leaves Asciidoctor as the only mature compiler.
|
| There's a spec being drafted, so hopefully that will spur some
| more action.
|
| For my purposes, Asciidoc is the best markup with the worst
| tooling, and Markdown is the worst markup with the best
| tooling.
| 60secs wrote:
| the toc macro on asciidoc is sublime
|
| :table-caption!: :toc: macro :sectlinks:
|
| toc::[]
| FartinMowler wrote:
| I run asciidoctor's Docker container. It does what I want it
| to do without leaving a mess behind on my laptop.
| IshKebab wrote:
| The trouble with that is it becomes a pain in CI. Nested
| Docker isn't fun.
| IshKebab wrote:
| Yeah a nice Rust or Go-based implementation of Asciidoc would
| be fantastic. Having to deal with Ruby and Gems is not fun.
|
| That's a mountain of work though and even if there is a spec,
| at this point it's complex enough and the Ruby implementation
| is enough of a de facto spec that I'm doubtful you'll ever
| make it past "this behaves differently to Asciidoctor"
| territory.
|
| Btw a more recent alternative is https://github.com/jgm/djot
| which actually _does_ have multiple implementations and looks
| like a way better option than Markdown, but maybe not as
| powerful as Asciidoctor still. I haven 't tried it.
| YakBizzarro wrote:
| Oh yes, I could mot agree more. We moved from Antora/asciidoc
| to mkdocs/markdown. Overall the situation improved (better
| HTML, faster builds, syntax highlighting of code,...) but I
| miss how good writing in asciidoc was
| __mharrison__ wrote:
| Except no one uses asciidoc either, and trying to manipulate it
| with Python is painful. Sadly (or not, depending on your
| opinion), the world has converged on md.
| IshKebab wrote:
| Markdown is definitely far more popular, but I see more book-
| length specification type documents written in Asciidoc. For
| example the RISC-V spec, or Ferrocene's Rust spec.
| __mharrison__ wrote:
| I've written and published books (both physical and ebooks)
| with rST, asciidoc, and md. No format is perfect, but of
| those three md works best for me.
| keybored wrote:
| A lot of lightweight markup languages get the basics right
| (except MediaWiki). Then eventually when it comes to making
| extensions--and especially if it is supposed to be terse, or look
| it--people get into the game of strategizing ascii symbol use
| (maybe `!` for images, maybe `@` for a figure).
|
| At some point (and Rst[1] has a tendency to look like this, but
| only a little) it can start to look like some _alternative_ ,
| less regular markup language. Maybe you just use more backticks
| rather than angle "brackets". Or maybe you have (like previously
| stated) marshalled all the ascii symbols so that all the common
| stuff can have a terse representation.
|
| Maybe they should just make a regular-looking markup for the
| unusual cases/user defined things. They could do something like
| Pollen with its Latex[1] syntax inspiration.
|
| [1] Initial caps for proper nouns
| samatman wrote:
| Words are styled the way they're styled. McDonald is a proper
| noun with two capital letters, Mcdonald is simply not correct.
|
| I'll note that you didn't manage your footnote consistently,
| since you spelled MediaWiki correctly, rather than spelling it
| wrong as Mediawiki.
|
| For some reason, you decided not to do that with rST and LaTeX,
| without explaining why. Latex and LaTeX aren't even pronounced
| the same way, so I fail to see the purpose in your
| (inconsistent) stylistic choices here.
| keybored wrote:
| I can make concessions for names that are based on real
| people.
|
| I assure you my mistake was not because of good-intent
| towards Media[Ww]iki.
| samatman wrote:
| What I'm not understanding is why you've invented an
| incorrect rule for the English language and cited it. What
| purpose does this serve?
| xigoi wrote:
| Why is your username not capitalized, Keybored?
| keybored wrote:
| Poor self-esteem.
| wodenokoto wrote:
| I like writing markdown because it is so simple, but I agree with
| the author that it is too simple for more advanced stuff.
|
| But at the same time, I find the writing experience for more
| advanced stuff too poor. The author talks about references, but
| do we have a language server that can look up available
| references, headlines, figure names etc and help you auto
| complete?
|
| That's what would make me take the plunge to a more advanced
| system.
| smore wrote:
| > do we have a language server that can look up available
| references, headlines, figure names etc and help you auto
| complete?
|
| That would be a total gamechanger! Having the ability to do
| ref/doc links and not have to worry about stale topic headers
| is another thing I loved about writing in rST that I miss now
| that I'm back in markdown.
| hwayne wrote:
| Yeah, the rst lsp server (esbonio) can autocomplete and jumpto
| references in your project. I believe the markdown lsp can do
| this too, but only to a limited extent.
| Ericson2314 wrote:
| I am proud to say this is might be the first time I finally agree
| with Hillel Wayne and something (at least mildly) controversial.
| Analemma_ wrote:
| To me rST targets such a narrow middle band of scenarios that I
| can't see any compelling reason to use it. For simple documents
| where Markdown is enough, I'll use that, and if I need more
| layout configuration and control I'll use LaTeX or HTML. What is
| rST for?
| xixixao wrote:
| This is why MDX rocks. It doesn't have all of this builtin, but
| you get a lot of the same benefits.
| somat wrote:
| "markdown is a lightweight representation of html"
|
| No, markdown is a set of standards around transforming a good
| looking text file into a rich format(this is usually html, but it
| does not have to be). The most important part about markdown is
| that it is a "good looking text file". If a markdown extension
| does not result in good looking text it has failed the one point
| of markdown. This is why markdown editors leave me confused, the
| whole point of markdown is to write a nice looking plain text
| document, if you are going to use a specialized editor why not
| use a better format?
|
| Note that markdown is a terrible document format, with only vague
| presentational cues and no semantic ones. it starts to suck real
| quick. However, it is a great idea if you want a good looking
| plaintext document. People understandably keep trying to "fix"
| markdown with better semantic options but these by and large miss
| the point of markdown leaving a ugly document.
|
| So RST may be the best thing since sliced bread, but it is not
| really in the same category as markdown, the plaintext for one is
| decidedly ugly.
| Ericson2314 wrote:
| Sure, the markdown AST is its own thing, but no doubt its a
| isomorphic to an obvious subset of HTML and that's not a
| coincidence.
|
| Moreover, you are missing Hillel's second point, which is that
| there is nothing like an "abstract node" syntax which can be
| used for custom extensions. Lisp has (NAME ...) and XML has
| <NAME>...</NAME>, and these are separate from the _choice_ of
| NAME.
|
| (GitHub-flavored) Markdown's one extensible thing is
| ```NAME ```
|
| but this isn't so useful because the inside is unstructured
| text (on purpose). You want a custom node which doesn't escape
| everything within, so you can have more regular or custom nodes
| on the inside.
| smore wrote:
| Markdown has a great linter in markdownlint. When I worked in
| rST, I found the syntax to be super extensible, and tables much
| easier to write (list tables! amazing!) but without an effective
| linter, writing in rST was consistently painful.
|
| Whitespace has meaning, so I had to set up all sorts of indent
| highlights and dots for each space in my IDE to try to avoid
| screwing up the syntax inadvertently.
|
| rst-lint and others exist, but don't seem to be maintained, and
| didn't seem to have documentation about how to add support for
| custom directives (which are definitely one of the key advantages
| of rST).
|
| I'd write in rST again, but without an effective linter to stop
| me from making easy mistakes, I wouldn't be happy about it.
| SparkyMcUnicorn wrote:
| I believe Mozilla uses rstcheck for linting, and it's actively
| supported.
|
| https://github.com/rstcheck/rstcheck
| Animats wrote:
| If you want all that extensibility, use TeX or something similar.
| Or write HTML yourself. Markdown was supposed to be _simple_.
| Yes, you can 't do everything you can do in HTML. That's the
| point.
| pradn wrote:
| I was thinking of how to setup a simple static blog without the
| baggage of a full-blow framework. Of course, I'd be re-inventing
| the wheel, but at least it'll make sense to me, personally.
|
| What I came up with:
|
| * Each page gets its own folder.
|
| * An optional METADATA file in each folder has stuff like the
| type of the page (blog post, photo gallery, code listing).
|
| * The index file can be in Markdown or rST or something. I'd just
| branch to a different parser based on the file name suffix.
|
| This is simple and lets me evolve the blog over time.
|
| For a personal blog, an ideal mix might be just branching to a
| different HTML converter based on the
| vunderba wrote:
| I have a customized version of pelican which is a python based
| static side generator. It basically supports this type of
| structure, except that in place of a physical separate meta-
| data file all the metadata goes in the front matter section at
| the top of the markdown file, and it gets stripped out of the
| actual rendered HTML.
| pradn wrote:
| That makes sense. The only reason to separate the metadata
| out is to avoid having to parse the main content files for
| front-matter. Plus the metadata files themselves could be in
| several formats, if necessary. I don't see a great need for
| that, however.
| lmm wrote:
| Hugo/Jekyll/etc. all work the way GP described too.
| photonthug wrote:
| I've done this thing a few times where I have a nice layout of
| about 5-10 pages of markdown docs, themselves rendered from more
| dynamic jinja templates, and feel that life is pretty good. Looks
| great, got a real build process for auto docs, but too big for a
| monolithic GitHub readme. Now the pain starts.
|
| GitHub's own docs for project pages don't work. Do I need a
| .nojekyl file, are gh-pages branches still required? Is there a
| config error in the repo or did changes just not prop? I guess
| I'll try actions. Fast forward a few hours and this is getting
| unreasonable, haven't looked at read the docs in a while, let's
| see if that works. Ok it's being weird and wants sphinx maybe,
| let's get sphinx to work with markdown, ok cool. The build works
| but the page width is broken after deployment even though I can't
| reproduce on my machine so it must be the ads injection on the
| community tier.
|
| I know all this is working fine for _lots_ of projects and have
| done it myself in the past. It works after it's working. But it's
| all so unbelievably fiddly. Bottom line, Markdown vs Rst isn't
| even a choice /pain point on my radar, it's more down to finding
| that good fit for medium sized docs projects / static hosting.
| paholg wrote:
| Have you looked into mdBook? I haven't used it myself, but I've
| enjoyed the documentation of many projects that do and it seems
| really nice once you get past the point where a single readme
| file works well.
|
| They also have some nice instructions on automated deployments.
|
| https://github.com/rust-lang/mdBook
| photonthug wrote:
| Thanks, but this does not seem to involve hosting? What I'm
| saying is, static site _generation_ is no problem at all,
| because even without all the choices for frameworks, pretty
| much everyone has to speak at least one templating language
| and read /write both markdown and rst anyway. But it's
| surprising that writing your project docs and rolling your
| own static-site generator is _faster_ than figuring out
| github-pages and /or readthedocs hosting from scratch.
|
| For hosting static sites, I actually like AWS amplify, and
| integrating it with github seems currently easier and
| certainly more flexible than trying to use github pages. But
| I don't really want the hassle of a custom domain or a subdir
| on existing inappropriate domains for every new project I
| start.
|
| This isn't about being cheap either BTW, I think it's
| important that self-hosting should NOT be the best way to get
| a friction-free setup for small-to-medium sized project docs.
| There's a major benefit just to the recognizable domains for
| github-pages / readthedocs, which is that I know I'm about to
| look at some kind of technical project documentation that is
| most likely a labor of love, rather than marketing fluff or a
| "sign up for the preview here!" bait and switch.
| paholg wrote:
| That's what I meant by instructions on automated
| deployments. MdBook generates HTML, so you don't need
| anything fancy to host it.
|
| This example shows a fairly short GitHub action to deploy
| to GitHub pages: https://github.com/rust-
| lang/mdBook/wiki/Automated-Deploymen...
| runningmike wrote:
| Everything you can do with rst can be done now with markdown. But
| easier and better. The toolchain is superb now. MyST extends
| Markdown for technical, scientific communication and publication
| - https://mystmd.org/ and use Jupyterbook, which builds upon
| spinhx.
| JoshTriplett wrote:
| I do appreciate that reStructuredText is extensible and Markdown
| (currently) isn't. I don't think that's an argument that
| outweighs rST's verbosity. But I do think it's an excellent
| argument for _adding_ a standard extension point to Markdown.
| osmarks wrote:
| I solve this for my usecases with custom Markdown rendering which
| accepts a few new block elements (via a markdown-it plugin).
| https://github.com/osmarks/website/blob/master/src/index.js
| KronisLV wrote:
| I like Markdown because it's simple and doesn't give me that many
| headaches.
|
| You know what I don't like? HTML, for user submitted content in
| particular. The mess I've seen, after someone opted for using
| HTML for messages in a system, because that's what JS based
| editors were available for at the time. Endless need to work
| against XSS, with more and more incremental updates needed to the
| sanitization logic, some of which broke the presentation of the
| data in the DB.
|
| Never again. Markdown, BBCode, anything but that.
|
| As for docs? Currently just some Markdown, because that's what
| GitHub, GitLab, Gitea and others all know how to render.
|
| Maybe something like https://www.mkdocs.org/ for the more
| standalone use cases.
| 8organicbits wrote:
| > it's that simple markdown is exceptionally bad. It doesn't have
| a uniform extension syntax or native support for pre-render
| transforms.
|
| I feel like "simple markdown" is a straw man here. If you're
| doing anything complex with markdown you're going to pick a
| flavor and learn it. Many flavors of markdown can do the things
| described.
|
| Here's a Hugo figure which looks easier to understand than the
| "ugly rST" equivalent: https://gohugo.io/content-
| management/shortcodes/#embedded-sh...
| RomanPushkin wrote:
| No offense, but when I downloaded a sample PDF I expected to see
| a better formatting. The file is little bit clunky. I think it's
| not a failure of a formatter, but the design in general. The
| default markdown formatter in Leanpub works good enough, to a
| degree when I don't need to think about it.
|
| So, while I understand all the good parts, I am still kinda not
| convinced it's a better option looking at the final product.
| hwayne wrote:
| No offense taken! Sphinx gives a lot of options for customizing
| pdf formatting, but I'm not thinking about that just yet. Step
| one is to get the book's content done, step two is to revise
| the content, step three is to revise it again... Getting it to
| look good is on my list, but ultimately a problem for future
| me.
| meribold wrote:
| Wasn't reStructuredText the one where you can't make text a link
| if any of it is bold/italic/monospaced? IIRC, nesting of inline
| markup is generally not possible. It works in Markdown...
| hwayne wrote:
| Yes, and this sucks.
| remram wrote:
| I had to scroll way too far to find this. All the arguments for
| RST are about how much more expressive the language is, how
| much care was taken in making it an abstract document tree. Yet
| there are simple trees you can't encode, even common ones that
| markdown handles fine.
|
| I'm not using a language simply because it was aiming at
| something better, if it missed the mark.
| xigoi wrote:
| > IIRC, nesting of inline markup is generally not possible. It
| works in Markdown...
|
| How do you write <i><b>x</b>y</i> in Markdown (without using
| HTML tags)?
| meribold wrote:
| Maybe Markdown doesn't allow arbitrary nesting of inline
| markup, but the combinations I actually wanted so far work.
| With reStructuredText, OTOH, I ran into limitations even
| though I didn't try to commit typographic atrocities.
| remram wrote:
| _**x**y_ works fine, I tried on GitHub: https://gist.github.c
| om/remram44/8cd460aef9020aa53d538b82cb4...
| xigoi wrote:
| Oops, I forgot that underscores are a thing :D
| ideasman42 wrote:
| Right, this is the one fairly clear down-side of RST, in
| practice I've found it's never been an issue - but it does seem
| like a strange constraint.
|
| If you really want you can define bold italic text using some
| styling magic, but that's quite awkward.
| Arainach wrote:
| >To which I say, are you really going to avoid using a good tool
| just because it makes you puke? Because looking at it makes your
| stomach churn? Because it offends every fiber of your being?"
|
| Yes. A thousand times yes. Because the biggest advantage of
| Markdown is that it's easy to read, and its second-biggest
| advantage is that it's easy to write. How easy it is to parse
| doesn't matter. How easy it is to extend is largely irrelevant.
|
| Markdown may or may not be the best tool for writing a book, but
| Markdown is the best tool for what it does - quickly writing
| formatted text in a way that is easy to read even for those who
| are not well versed in its syntax.
|
| I don't want to write a book. If I did I'd use LaTeX before RST.
| I want something to take notes, make quick documentation and
| thread comments.
| pclmulqdq wrote:
| I am probably in the 90th percentile of TeX users, but I have
| to say that it's hard for me to think that there's much space
| between markdown and TeX for another typesetting language.
| Markdown is easy to write and read but very constrained, while
| TeX is a bit harder and essentially infinitely flexible.
|
| The biggest issue I have seen with TeX is a people problem:
| people frequently write spaghetti TeX with horrible style. This
| is terrible, but it is not actually a language issue. Writing
| it with a "docs are code" mindset can produce some very clean
| results. The second biggest issue is that there isn't a good
| TeX -> HTML compiler.
| slaymaker1907 wrote:
| You should check out Scribble which uses Racket. It has a
| bunch of different renderers including HTML and Markdown.
| However, unlike Markdown, you can easily write extensions for
| it in Lisp, even within the document itself.
| https://docs.racket-
| lang.org/scribble/running.html#%28part._...
|
| I suppose that makes it inappropriate for something like
| rendering comments, but it's a great way to write documents.
| I used it a lot for writing papers since there's a lot less
| boilerplate and was much easier to use than TeX.
| conaclos wrote:
| Maybe Typst (https://typst.app/) is a good in-between?
| josephg wrote:
| I used typst for a recent project and I love it. It's
| essentially all the power of latex but with modern
| sensibilities. And it's a cute little programming language
| - with support for variables, functions, json data loading,
| 3rd party libraries, and all sorts of other nice to haves.
|
| I just wish the typst compiler had a way to output html. It
| would be perfect for making online documentation and blog
| posts.
| enema_bag_jones wrote:
| I see typst mentions HTML output, is this only possible
| with something besides the the CLI? It looks very cool,
| going to try it out at the first opportunity.
| flokl wrote:
| HTML output with Typst isn't possible yet, but it has a
| high priority.
| reknih wrote:
| For the upcoming release, we decided to prioritize print
| layout and the shortcomings we have there. The release
| after (think late fall) will focus on HTML and accessible
| output. The plan is to create a turn-key solution for
| technical writing, docs, and document automation.
| josephg wrote:
| Thankyou for your work! It's a delight.
| g8oz wrote:
| Indeed, I don't see the reason for someone to learn LaTex
| now that Typst is here.
| auggierose wrote:
| Are you an actual LaTeX user? If so, what have you used
| it for that you can now use Typst for? For me, the
| answers are yes, and nothing.
| red_admiral wrote:
| TikZ/PGF ?
| nrr wrote:
| "The second biggest issue is that there isn't a good TeX ->
| HTML compiler." This is the crux of the problem in using just
| TeX for writing books: it focuses on producing camera-ready
| output at the expense of literally everything else.
|
| reStructuredText isn't itself a typesetting language. It's
| meant to be something of an interposer between the semantic
| meaning of what you're writing and the thing that does the
| typesetting. The hope is that it, unlike something heavily
| constrained like Markdown, gives you the tools to capture
| that semantic meaning and transform it into something that
| can be typeset.
|
| Like, the goal isn't to throw out TeX. The goal is to be able
| to target TeX as a typesetter along with Web browsers and
| e-book readers and even things like GNU info and troff
| without having to rewrite the content wholesale to fit each
| one.
| pclmulqdq wrote:
| Personally, I would rather just have TeX itself target the
| web rather than wedging another layer into the typesetting
| stack. As far as I know, other than the sheer size of the
| language, there is nothing fundamental stopping someone (I
| guess me, eventually) from writing "htmlatex."
|
| Modern web pages are already designed with "camera ready"
| in mind, essentially with browser width being the only
| thing that changes layout.
| nrr wrote:
| My point is more that TeX is a typesetter just as a Web
| browser is. They're incompatible typesetting systems with
| wildly different command languages.
| justincormack wrote:
| I think the poster above wants to run TeX in js to format
| the text. I have seen a bunch of hyphenation and suchlike
| stretching back years not sure about running a full
| engine.
| bitwize wrote:
| TeX is old and busted; Typst is the new hotness. Written in
| Rust, too!
| pclmulqdq wrote:
| "Written in Rust" matters to very few customers of your
| office webapp. And you should add that it is $8/month for
| an online platform, not free or self-hosted.
| bitwize wrote:
| What? Typst is open source and has a CLI, it's not just
| an online app.
| JW_00000 wrote:
| I think the previous author is confused because if you
| google "Typst", you end up at https://typst.app, which
| seems to only advertise the web GUI and not the open-
| source CLI tool.
| __mharrison__ wrote:
| What advice do you have for writing "docs are code" LaTeX?
|
| I find LaTeX to be the lesser of evils when creating PDFs.
| However, I rarely deal with LaTeX issues these days because
| all of the pain points have been patched away in my tooling
| that converts md to tex. However, I keep thinking something
| more modern or faster (like Typst) might make my life as an
| author easier. Compiling LaTeX with tools like rubber is
| still painful and slow.
| pclmulqdq wrote:
| A few things:
|
| 1. Separate each part of a document into different TeX
| files and include them in the main document. Each file
| should be a separate unit of the work. Only compile the
| main document when you need to.
|
| 2. Generally write with readability in mind and use
| newlines and other whitespace in the source a lot more than
| you think you should.
|
| 3. If you have common boilerplate that you frequently use
| at the top of docs, make your own package(s) for those
| commands and maintain that separately.
|
| 4. Refs and labels everywhere you possibly can. Also,
| prefixing your label names helps a lot, so \label{clouds}
| on a picture of clouds becomes \label{fig:clouds}. If you
| are writing a book, and this is the chapter on the sky,
| consider \label{fig:sky:clouds}.
| __mharrison__ wrote:
| Awesome. Can you point to a repository with an example?
|
| Also, is there a book that you would recommend for
| learning LaTeX?
| pclmulqdq wrote:
| Overleaf has several examples that are not bad. I am
| currently working on a book and the Krantz template is a
| pretty decent example of how you might structure things
| (although the package itself is total spaghetti). The ACM
| and IEEE paper examples are also both OK, but are short
| so they cut some corners.
|
| I'm not sure if there is a good book on LaTeX,
| ironically.
| __mharrison__ wrote:
| I've always used memoir.
| pclmulqdq wrote:
| The publisher wanted krantz. It's very pretty, but I
| wouldn't self-publish with it.
| red_admiral wrote:
| My problem with the TeX ecosystem is it's so non-modular.
| Bring in this package to add a new font with some extra
| dingbats, and suddenly you lose proper linebreaking inside
| boxed environments. And so on.
| bilater wrote:
| yup - my knee jerk reaction at seeing the first couple of
| samples was to recoil. Great if it works for ppl but I'm gonna
| stick with markdown.
| bityard wrote:
| I thought Markdown was clearly very silly back when it started
| gaining traction amongst developer types. There were already so
| many other better options--even at the time--for plaintext-to-
| formatted document markup languages.) But still, developers
| were designing whole apps (CMSes, productivity apps, document
| management, etc) and plugins around Markdown, sometimes as
| businesses.
|
| But then I realized, after using it in some apps, that wasn't
| really what Markdown was about. Markdown is about a bare-
| minimum amount of styling that is just as readable and at home
| in plaintext as formatted in HTML. The amount of formatting it
| supports is small _on purpose_, so that it fits in your brain
| and doesn't require a toolbar to use. It is _meant_ for things
| like comment fields, chat programs, commit messages, and so on.
| Maybe even blog articles. But it certainly is not something
| you'd want for writing the documentation for an enterprise-
| grade product.
|
| These days, I write Markdown even in place where it will never
| be rendered into HTML. Because it's quite readable as-is. (And
| I wish HN supported it.)
| packetlost wrote:
| > But it certainly is not something you'd want for writing
| the documentation for an enterprise-grade product.
|
| I guess that depends. If you're making a print manual, yeah
| probably not. IME markdown gets painful as soon as you start
| doing a bunch of tables.
|
| Most enterprise _web applications_ would probably be
| completely fine with just markdown-based docs.
| paholg wrote:
| I think a good example is all of the wonderful
| documentation that's been created with mdBook.
|
| Heck, the Rust book was written with it, and they also made
| a print edition, so maybe markdown is enough even for that.
|
| https://github.com/rust-lang/mdBook
| steveklabnik wrote:
| Carol put in a tremendous amount of work to build tooling
| to go between Markdown and Docx. The publishers used the
| docx versions for print.
|
| That doesn't mean that I think Markdown is inadequate or
| the wrong decision, but it's not just a "write in
| Markdown and you're good" sort of situation.
| paholg wrote:
| Ah, good to know! Is that tooling public anywhere, or was
| it pretty tailor-made just for the Rust book?
| steveklabnik wrote:
| Both public and tailor-made: https://github.com/rust-
| lang/book/tree/main/tools
| paholg wrote:
| Awesome! You and Carol rock!
| steveklabnik wrote:
| Thanks! She gets 100% of the credit in this case though
| :)
| brnt wrote:
| I can find here the process of converting docx to md, but
| not the reverse. I see the material is checked into the
| repo in both formats. Does that mean the docx's are your
| master, and you generate the markdown from it for diffing
| and building HTML?
|
| I'm investigating how to switch an organisation away from
| a docx-only mess of a documentation system, and it looks
| like you might have found a process that'd work for us,
| and let people keep using docx if they have to.
|
| I wonder what all those binary blobs do to the git repo
| though.
|
| Thanks for any info!
| steveklabnik wrote:
| You'd have to ask Carol, with the way we split the work,
| she handled all of this.
|
| From my perspective, the markdown was the master copy.
|
| Sorry I can't be of more help!
| Terretta wrote:
| The link below (https://github.com/rust-
| lang/book/tree/main/tools) could imply the book was
| written as Word .docx with named styles, which enabled
| transformation into markdown for the mdBook?
| tetha wrote:
| I arrived at a similar conclusion, just from the other
| direction: It is really hard to get people to document. It is
| even harder to get those people to care a little bit about
| formatting.
|
| Markdown is... limited, I acknowledge. But with a very small
| amount of learning, markdown is as fluent and simple to write
| as normal text. In fact, 90% of what I wrote before I knew
| markdown was valid and decently formatted markdown already.
|
| If you asked people who don't document to document in rST or
| tex... then you'd have no documentation at all. Because that
| suddenly adds a lot of effort on top of what you want to
| write down.
|
| Now for some customer-facing whitepapers and documentation,
| we do use rST. But there you have people who are tasked with
| paying some effort to create some decently looking docs. Not
| trying to coax developers into writing down some of their
| state of mind while doing stuff.
| unethical_ban wrote:
| Yes!
|
| Markdown is great because it is a way to write and store
| documentation in plaintext, in a way non-documentarians can
| follow.
| duskwuff wrote:
| And it's been making a ton of headway even outside that
| context -- I've seen occasional formatting goofs in
| online newspaper articles that indicated they were
| authoring their content in Markdown. (Which makes sense!
| News rarely requires complex formatting.)
| eru wrote:
| Yes, though I would expect most news-folks to use some
| form of WYSIWYG for writing?
| zelphirkalt wrote:
| Although, I have to say, it is a sad state of afairs, if
| rST is already too difficult for a person with the job role
| "programmer" to use. If this is already the threshold,
| which would stop them from writing documentation, then I
| have my doubts about the quality of documentation, that
| they will write in Markdown.
| fireflash38 wrote:
| Agreed. Mandate function docstrings? You'll get "Function
| FlargleBlab blabs the flargle" docstrings. Just useless.
| lmm wrote:
| Small barriers matter. Anything that kicks you out of the
| flow makes a huge difference. And rST is confusing enough
| often enough to kick you out of the flow.
| runlevel1 wrote:
| Ironically, that was my argument for getting rid of
| Confluence. Confluence should be _the_ low barrier to entry
| solution, but its buggy, clunky GUI ends up actively
| punishing anyone who dares try to update docs. So a repo
| full of markdown files with a self-merge pipeline ends up
| being lower-resistance.
| AndIHateLatex wrote:
| I wonder if Spotify was right on the money with their
| Techdocs approach. It's all just Markdown files being
| rendered in another format, and the edit button is just
| sends you to a github or equivalent editing page. People
| want the idea of a platform... but do they need one?
| eru wrote:
| Well, you could get similar results by just spinning up a
| copy of the Wikipedia software. Their formatting language
| even looks enough like markdown in practice (despite
| appearing earlier).
| keybored wrote:
| Markdown is like a virus of an idea:
|
| 1. Apparently simple enough to implement to get the basics
| right (not that I could do it)
|
| 2. But there is plenty of room for accidental edge cases in
| the implementation
|
| 3. Many then implement it with or without edge cases
|
| 4. But it's not enough because a lot of the people who use it
| are _programmers_ so they naturally want to extend it to do
| just a little more
|
| 5. Now the standardization effort (Commonmark) has to take
| all of those edge cases into account plus have to figure out
| how to deal with extensions (especially for popular ones)
|
| 6. Then you get a heroically (in terms of effort and grit)
| wordy standard
|
| All for the initial idea which is so simple that it seems
| redundant: look as good plain as rendered. (Then what's the
| point of rendering it, and in turn what's the point of a
| formal syntax instead of the (still existing) ad hoc email
| and whatnot conventions?)
|
| Right now it's fantastic for chat applications (here you
| definitely want rendering and not the visible markup). It's
| been pretty good for things like forum comments as well. With
| the exception of block quotes which are a pain to fiddle with
| (the only prefix syntax if you don't include the indentation-
| for-code since that is de facto optional now that so many
| applications support code fences... all because that's how
| email does it).
| bitwize wrote:
| Markdown is the Unix of rich text formats.
| gm3dmo wrote:
| Ready for Markdown wars?
| cqqxo4zV46cp wrote:
| To be fair, John Gruber offered up a completely deficient
| "standard" and a buggy as hell Perl parser implementation.
| Yet still wears "I created markdown" as a feather in his
| cap, strongly insists to this day that it was a good idea,
| and says "the canonical markdown docs are on my blog!
| Nothing else is markdown!" Things like CommonMark were
| absolutely integral to Markdown's current success. It was
| way more about fixing John's mistakes than adding more
| functionality.
| KerrAvon wrote:
| But nobody (relatively speaking) uses CommonMark, and
| everyone uses Markdown
| input_sh wrote:
| They're not separate things, but a more consistent
| implementation of the original idea. GitHub, GitLab,
| Reddit, Stack Exchange... they're all adhering to
| CommonMark specification, not the original Markdown
| specification.
| billti wrote:
| The hours I spent chasing down the edge cases with inline
| html! There's some real nuance to the spec there.
|
| You need inline html fairly often for anything non-trivial,
| and some of the rules certainly aren't intuitive or easy to
| remember.
|
| That said, like JSON, it won by being both simple to grok
| and good enough for most use cases.
| deathanatos wrote:
| > _3. Many then implement it with or without edge cases_
|
| > _it's fantastic for chat applications_
|
| Slack is the absolute _worst_ at it; I am unable to at all
| figure out what its "parser" (which feels like cobbled
| together regexes ... but even then ... not?) is doing.
| [link text](URL)
|
| is sometimes a link. But sometimes not! Sometimes Slack
| mutates your message, and then renders the mutated version
| -- and this is visible if you subsequently edit your
| message, as what is now there != what you type. When it
| _works_ it is nice, but when Slack decides it doesn 't like
| _that_ message, in particular, it can just be a pain to get
| it to do what you 've typed.
|
| Worse to me is that Slack considers "we mutated the input
| you typed, and then proceeded to misrender it" as "Won't
| Fix/Working As Intended". (I reported it a while ago, that
| was the resolution.)
| m-p-3 wrote:
| Google Chat is also somewhat terrible at it.
|
| Want to italicize some text? Easy right, just do it like
| *this*.. nope that will bake it BOLD, gotta write it like
| _this_ for italics.
|
| https://support.google.com/chat/answer/7649118
|
| The only thing I like is that you can colorize text, but
| there's no syntax for it, you gotta highlight it then
| choose a color in the formatting toolbar.
|
| It's annoying to no end when you memorized the syntax and
| Google decides to not even follow it.
| deathanatos wrote:
| Way back in the day when I was on IRC, I usually read
| them as, *bold* /italics/
| _underline_
|
| ... which would have made _sense_ , if you stop to think
| about the characters. (But of course humans are wibbly-
| wobbly in what they'll choose, so context is context.)
| Alas, bold is now different in everything, it seems, and
| I can never remember which is which, aside from Discord
| which gives visual feedback.
| pitaj wrote:
| I think one of Markdown's biggest mistake was making `*`
| and `_` interchangeable. It should have been `*bold*` and
| `_italics_` from the beginning.
| m-p-3 wrote:
| I agree with you on that.
|
| What about * for bold, / for italic and _ for underline?
| ysavir wrote:
| / is too commonly used, such as when making a list of
| replacements/alternatives/synonyms. It works fine when
| it's just the text as written, but if it was parsing and
| turned that list to replacements _alternatives_ synonyms,
| it would only be getting in the way.
| fragmede wrote:
| fwiw, I find it's easiest to copy a url to my clipboard,
| go back to slack, type the words, then select them, and
| then hit ctrl-v, which doesn't get rid of the text but
| instead makes it a link with the selected text as the
| link text and the pasted text as the url.
| keybored wrote:
| Slack is pretty bad yeah. It might work great if you
| write a whole message perfectly without typos. Then
| immediately when you have to go back and edit things like
| code snippets it gets confused: often you get raw
| backticks in the rendered message since it's so confused.
|
| And for technical stuff I very often have to edit my
| message.
|
| And yes: don't even get me started on having to think
| about whether I can write a link or whatever in MD or if
| I have to use the bells and whistles buttons in Slack.
|
| Considering that Slack is used by both technical and non-
| technical users they should, well, really have a way to
| toggle between rendering the text immediately while
| typing and having it in the raw form while typing.
| Because editing it raw would be much less confusing for
| me.
| Zacru wrote:
| >having it in the raw form while typing
|
| This is actually an option in the settings (on desktop,
| at least).
| keybored wrote:
| Aw that's embarrassing. Thanks.
| strken wrote:
| > All for the initial idea which is so simple that it seems
| redundant: look as good plain as rendered. (Then what's the
| point of rendering it, and in turn what's the point of a
| formal syntax instead of the (still existing) ad hoc email
| and whatnot conventions?)
|
| It's intended to look as good as possible in both mediums.
| It is not possible for the raw text to look as good as the
| rendered text and still be easily writeable, because the
| raw text cannot generate visual hierarchy using font size
| and weight.
|
| I suspect you know this, but when you say readable raw text
| seems like a redundant idea, I'm not sure what point you're
| trying to make.
| keybored wrote:
| > I suspect you know this, but when you say readable raw
| text seems like a redundant idea, I'm not sure what point
| you're trying to make.
|
| I was referring to the sentiment that "MD looks so good
| that I might never even render it".
| rcarmo wrote:
| Yeah, I still have thousands of Textile pages, but all of my
| newer stuff is in Markdown...
| hinkley wrote:
| As we've gone horizontal on tool chains instead of vertical
| like we used to, what you want is a bunch of mentally cheap
| tools with high bang for the buck. Get in, get out, move on
| to the next of fifty tools you have to deal with each week.
| tjoff wrote:
| > _Markdown is about a bare-minimum amount of styling that is
| just as readable and at home in plaintext as formatted in
| HTML._
|
| My gripe is that it really isn't. Because markdown inevitable
| includes images or something and the instant it does it
| doesn't hold up to it's killer feature. Now you can't read it
| properly, so now you have to find a generated version, or
| hunt down the images manually, or generate the output
| yourself.
|
| Alternatively, the document is so trivial that even markdown
| formatting is too much (just distracts) and doesn't add
| anything of value.
|
| It isn't that bad, it just never seems to make any sense for
| files. It does make sense for web forms though but that's
| only because you never read the markdown, you just write it
| and the output is generated on the fly.
| 8organicbits wrote:
| When you use one of the extensions, like Hugo's figure,
| which has alt-text support you're about as close to that
| goal as possible. An image can't be stored in human
| readable plain text.
|
| The alternative is WYSIWYG formats that aren't plain text.
| tjoff wrote:
| Doesn't matter how close to the goal you get if it is on
| the outside...
|
| I'm gonna be annoyed if I clone your repo, open the
| readme.md and now have to figure out how to read it.
|
| Plain text is awesome, for plain text. If it isn't plain
| text might as well use a pdf.
| 8organicbits wrote:
| There's no reason for this to be all or nothing. This
| seems perfectly readable to me: 
|
| Even if you've never seen markdown before, it's pretty
| obvious.
| AndIHateLatex wrote:
| I'm having a bit of trouble understanding the problem
| here as well, and kinda hope people expand on it, because
| insight might think of what to do better.
|
| I edit a number of wikis. This leads to an inevitable
| amount of instances of having images floating aside the
| the text. Sometimes there's some peculiar stuff done with
| tables. But we never actually intermix the text content
| in a completely unreadable way, at least outside of
| templates and modules, which are NOT text content meant
| to be read in the first place and are NOT markdown
| either.
|
| Every section of text only has text content, and the only
| alterations to the text come as syntax that strictly
| surrounds the affected text. If images have peculiar
| formatting demands, they will exist outside of text (Such
| as a CLR).
| tjoff wrote:
| How often do you refer to the logo? Try something like
| this: 
|
| You know what it is, but you have no idea what it looks
| like. Maybe it is a garbage picture that doesn't really
| add anything. Or maybe the picture is a necessity to
| understand the architecture of the system. Someone put
| the time and effort to create that picture, you'd imagine
| for a reason. Maybe worth having a look?
|
| Maybe, just maybe, looking at that image is a good idea
| to do before reading 20 pages of documentation? Probably
| a good idea to look at even if you only intended to
| glance at the documentation for 20s.
|
| Because that's what markdown mostly is in my experience,
| documentation. And the images, if they exist, often are a
| very important part of that.
|
| Now some images are garbage, but you don't know because
| the alt-text will not be "Superfluous image that doesn't
| add to the understanding". Maybe it depends on the
| reader, is the reader fluent in design patterns (and
| crucially, is the project following the design pattern as
| is or have they made their custom modifications to it?).
|
| But in reality it will likely be a flowchart. Kind if an
| important piece that really help when reading the text.
| Or maybe just an image of a header and all the field
| sizes. Can you do it without it? Sure. But remember that
| not all documentation is perfect, it might not have had
| someone pouring his/her heart in it. It might have been
| rushed. So as often is the case you actually do need both
| the image and the text, not just to help understanding
| (which alone really is reason to make sure you look at
| both) - but because you need both to get all the
| information.
|
| I sigh when I see a .md. Especially in documentation,
| because in reality that probably means that I have to
| either get the dependencies and look up the build process
| to build it myself. Or I have to go to the official
| project web page and browse the documentation there.
|
| If it is a .txt or .pdf I know what I'm in for, and I
| know I have the tools needed to view it.
| 8organicbits wrote:
| You're still using all or nothing thinking. If I wanted
| to see the diagram then I'd open `system-hierarchy.png`
| by navigating to that file and clicking on it. Besides,
| you rarely need to build a markdown file yourself; open
| it on Git[Hub|Lab] or open the project's web docs. You
| could prefer a .txt, but that can't display images at
| all.
| tjoff wrote:
| Markdown can't display images at all, either... Which is
| my point.
|
| (you know you can write paths in a .txt file too?)
| SPBS wrote:
| > But it certainly is not something you'd want for writing
| the documentation for an enterprise-grade product.
|
| MDN documentation is written in markdown. I've always felt
| this was a resounding endorsement of markdown over other more
| "powerful" markup languages because if they can do it, why
| can't you? (not you in particular, but anyone who thinks
| markdown is inadequate for docs)
|
| https://developer.mozilla.org/en-
| US/docs/MDN/Writing_guideli...
| red_admiral wrote:
| All my documentation at work is written in a dialect of
| markdown. It's absolutely the thing you want, together with
| a good parser and content management system for producing a
| site with search, navigation etc.
| edgarvaldes wrote:
| The very next paragraph in TFA agrees with you:
|
| >...Okay yeah that's actually a pretty good reason not to use
| it. I can't get into lisps for the same reason. I'm not going
| to begrudge anybody who avoids a tool because it's ugly.
| thomascgalvin wrote:
| I _have_ used markdown to write books, and it worked just fine.
| Now, these were novels, not technical documents, but I never
| encountered something that couldn 't be solved with markdown
| plus some occasional HTML.
|
| I've also generated quite a bit of technical documentation
| using markdown, and Pandoc's extensions[1] allow you to include
| pretty much any formatting you might require, complicated math
| and syntax highlighted code blocks included.
|
| That markdown can then be transformed into HTML, a Word doc, a
| ePub, a PDF ...
|
| There needs to be a _very_ compelling reason for me to reach
| for something other than markdown.
|
| [1] https://pandoc.org/MANUAL.html
| bluGill wrote:
| Most novels don't need anything more complex than a link to
| the next chapter at the end of the page. Maybe bold text, but
| a lot get by without. As such markdown will work for most.
| I've seen some novels with some really complex formatting,
| but those are rare (I read a lot of litRPG and still call
| them rare). However I mostly write technical documentation
| and I often hit limits of things markdown cannot do even
| though my documents are much shorter than a novel.
| zelphirkalt wrote:
| Pandoc is a great thing! However, lets not mix up Pandoc
| Markdown with standard Markdown. Pandoc Markdown
| intentionally adds features, that make it more suitable for
| academic writing, I believe.
| thangalin wrote:
| Here are some Markdown books I've crafted:
|
| * https://whitemagicsoftware.com/softcover/technical.pdf
|
| * https://impacts.to/downloads/lowres/impacts.pdf
|
| * https://whitemagicsoftware.com/softcover/jekyll-hyde.pdf
|
| My blog describes shell scripts to use pandoc and knitr for
| converting Markdown to PDF:
|
| https://dave.autonoma.ca/blog/2019/05/22/typesetting-
| markdow...
|
| I wrote a FOSS GUI/CLI cross-platform desktop application to
| replace those shell scripts:
|
| * https://keenwrite.com
|
| * https://keenwrite.com/screenshots.html
|
| * https://www.youtube.com/playlist?list=PLB-
| WIt1cZYLm1MMx2FBG9...
|
| I'm using KeenWrite to write a sci-fi novel and can produce a
| standard manuscript format in seconds (because the content is
| kept separate from the presentation).
|
| Regarding technical documentation, I extended Markdown in
| KeenWrite with a consistent cross-reference syntax for
| tables, figures, equations, etc.
|
| * https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/docs/re
| f...
| thesnide wrote:
| about keenwrite, touting "producing beautifully typeset PDF
| files" and not giving a single PDF example, ideally its
| documentation, is a missed opportunity, to say the least
| ;-)
| sureglymop wrote:
| And it actually can be easily extended with custom blocks ( :::
| ). https://github.com/vokimon/markdown-customblocks
| ajross wrote:
| > Because the biggest advantage of Markdown is that it's easy
| to read, and its second-biggest advantage is that it's easy to
| write.
|
| I'd go so far as to flip those two. By far, it's more important
| to ensure that documentation _can be easily written_ (the
| raisin d 'etre of MD) than it is to optimize for the job of the
| people trying to collate/edit/format/improve/maintain the
| documentation (something that RST speaks to, primarily).
|
| Because the primarily failure mode in this space is _not_ that
| we have imperfectly edited documentation. _It 's that we lack
| docs at all, because the hackers didn't understand the doc
| tools_.
|
| In Zephyr, we use RST. And... it's fine. I've made my peace
| with it. But "please write some docs" is a routine comment in
| review, and in my experience many-probably-most contributors
| just don't know how and don't want to take the time to learn.
| The barrier to markdown would be much, much lower.
| philistine wrote:
| > I don't want to write a book. If I did I'd use LaTeX before
| RST.
|
| 100 times yes. Markdown for light styling. LaTeX for anything
| else. The next revolution in standardized text parsers will not
| come from replacing Markdown, but from replacing LaTeX.
| lapinot wrote:
| Every heard about https://typst.app/?
| qwerty456127 wrote:
| > Because the biggest advantage of Markdown is that it's easy
| to read
|
| Do you really read Markdown in plain text editors? I only do
| occasionally (nevertheless I'm glad I can). Most of the times I
| use tools like Obsidian, Typora, Markdown Monster etc.
|
| HTML is just _too_ bad for plain source reading relatively to
| Markdown and too complex for reliable mapping between what it
| is looks, what it means and what it is.
|
| This said, something slightly more complex than Markdown while
| slightly more elegant, less chaotic and more readable than HTML
| sounds a great thing to have.
|
| There certainly are cases where Makrdown seems the best choice
| - wherever simple plaintext editors are going to be used often.
| Nevertheless I doubt Markdown is the best choice for tools like
| Obsidian - perhaps people working on new projects of this kind
| should also take a look at rST or AsciiDoc.
| riidom wrote:
| I'm with you on that, I can think of one counter example
| though, and that is when you have to write your MD in
| something like VS Code. Which uses the old-fashioned approach
| of source code pane and render pane. I strongly dislike that
| and usually try to get away with source-code view only. To be
| fair, they use a tiny bit of coloring, so it's not 100% plain
| text. And the better solution is to write your MD in any
| other MD editor except VSC, of course.
| red_admiral wrote:
| When you're putting documentation in the same commit as the
| relevant code - which is good practice, at least around here
| - then it's often useful to be able to read not just markdown
| but a diff of markdown as plain text in ${editor}.
| qwerty456127 wrote:
| > I don't want to write a book. If I did I'd use LaTeX before
| RST.
|
| To me this seems a horrible decision at the stage of
| writing/structuring. I'd rather write in Markdown (this way I
| could just write, without bothering about typesetting) and only
| convert to LaTeX for publishing. I'm not proficient in LaTeX
| though - I once tried to learn it and it felt like learning a
| language of an insectoid extraterrestrial civilization -
| completely unintuitive, almost impossible to do anything new -
| what hasn't been already done by someone else enabling you just
| copy-paste your own text. IIRC it doesn't even have first-class
| Unicode support.
| anserin wrote:
| In LaTeX you also clearly separate structure and typesetting:
| you don't write
| \noindent\textbf{Introduction}\nobreak\medskip or whatever,
| but simply \section{Introduction}
|
| Macros are also pretty easy to define
| \newcommand\important[1]{\textcolor{red}{#1}}
|
| And of course it has first-class Unicode support
| josephg wrote:
| Easy is relative. Latex is sooo much uglier than typst:
| #let important(body) = { text(red, body)
| } But whatever you do, #important[Dont
| *panic*!]
|
| Docs:
|
| https://typst.app/docs/reference/foundations/function/
| nrr wrote:
| "In LaTeX you also clearly separate structure and
| typesetting ..." Not quite.
|
| The rub comes in when you want to pull that content out to
| render it in a format that isn't meant to be camera-ready,
| like a Web page or an e-book. TeX, even with Leslie
| Lamport's LaTeX macros, doesn't give you an ergonomic
| mechanism for marshalling out the semantic structure of
| your document to reuse elsewhere.
|
| You're left parsing the TeX yourself, and that sucks.
| ori_b wrote:
| Yes, that is a good rephrasing of the rest of the paragraph you
| quoted.
| eviks wrote:
| > but Markdown is the best tool for what it does - quickly
| writing formatted text in a way that is easy to read even for
| those who are not well versed in its syntax.
|
| That's not true, even at the basics it's not great, let alone
| the best: asterisks/underlines for italics already require
| familiarity unlike the much more intuitive /italic slashes/
|
| And then outside the basics it's not that easy to write/read
| either, you'll get lost in bad formatting of tables or metadata
| (tags) obscuring text or what not without proper tooling
|
| > How easy it is to extend is largely irrelevant
|
| It is relevant as then you could fix those basics if you could
| easily and conveniently extend it
| necovek wrote:
| Uhm, reST is also easy to read and write, at least where
| Markdown is easy to read and write.
|
| To me, they are largely the same thing, with slight syntax
| differences, with reST being more readable as it's clearer what
| any special syntax is about, whereas MD is more concise to type
| out -- you need to learn the special syntax whatever way you
| slice it.
|
| FWIW, reST was the default for Python "doctests": a wonderful
| feature that has fallen out of favour for some reason, but has
| the potential to be your real runnable documentation.
|
| I wouldn't write a book in either, but that's because I am
| really high on great typesetting -- I even had my own set of
| (Plain) TeX macros to do ToC generation, syntax highlighting,
| alternative math fonts, support for UTF-8 before eTeX and such
| when I did write papers and handed in coursework regularly.
| lmm wrote:
| > reST is also easy to read and write, at least where
| Markdown is easy to read and write.
|
| It isn't though. It's just a whole lot more annoying. On
| paper the syntax differences are small, but they make the
| writing experience so much worse. I wanted to like rST but it
| just isn't good enough in use.
| __mharrison__ wrote:
| Except for native Python tools like Jupyter, which have all
| moved on to md.
|
| (I still like doctests and use them extensively in my books.)
| bosie wrote:
| What do you use for the actual, non-quick documentation?
|
| Markdown is pretty bad for note taking, it has a niche
| functionality suited for basic text based note taking.
| Unfortunately that isn't the only note taking that is possible
| andrepd wrote:
| This is pretty much the paragraph that follows the paragraph
| you cited...
| makeitshine wrote:
| That was a rhetorical question in the article. It's immediately
| followed by:
|
| > ..Okay yeah that's actually a pretty good reason not to use
| it. I can't get into lisps for the same reason. I'm not going
| to begrudge anybody who avoids a tool because it's ugly.
| __mharrison__ wrote:
| rST and md are both not ideal for writing books. And LaTeX is
| even more painful. IMO using md is the lesser of two evils. I'm
| done kicking against the pricks with rST.
| kevin_thibedeau wrote:
| Markdown has 30 different flavors because it grew organically
| and has no formal extension mechanism. "What am I allowed to
| use in _this_ markdown processor? " never becomes an issue with
| reST.
| red_admiral wrote:
| Markdown has 30 flavors because it has over 30 different
| ecosystems using it. We have github flavored markdown, gitlab
| flavored markdown, MDN markdown etc. because github, gitlab
| and MDN are all using it. If you forced everyone to move to
| rst, then you'd see flavors cropping up soon too.
|
| Even if rst has a generic extension mechanism, on github
| you'll spend a lot of time referencing commits, tags, users,
| pull requests and that kind of thing. So you end up having to
| know a domain-specific language anyway, whether it's formally
| presented as an extension mechanism to the language or as a
| dialect.
| ska wrote:
| If it was only about this, personally I find org-mode is better
| than markdown.
|
| There is a big gap between a book and informal notes, docs,
| comments though. At least big enough to drive several tools
| into, or they wouldn't exist.
| skybrian wrote:
| It seems like Markdown works pretty well for writing API docs,
| where the language has a tool for generating documentation that
| also gets things like type signatures from the source code
| itself.
|
| The result of running that tool is always API documentation, so
| you might need something for docs that aren't structured that
| way.
| kaizendad wrote:
| While I definitely understand what the author is saying, the
| reality is that, for the majority of writing developers will be
| doing, having something that is easy-to-produce and easy-to-
| consume is paramount. There are tons of more powerful and
| flexible options than Markdown, but none that let you create a
| document that is both computer- and human-readable quite as
| quickly. Documentation that is written is better than
| documentation that isn't.
| bluGill wrote:
| Which is why I use rST - just as easy to write, but enough more
| powerful that I'm not left hanging when I realize I need to do
| something more complex.
|
| > Documentation that is written is better than documentation
| that isn't.
|
| I have to disagree with this. I've read too many out of date
| documents. If documentation exists that isn't correct it is
| worse than no documentation at all. The only useful
| documentation is documentation that is correct, easy to
| navigate, easy to search, and easy to update as the world
| changes (there might be more?).
|
| Good documentation is better than bad, it is debatable if bad
| documentation is better than no documentation or not (in part
| because some bad documentation is worse than others).
| Decabytes wrote:
| Another good documentation choices is Racket's scribble^1. I like
| that you can embed Racket code directly into the text, and the
| language oriented programming of Racket means the syntax is more
| ergonomic than other systems. There is also pollen^2 but that is
| more set up for online books by default
|
| 1. https://docs.racket-lang.org/scribble/
|
| 2. https://docs.racket-lang.org/pollen/
| nailer wrote:
| "Now here's how to make an image in rst:" ..
| image:: example.jpg :alt: alttext
|
| Great, I can close this article now.
| taeric wrote:
| I dislike rST for how cumbersome it is with some of its markers.
| Trailing underscores, tons of dots, non-fenced sections, nested
| lists needing extra lines, etc.. It seems actively made to make
| it hard for me to read the source.
|
| Now, granted, I am clearly ok with fenced sections. And I love
| org-mode for most all things.
| bradboimler wrote:
| Sure, for quick throwaway notes or messaging apps Markdown is
| fine. But if I'm gonna sit down and write a proper document? I
| prefer handcrafting HTML.
| geenat wrote:
| IMHO, ignoring the parsing difficulty, the main issue with
| Markdown is it's difficult to write for non-technical users- 1
| misplaced character can mess you up if you stick to the "spec".
|
| Markdown has already won over the technical users.
|
| Enjoy your infinite support tickets caused by markdown. RST does
| nothing to help this.
| gregopet wrote:
| I used to hate Markdown (am partial to AsciiDoc myself) but it
| has "won" and I've just accepted it & use it every day. Not the
| first time an inferior product did so, and won't be the last.
| There are a few hills I'd die on, but Markdown alternatives are
| not one of them.
| fefe23 wrote:
| I don't understand the argument for rST. If you need more control
| than Markdown can deliver, then write your stuff in HTML to begin
| with.
|
| I have written a ton of documents in plain HTML, including slide
| decks, documentation for customers, reports for customers, a
| blog. I have not written a book yet. If I were to write a book, I
| would use LaTeX because then the typographic fidelity of the
| output would be my paramount objective.
|
| Plain HTML is actually pretty awesome. It allows you to encode
| the structure of the document and then style if however you
| wanted. When I started in this business, you had to use LaTeX for
| that kind of flexibility. HTML has gotten a bad rep, I think,
| because it's dark side of including Javascript and a ton of
| frameworks for whatever perceived goal looks easy and seductive
| and then forces you into serfdom by obstructing future reuse.
|
| If you stick with the bare minimum HTML you'll be fine. Better
| than fine actually. Text processors can these days usually import
| bare metal HTML just fine if need be. They only fail if you give
| them the "processed food" output of some kind of rendering
| pipeline.
|
| The only other system for documentation we haven't covered in
| this thread is troff for man pages :-) Any takers?
| bluGill wrote:
| HTML is a bad choice - I want to be able to reorganize my site
| without have a million dead links. Even if I know what the
| correct organization is today, requirements will change and so
| in the future something will be wrong.
|
| With rST I can link to a section and move that section to a
| different document and the links all still work (or if they
| don't I get an error for each and so I know where to look).
| With markdown and html I link to a specific document and since
| each is a document generator there is no warning if I typo the
| page name (there are a number of tools to look for dead links
| in html). With markdown I cannot link into a section of the
| page, only the page itself (some extensions to markdown allow
| this)
| paholg wrote:
| What you see as annoying, I see as a strength. You shouldn't
| break links; they don't only exist in your site. People will
| have them bookmarked or shared on the web.
|
| There's nothing worse than finding a post online that seems
| like it will cover your exact issue, but the link is now a
| 404.
| bluGill wrote:
| I get what you are saying, but the world is not static. The
| concept of bookmarks and deep links thus is flawed because
| they do not/cannot follow changes in the world. Bookmarks
| need to take a snapshot of the reachable web (this is
| probably impossible...) or they need to expire after a few
| months so that the world can change.
|
| I would hate if all nurses manuals had to accept the
| bookmarks of some book from 1820 just because someone once
| had a bookmark to the bloodletting section.
| paholg wrote:
| As you said, it's not static. You can update the content
| of pages.
|
| You can also reorganize things and keep old links as
| 302s.
|
| At a minimum, you should be aware of when you're breaking
| links and it should be a conscious decision.
| mmphosis wrote:
| I prefer What You See Is What You Get (WYSIWYG.)
| beej71 wrote:
| I started looking at converting my books to use Sphinx (from
| pandoc) and got almost there. What stopped me was something a
| little odd: I wanted to use different fonts in a link, notably
| some proportional and some monospace in the same link. And it was
| my read that this wasn't possible...?
| westurner wrote:
| A Table of Contents instruction that works across all markdown
| implementations would be an accomplishment.
|
| OTOH, Markdown does not require newlines between list elements;
| which is more compact but limits the HTML that can be produced
| from the syntax.
|
| MyST Markdown adds Sphinx roles and directives to Markdown.
|
| nbsphinx adds docutils (RST) support back to Jupyter Notebooks.
| (IPython notebook originally supported RST and Markdown.)
| arp242 wrote:
| > When I gush about rST to other programmers, this is the
| objection I hear the most: it's ugly. To which I say, are you
| really going to avoid using a good tool just because it makes you
| puke? Because looking at it makes your stomach churn? Because it
| offends every fiber of your being?
|
| I like my Markdown documents to be nicely readable in source
| form. Because that's what I'm editing so being readable helps,
| and it's also what I read most of the time.
|
| I don't think Markdown is perfect. I have gripes. But it's "good
| enough", and damn near everywhere already so it's "in the
| fingers", so to speak.
|
| > Markdown doesn't have a uniform extension syntax or native
| support for pre-render transforms.
|
| Well no, but "Markdown" is also a standard with more
| implementations you can shake a stick at, whereas most of the
| alternates mentioned n the article are basically just a program
| written in $lang, and that's it. I think some do have a spec
| document, but also don't really have complete alternative
| implementations, so it doesn't really matter.
|
| And I get the point; for my own website I have this ... piece of
| art ... to transform some of the HTML:
| https://github.com/arp242/arp242.net/blob/master/_plugins/ma...
|
| On one hand: eww. On the other hand: it's not strictly _needed_ ,
| hard to do cross-platform, and has been working fine for a long
| time now. So whatever.
| philistine wrote:
| > Well no, but "Markdown" is also a standard with more
| implementations you can shake a stick at
|
| This ubiquity comes in large part from its lineage. Gruber
| based Markdown on the established cultural standards in raw
| text emails. The people who quickly adopted it where doing so
| based on familiarity.
| andrewflnr wrote:
| > ...Okay yeah that's actually a pretty good reason not to use
| it. I can't get into lisps for the same reason.
|
| I guess this is why he's not using Pollen, which is explicitly
| designed for this sort of thing, but based on Racket.
|
| I actually settled on rST for writing fiction manuscripts, I
| think because I actually liked the syntax? Maybe I just needed
| proper header support. I'm compiling to DOCX via pandoc, so I'm
| not using the extensibility in the slightest. Anyway, it's
| amusingly validating to see someone else use it for a similar
| job.
| unoti wrote:
| For the motivating use cases, I wonder if YAML and a simple
| script to transform to other formats as needed would be more
| effective, easier to read, easier to write, and easier to work
| with in general.
| AceJohnny2 wrote:
| No. <Michael Scott "nooo" meme>
|
| While a tree datastructure like YAML (or JSON) can be mapped to
| a document (like HTML, or PDF), as demonstrated by the
| existence of the DOM tree and the (mis)popularity of XML, the
| one lesson we should have taken from XML is that it's awkward
| and you should not mix a tree datastructure with a text
| _markup_ syntax.
|
| Do not make humans have to construct their documentation as a
| tree first. Let them do in a free-flow way, with markup, and
| have _tools internally_ convert it to a tree.
|
| We've emerged from 20 years of XML-as-a-human-readable-
| datastructure dark ages. Let's not then make the opposite
| mistake.
| remram wrote:
| What's the YAML syntax for "That's a _weird_ idea,
| [YAML](https://yaml.org/) is a data serialization language"?
| hintymad wrote:
| > .. image:: defines the image "directive". When Sphinx reads it,
| it looks up the registered handler for the directive
|
| And the author continues to explain how rST is convenient and
| flexible to a doc engine like Sphinx. This kind of argument
| confuses me as a user. That is, why would I care? I just want to
| write my doc fast with minimal effort, and couldn't give zero
| attention to how Sphinx works. Wouldn't an average user like me
| should just ask: what will rST offer that is 10X better than
| Markdown?
| crowcroft wrote:
| Markdown might not be _the best_ at anything, but it 's pretty
| good for a lot of use cases and is beautifully simple. I can
| teach a non-technical friend markdown in about five minutes.
| asmeurer wrote:
| The author claims that RST is nice because it's extensible, but
| as someone who's written some Sphinx extensions, I can tell you
| that extending RST is not as pleasant of a task as the author
| makes it out to be. I don't really know what it's like in
| Markdown world, but the underlying tools (Sphinx and docutils)
| are very difficult to work with, and make many implicit
| assumptions that make certain things difficult or impossible.
| romanovcode wrote:
| I think author should write HTML if they want extensibility so
| much. Not like RST is reading-friendly to begin with.
| ideasman42 wrote:
| Keep in mind you might not _only_ be exporting HTML.
| ideasman42 wrote:
| I've written a few Sphinx extensions ... it seemed OK to me, a
| bit awkward but long term - this is the kind of thing you do
| rarely & use often, so how nice it is to write extensions is
| barely an issue.
| innocentoldguy wrote:
| I don't mean to hijack a conversation about ReStructuredText, but
| if you're looking for a markup language that gives you more than
| Markdown, look at AsciiDoc rather than ReStructuredText. I have
| written technical documentation using all three for years and
| AsciiDoc is superior to both ReStructuredText and Markdown, in my
| opinion.
|
| For example, Markdown's and ReStructuredText's support for tables
| is cumbersome to say the least. AsciiDoc's table formatting is
| much easier to read, write, and maintain, and AsciiDoc tables are
| more robust, supporting headers, captions, custom dimensions for
| tables/rows, and complex formatting within tables.
|
| Some other benefits include:
|
| * A single, standardized format where Markdown and
| ReStructuredText do not (in other words, there are no "flavors"
| like you have in Markdown).
|
| * Concise and readable syntax.
|
| * A more gradual learning curve that ReStructuredText (probably
| due to its consistency and excellent documentation).
|
| * Superior styling options for your output.
|
| * A superior toolchain to the other two markup languages.
|
| * A rich set of built-in documentation features, so you rarely
| have to rely on third-party plugins.
|
| AsciiDoc was designed from the ground up for technical
| documentation, whereas the other two get shoehorned into that
| role.
|
| Having worked extensively with all three, I can't recommend
| AsciiDoc highly enough.
| concombres wrote:
| I love rst. I love sphinx. I've written a lot of things with it.
|
| But, I use markdown. Markdown is technically inferior, but it's
| just simpler and that's really what makes all the difference.
| There's things I can do in rst that are more logical, more
| powerful - and yet - I still use markdown and pictures.
|
| To me, it's the usual problem that I like to illustrate with a
| config file:
|
| while True: 1. You need a config. You make a text
| file and write values in it. It grows. Its unmanageable. It's
| terrible. 2. You write some proto to store the config.
| Its complex. It can do everything. It's relatively good but the
| more you use it, the more little problems show up. It looks like
| regedit, a sql database, a tree of trees, etc. 3. You
| throw it all away and write something with trade offs, that is
| reasonably simple, solve 80-90% of use cases and is otherwise
| somewhat limited. Sometimes, it feels like you might as well just
| use a text file.
| ideasman42 wrote:
| Strange that everyone seems to think it's simpler, it seems
| might be a web-developer bias here.
|
| I'm not a web developer and I don't find markdown especially
| easy/pretty/simple... I find it annoying when the same markdown
| can't be used in different places based on the rendering engine
| and there aren't standard ways to extend it.
|
| Also, having trailing whitespace as part of the spec.. tsk!
| ktosobcy wrote:
| If it's a matter of preference then whatever.
|
| We had our documentation in asciidoc and it was awesome to write.
| We migrated to RTD/Sphinx/rST mainly for 1) better handling of
| i18n and 2) better handling of multiple-version-documentation
| (switching between versions)... and I loath rST every day. It's
| syntax is just abysmally awful and the tooling sucks (seriously,
| it's not just bad... it sucks!).
|
| Nowadays there is antora but still - i18n is still a problem...
|
| And markdown - as a simple tool to add some simple and basic
| formatting is just awesome and it's easily readable even if you
| don't have parser and end up having to read plaintext...
| wiresurfer wrote:
| I have grappled with the same conundrum. Here are my takes on
| documentation writing. First is the X axis of type of document we
| are called on to write. 1. There is personal writing. books
| included. 2. Personal Blogging and Dev Rel publishing. 3. Then
| there is developer tool documentation. [code snippets, sdks,
| libraries] 4. Then there is product documentation. [images,
| steps, how tos]
|
| Then there is Y axis of tools. 1. markdown and with it Z axis of
| mkdocs, hugo, KMSs like obsidian <name everything markdown here>
| 2. rst 3. org? 3. wysiswg editors or anything custom.
|
| I find - markdown both ubiquitous and somewhat approachable. for
| most beginners. with obsidian/logseq/... it can also work for non
| tech writers too. its also more widely supported. [Github i am
| looking at you] - dev rel/dev tools docs with sphinx and rst is
| absolutely godsend! also a vibrant ecosystem. - product docs with
| mkdocs x markdown if its a consumer facing docs with lots of
| images and need for customizing. rst if its a developer product.
|
| ---
|
| I write my blog in markdown, https://blog.shaishav.kr
|
| My team maintained https://userdocs.rapyuta.io in markdown for
| the last 4 years. https://github.com/rapyuta-robotics/rapyuta-io-
| docs
|
| - we also maintained https://sdk.rapyuta.io/ &
| https://cli.rapyuta.io/ both in semiautomated rst + github
| actions setup
| zelphirkalt wrote:
| rST is also much more powerful than Markdown. You can write an
| academic papar properly in rST. You can add custom directives
| implemented in Python and stuff. If I could make everyone use rST
| instead of Markdown, I would.
|
| Of course Markdown is simpler in many aspects. But therefore it
| lacks many things that rST has.
| necovek wrote:
| It's funny how people are commenting as if reST was created as a
| competitor to MarkDown: it's actually quite the opposite. reST
| was a 2002 evolution on StructuredText from even earlier, and MD
| was first publicized in 2004.
|
| They've got extremely similar goals, and for the most basic text,
| both read and write like plain text too. And it was obviously a
| time when this thing simply became a thing everybody desired, so
| many "formats" appeared.
|
| Why did MD win has -- IMO -- nothing to do with how it's
| "simpler" or "more readable" -- they are largely interchangeable
| for anything that's easily represented with whitespaces in pure
| ASCII.
|
| Or does someone claim that the following is unreadable gibberish
| that they need a parser for? The best friends
| ================ ``markdown`` and ``reST`` are two
| formats that *largely* aim to achieve the same goals:
| * Be simple to read without any parser * Be quick and
| simple to type out
|
| I really, really don't see how the Markdown variant of the above
| is better in any way (note that I am not saying that reST is
| better either)? It's mostly the weirdness of history that has one
| prevail over the other, but both are good enough for their core
| goals.
| johnmaguire wrote:
| You've provided a very simple example that can be performed
| easily in both Markdown and reST.
|
| reST offers a lot of additional formatting features which are
| beneficial if you need them and cruft when you don't.
|
| I first started using Github-flavored Markdown after signing up
| for Github in 2010 (possibly earlier under another alias.) I
| used reStructuredText for Python docs a couple times. I found
| the latter to have a much higher learning curve and I haven't
| had a reason to use it since.
| necovek wrote:
| In general, either will be simple as long as your input is
| simple, and they will become complex as soon as you want
| something complex -- I am pretty sure people here bringing
| the pitchforks are really not even aware of how reST looks
| like in the first place.
|
| But looking through examples at https://docutils.sourceforge.
| io/docs/user/rst/quickref.html#..., I really see a lot of
| non-simple stuff done in an obvious way too (block quotes,
| tables, bullet and enumerated lists, sections and headings,
| separator lines...).
|
| By the time you got on the markdown train, it has already won
| out, and you've probably seen a lot more of it than of reST,
| even if MD still wasn't standardized. As a counter-point,
| having done lots of reST with Python docutils prior to 2010,
| I still mix up reST and MD -- there's nothing intuitive about
| any of their special syntax, and our perception is mostly
| tainted with our prior experience. I've also written a lot of
| ASCII-only docs prior to either of those, and most people
| used ever-so-slightly different conventions there as well
| (somebody mentioned using /this/ for italics as well).
|
| reST was standardized in the form of a Python PEP from its
| inception so you could at least rely on learning it once.
|
| Edit: My ultimate point is that you (and most everybody else,
| including me) are using MD because it's more popular, not
| because it's "better".
| johnmaguire wrote:
| I'm not arguing one is better, just that Markdown is
| simpler: it literally has less syntax. If I don't need all
| the bells and whistles of reST, Markdown is simpler to
| learn, use and likely implement.
|
| I agree that reST is probably a better fit for complex use
| cases like building a docs site. But it's overkill for
| Facebook Messenger or even forum posts, IMO.
| necovek wrote:
| I am arguing that it's not simpler either. Check out the
| latest spec on Markdown:
| https://spec.commonmark.org/0.31.2/
|
| If you want to use a mark-up language in a chat app, a
| subset of either would serve you just fine and both are
| equally simple. It sounds like you are comparing a subset
| of what-is-markdown-today (and there are still variants)
| to full reST, which I don't think is a fair comparison.
| johnmaguire wrote:
| Right, we can compare it to the reST spec: https://docuti
| ls.sourceforge.io/docs/ref/rst/restructuredtex...
|
| From a very brief look, here's some things that probably
| aren't generally necessary (and aren't included in
| Markdown): Document structure, Bibliographic fields,
| complex footnotes and citations, directives, substitution
| definitions
|
| All of these increase the number of things I have to
| escape, as well as my cognitive load when writing
| documents. And that's before we talk about reST config
| settings!
|
| You could use a subset of reST, or you could just use
| Markdown!
| lmm wrote:
| > Or does someone claim that the following is unreadable
| gibberish that they need a parser for?
|
| Unreadable? No. Frustrating to type out? Yes. Underline style
| is annoying when editing, and even if you technically don't
| have to match the length you will still feel obliged do. Double
| backtick is just awful to write, annoying out of all proportion
| to how much extra time it actually takes.
| necovek wrote:
| I guess you must really hate the double * for bold in either.
| lmm wrote:
| I do yes. I swear at some point there was markdown or some
| variant that allowed one single-character thing for italics
| and another for bold (maybe * for bold and / for italic?
| And _ for underline?). These days I've mostly just given up
| using bold.
| necovek wrote:
| You are right, there was a convention using that as well:
| I still have it in my muscle memory too (I always expect
| bold with a single asterisk). But I can't remember when
| and what that was.
|
| I still wouldn't go as far to say the MD or RST syntax is
| hard in any way (and really, asterisk which requires a
| Shift key is worse than double backticks).
| fireflash38 wrote:
| I used rST and Sphinx along with a custom built test reporter to
| generate a huge amount of test documentation for compliance. It
| really was nice to work with, especially since it is the default
| for python docstrings too.
| fridder wrote:
| Perhaps it is just how it was implemented the last time I used it
| but rST+Sphinx was so finicky and annoying that engineers just
| stopped updating the docs.
| oglop wrote:
| Ok well, that was insane.
|
| I absolutely despise working with restructured text. Markdown I
| use allllll day long and it's simple, fast, and a pleasure
| comparatively.
|
| People like this just want to make the rest of us miserable.
| dheera wrote:
| I prefer just vanilla HTML. It's easy to read and you can tack a
| stylesheet at the top to make it look actually nice and directly
| renderable in a browser without needing any parser.
| __mharrison__ wrote:
| I wrote my books for years with rST. (I also used Asciidoc, and
| one publisher wanted me to use Word.) Recently, I migrated all of
| my tooling to Markdown.
|
| It turned out that no single markup language supported all of the
| features required to make physical books, so I would need custom
| tooling regardless. The rest of the world was moving onto MD, and
| even though I'm a huge Python fan, rST is painful, and writing
| tooling with it is even worse. (I also have commit rights for
| docutils.)
|
| I don't regret my choice one bit. It has made my life much
| easier, and I can work much faster today.
| AndIHateLatex wrote:
| I never gave rST an in-depth look. This article made me.
|
| I am utterly disappointed.
|
| I want markdown for writing loose text in a way that will be
| shared with and edited by non-technical people. If something is
| not formatted such that it can be placed in-line, then we're
| entering the real of "function" abstractions, which non-technical
| people DESPISE WITH A PASSION. They won't say it, but I'm old,
| and wise enough to know it's a mistake.
|
| In other words, Markdown is just an expanded BB Code for me. And
| it does its job very well, because BB Code was insufficient.
|
| So that's the context in which I'm disappointed with rST here.
| Because it look like... A poor man's LaTeX. This stuff is way too
| complicated for Markdown's use case, and way less complex than
| the demands of a book. I don't want to take the use case of LaTeX
| and use a worse tool. Disappointment. That's all.
| rk06 wrote:
| rST is very powerful but if you have rST-illterate people on your
| team and you would like them to contribute, tough luck.
|
| Passion for most powerful tech can take you far, but not tohers
| in your team. For others, Markdown has a much lower barrier to
| entry and is easier to preview in your local editor
| daghamm wrote:
| Can't we all agree that both suck and everyone should use org?
|
| Jokes aside, org seems to have a more clear specification and is
| very easy so use. Why don't more people use it?
|
| I think Github already renders README.org as good as README.md
| and READEM.rst.
| ideasman42 wrote:
| ORG's tightly integrated into emacs & it's ecosystem. It's fine
| but I don't think there is an equivalent to Sphinx for large
| cross referenced documents, with different outputs formats &
| support for translations (different languages).
|
| Perhaps some of these things exist - I may be wrong, if they do
| I doubt the system is as mature or well supported as Sphinx's.
| port19 wrote:
| So it's more complex than markdown while being less powerfull
| than latex or org-mode? What a waste
| fermigier wrote:
| Typst has a cool syntax and is highly extensible.
|
| I wish there was a way to use it to render HTML and not just PDF.
| mrled wrote:
| I am kind of syntax agnostic and would be happy to use more
| complicated syntax in exchange for more power. (I have a lot of
| HTML inside my Markdown files, too.) However, my use of rST has
| been in Sphinx, and I want to love it because it's quite
| powerful, but it's so slow. Am I missing some configuration or
| third party package to fix this? I wrote about 15k words of
| English text in rST in Sphinx to document a project[^1], and
| Sphinx's build speed was many times more an impediment than my
| unfamiliarity with rST.
|
| [1]: https://pages.micahrl.com/progfiguration/
| gigatexal wrote:
| I'm not convinced. Markdown is cleaner imo and basically the
| standard. I see no reason to move.
| red_admiral wrote:
| The way of the world is this: ISO comes up with SGML, everyone
| gets a pat on the back, and then some guy called Tim who isn't
| even on a standards committee comes up with some bastardised
| version where you have to use angle brackets rather than generic
| customisable delimiter classes, and there's things like `<b>` for
| bold that are not even semantic. Guess which one took over the
| world?
|
| I write a lot of markdown at work, and while you can't do this in
| commonmark, most parsers will absolutely let you define custom
| block types and transform the doctree and other things. You know
| how three backticks followed by the word 'python' produces
| syntax-highlighted code almost everywhere? You bet that I can do
| `::: warning` in my documentation to make the following content
| appear in a big red box with an exclamation mark.
|
| As long as you don't put raw HTML in your source, you can even
| render to different targets like PDF. jupyter-book is a good
| example here.
| 0xbadcafebee wrote:
| My grandmother can create better docs than most programmers, but
| not because she's some technical wizard. She uses MS Word.
| Imagine, a program designed to allow humans to lay out and format
| a document quickly and easily... programmers prefer to hack up
| ascii art and forego the graphical layout and formatting tools
| developed 30 years ago. And then they complain that docs are hard
| to read/write...
| kstrauser wrote:
| Grandma's doc may not be readable in 30 years. I can look at
| basically every text file written since ASCII came along with
| standard tools. Also, since Grandma isn't a programmer, she's
| probably not collaborating on her doc with a bunch of distant
| people using a version control system with patch requests.
|
| Shiny tools are nice when it's only you and you don't need to
| keep the results forever.
| Kwpolska wrote:
| Word sucks if you want consistent formatting. It has styles,
| but they randomly glitch out and can't always handle
| everything. I want docs in HTML, not PDF, and definitely not
| DOCX. The issues some programmers have are issues with content,
| not formatting.
| HenriTEL wrote:
| To me the main deal breaker with reST is titles that must be
| underlined with punctuation characters at least as long as the
| title.
|
| That's very annoying to write, and some people even add
| overlining. We're entering the ascii art domain here and I don't
| have time for that.
___________________________________________________________________
(page generated 2024-08-01 23:01 UTC)