Unfortunately, it's much less known and there is much less software support for it.
Too bad because I found it superior to markdown for my uses.
For a finer control of the rendering, HTML is still available.
Every markdown-like language has some underlining and bullet points. I can handle that. Once we get into using graphviz / some other tool for drawing charts and graphs I simply lose it.
It is in the end much easier to knock up something in PowerPoint / Visio / paint tool than be clever with graphviz.
The only arguments against this are
1. Maintenance - and yes it’s a good argument. Changing the name of one box should be easy - but it is with some paint tool too.
2. Graphviz etc are much more “programmable”. Slapping together 6 boxes for your network diagram is easy. 150 is what graphviz is for.
The problem is that you stopped using markdown the minute you went “oh, 150 boxes with edges between them.” At that point you have to use “some other tool”.
Maybe that tool is taipy, or graphviz or he’ll LaTeX is great for this - but you need to master the tool then you get great results.
So things like this should be
“If you are already fluent with graph production in LaTeX, use this tool That links latex to markdown”
Otherwise spending a large chunk of your undergraduate thesis learning how to use the tool might not work so good.
Summary:
Just use dead simple plotly graphs in your sphinx docs. Something like “total number of words bar chart”.
Then it’s there and you can expand it as much as you can before you hit the complexity limit that is just simpler to grab a visual drawing tools and store a binary.
Markdown was originally a loose formalization of how people already wrote text only emails. It was how _people_ wrote, not how to optimize for the computer.
Not sure, but isn't using _ instead of the more intuitive /italics/ a big mistake on the syntax side?
... in fact I just tried it and underscore apparently works in WhatsApp, TIL.
OTOH /italics/ reads to me as a regular expression, which ... is apparently not what you meant.
(as ever, "intuitive" varies wildly between people, and the trick is to pick the option that's intuitive for the highest possible percentage of your expected user base)
Also, no one has implemented a really good experience for writing HTML, not for webpages, but simple documents. It could be really easy to write HTML mostly by hand if an editor could dynamically convert Markdown-like syntax into HTML tags on the fly. That way, the resulting document is definitely HTML, and not up to the interpretation of some flavor of Markdown.
Such an editor can also do things to try and soft-preview what emphasis the HTML represents. Here's an example of an experiment I worked on in this direction a long time ago: https://codepen.io/Ravenstine/pen/gyMVNx
^^ Never mind the pompous attitude I had when I wrote the placeholder text for it.
Eventually, I settled on a workflow with Python as a scripting language, but I avoid any UI stuff. If I need good charting, I just build Tableau or Power BI displays to consume the Python outputs that I've already pushed to a SQL database for analysis anyway as the data I'm dealing with is generally fairly large (i.e. gigabytes were generated while I wrote this reply).
I certainly get the appeal of doing everything in one language and there are some efficiency gains for sure, but sometimes (especially dealing with data science folks), I feel like they'd be much better off if they could learn common unix command line tools and SQL and add that to their arsenal. They all say they know SQL, but can't do much outside of "Select * from table;" and then spend a ton of time working around local Python memory limitations, which sometimes just means using a tiny dataset that they can actually fit into memory. I got a little off topic there, but wonder if anyone else has experienced something similar?
My current go-to python GUI solution is to use the Eel library. It renders GUIs in a web-browser like window with HTMl/CSS/JS.It lets you expose your python functions to JavaScript, so data can be easily transferred back and forth between the python and the JavaScript. And since it's just web-dev, it's pretty easy to make things look and feel good enough. Any other web-dev libraries like bootstrap and jquery can be used. It works pretty well for writing GUIs that put data analysis tools in front of my colleagues.
To show-off these "hyper-markdown" capabilities and avoid compatibility issues with "md" files, we could name the new file format with an "html" extension (HyperText Markdown Language).
Makes me think of Voila [0], in my opinion one of the most powerful solutions to build interactive app with python. It requires Jupyter notebook, IPywidgets and e.g. BQPlot.
Then, the part where you do "Gui(page=my_page).run()" just becomes a build script that happens in the background, rather than requiring the coder to have a bunch of isolated markdown snippets throughout their code
Was hoping this was the analog for Python, but it seems the content is still strings.
i.e. parse markdown with code vs parse code with special strings
Not all computing platforms allow users to do whatever. Eventually these disparate doc platforms will need to get merged, updated. What happens when Restrictive Platform X needs to update your Special Format? They fork, and they use a doc markup that's workable on a generic platform. Welcome to Double Work Town.
Anyway, it's pretty important to select a markup whose core specification does all the things you need on a generic computing platform[1]. Many different paths branch from that one singular fact, but I'll stand by that singular fact. Seen too many decades flushed down the toilet of churning doc/markup formats.
[1] That doesn't require frickin admin access for trivial writing tasks, like changing DTDs.
<cough>Arbortext</cough>
1. Layout, format [aka style], and interactivity, is both hard and necessary
2. Interfaces are subtly complex
Number 2 is the reason that "simple" formatting markup, like Markdown, will never be good enough to make a great interface. You can make a poor interface with Markdown, and that poor interface is good enough for very simple use cases. But people quickly get annoyed by simple use cases. They create friction, both for the designer and the user. More useful functionality is desired, and you need something more complex to enable that.
I've written a lot of tech docs. Markdown is one of the worst methods I've found to write them. Not because its formatting isn't intuitive, easy to remember, and easy to use. But because the documents it creates are not conducive to the purpose of the document: making it easy to read and remember information.
As for more general interfaces, the easiest way to understand why you need more elaborate methods, is HTML. When HTML was created by Tim-Berners Lee ~1990, he intended for format and layout to be independent and configurable. However, for years it lacked both formatting and layout options, and lots of people complained. It took six years for CSS to eventually become a standard, and before that, lots of hacks and incompatibility (and it turned out, more of them afterwards). The entire time people were complaining about how any document editor could easily format and layout exactly what the author wanted, but web browsers persisted in being difficult and inferior. Tables were only added in HTML 2.0, five years after the Web's birth.
You can still get by with not-very-good markdown, for not-very-good interfaces. But you will never have a Great interface without the ability to control layout, format, and interactivity, in subtly complex ways.
There is no easy way for a human to do that with text. But there is an invention that enabled users to create complex and rich layout, formatting, and interactivity: the WYSIWYG interface. With this tool, the human no longer needs to remember control characters, markup syntax, or formatting codes. The user no longer needs to spend endless time typing in code, displaying the result, being unsatisfied, and tweaking the code again, trying desperately to just get the screen to show them what they know they want. A WYSIWYG editor enables a human to completely discard any knowledge of how to format or layout content, and instead simply move things around on their screen with a mouse, completely eliminating complexity for the human, and enabling the creation of better content.
I think the reason modern software abandoned WYSIWYG, is that modern software isn't created for users. Most modern software is open-source (or close), and as such, it's created by developers, for developers. Developers don't want to spend time engineering a WYSIWYG, because they have no need for a good interface, and they don't care about wasting their time writing code. To them, writing code is the whole point, regardless of how long it takes, or what the outcome is. That's why Markdown was invented, and why people persist in trying to force Markdown to make something better, without realizing that that's impossible. They want to to build a castle, but they don't want to use anything other than the twigs and rocks lying about their feet.
Where does this verge into the realm of a Jupyter notebook? And why would this be better than such a notebook? The usecase for this markdown and rendering is... vs. a notebook? Genuinely curious about this, because sure you can make code do stuff, but is it worth it?
