Convert to Markdown

[probonopd]

This is a proposal to convert the documentation to Markdown since many people are familiar with it (myself included) but are not familiar with ReStructuredText. Personally I don't have the time nor interest in learning another markup language when Markdown is the standard on GitHub. As a result, I have not been involved with the documentation lately.

https://hellosystem.github.io/docs/ uses Sphinx, recommonmark, and GitHub Actions to produce documentation from the Markdown source files in this repository: https://github.com/helloSystem/docs

Maybe we can use a similar tooling for this documentation?

NOTE: recommonmark is now deprecated. Its developers recommend using MyST for a docutils bridge going forward. See this issue for background and discussion.

[Drsheppard01]

Looks like pandoc can help you

FILES=*.rst
for f in $FILES
do
  filename="${f%.*}"
  echo "Converting $f to $filename.md"
  pandoc $f -f rst -t markdown -o $filename.md
done
### taken from this gists https://gist.github.com/zaiste/77a946bbba73f5c4d33f3106a494e6cd

[TheAssassin]

This again feels like one of these debates where someone tries to make a case for rewriting some software from scratch just because they dislike C or C++ (note: dislike, not a lack of skill or knowledge) to make small contributions.

First things first: I do not intend to convert existing documentation for no apparent reason. There is no gain in this. Adding text without modifying the structure of the code does not really require any kind of conversion. Changes close to rewrites may justify a rewrite in a different language. I'd have to evaluate options how to use more Markdown before providing realistic feedback, though.

The main issue with Markdown-based systems is, in all systems known to me (i.e., the ones I used myself), the ridiculous lack of features. No Markdown implementation is remotely on par with the features reStructuredText provides and which we rely on. The most notable of these is the anchor-based linking/referencing feature, but there are many more.

Most documentation systems either compensate that by relying on Markdown's HTML embedding feature (e.g., for info boxes and other formatting), but stuff like cross-page anchors is not as easy to replace. These are essential for good documentation, though. Instead of repeating yourself all over the place (or, worse, providing contradicting information across pages), you need to cross reference. This should also work when filenames are changed or sections are moved around (i.e., anchors should be independent from the filename, path, ..., as implemented in, e.g., Docusaurus).

Edit: the issues mentioned in the paragraph above (i.e., contradicting/duplicate information) have existed in all prior implementations of AppImage documentation.

I think it's consensual that it takes some time to get used to reStructuredText, but then again, it's really well documented and due to ReadTheDocs, it's a well established language.

[TheAssassin]

Looks like pandoc can help you

Pandoc's "conversion" is nowhere near lossless or aware of the context. You still need to manually revise and edit every single file. This is not a purely technological issue anyway.

[TheAssassin]

@probonopd since this seems to have caught your attention recently, I suggest you check your private messages on IRC.