Comments (3)
While we are at it, we might also want to check out Jupyter Book which can be used to generate books/documentation websites that embed executable code:
https://www.heise.de/news/Projekt-Ausfuehrbares-Buch-Jupyter-Book-erstellt-Tech-Buecher-mit-Markdown-4870752.html
from docs.appimage.org.
So your response to "I would have to learn something new" is to suggest "everyone else but me has to learn something entirely new"? This MyST stuff is a lot more cumbersome than reST, syntax wise, as it hacks additional markup into existing Markdown structures, making it a lot harder to understand and read. reST provides proper extension points by default (like blocks etc.), and is designed to be augmented with additional features.
Just look at ref
s. That's not easier than reST's ref
s, it's actually more complicated than reST:
# reST
:ref:`My displayed text <my-ref>`
# MyST
{ref}`My displayed text <my-ref>`
Their blocks are hacked into Markdown's code syntax:
# reST
.. contents::
:local:
:depth: 1
...
# MyST
```{contents} Contents
:local:
:depth: 1
...
I can understand that reST might look awkward at first glance, but it's easy to understand, provides a very consistent approach syntax wise (most elements are noted similarly, with different names only), is not just months but decades old, well tested and used in the best tech docs in the world. Many people know the syntax, it's not as unpopular as most people think.
MyST indeed looks, however, like someone tries to merge reST and Markdown. However, I'm clearly not a fan of the result. It's not like it makes anything easier to add additional parsers; we've had tried that, and the result was a mix of languages, with the reST part being written using the features it provides and providing a better overall result, the rest being mostly ported from the wiki, which had no consistent style, lacked proper cross references and structure (hierarchy), and overwhelming the user with information they didn't need immediately.
Have you ever tried to write reST? It's not hard at all. There's editors like ReText (request for AppImage here) which make writing Sphinx docs very easy.
P.S.: It's not a matter of preference. I also write LaTeX not because it's necessarily easy but because the result is significantly better than what any "simple alternative" could provide (well, there's nothing really comparable). I don't claim reST was the best markup language, but it's easy to learn and use IMO.
from docs.appimage.org.
Have you ever tried to write reST?
Yes. For me it is cryptic, counter-intuitive and not fun. Unlike Markdown which I find straightforward, easy, and fun.
It's not a matter of preference.
Let's say it's "compatibility to how my brain works". ;-) Plus brain muscles that have been trained to do Markdown.
from docs.appimage.org.
Related Issues (20)
- Add section on how to make AppImages of Qt apps look native on Gtk
- Dunno - AppImage have a quick tutorial ?
- External AppStream Generator is not working HOT 9
- Would you be open to adding an examples section ? HOT 2
- Missing Desktop entries in docs
- Better describe registering and desktop integration process HOT 1
- CI fails on linkcheck HOT 5
- Add a chapter about the environment for 'appimaged' applications HOT 2
- Arch FUSE install instructions
- Documentation needs to be updated for Ubuntu 22.04 / Fuse section HOT 7
- Missing link to AppRun file in manual packaging doc HOT 1
- Consolidate info about hard-coded paths HOT 1
- Confusion between https://www.appimagehub.com and https://appimage.github.io/
- Remove appimage-testsuite? HOT 1
- https://docs.appimage.org/ is offline. HOT 3
- SSL Certificate expired HOT 1
- Documentation about supporting update channels
- linuxdeploy is also available on ARM HOT 2
- No instructions for Fedora Atomic Desktop
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docs.appimage.org.