4 ms·
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
by fefe23 2y ago
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 2y agoHTML 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 2y agoWhat 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 2y agoI 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 2y agoAs 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.