Use github compatible markdown for README about dropbear HOT 8 OPEN

The idea to "separate" one big file to two smaller halves without intersection means that the overall maintenance burden should be the same.

Certain people mean "CommonMark" when they refer to standardized markdown I think:
https://en.wikipedia.org/wiki/Markdown#Standardization

from dropbear.

Might be fine, but just to widen the view:

Remember GitHub is not the only/main target for this README, but it is included in Dropbear sources downloads from the official website/server: https://matt.ucc.asn.au/dropbear/releases/

When downloading such an archive, Markdown is probably not the format wanted for an universally readable README, especially not a possibly non-standard GitHub-flavoured Markdown format with external resources embedded.

from dropbear.

There is no such thing as "standard" markdown - there exist multiple dialects. Certain subsets of features of them do intersect, however. And if you stick to adding extra whitespace and stay away from advanced features, it should look the same on all output.

I can read downloaded markdown files offline just fine, but if this bothers you, the readme could be separate to a shiny part that appears on the GitHub main page and a more dull (but still markdown) one that contains instructions for installation, usage and whatnot.

from dropbear.

There is no such thing as "standard" markdown

I meant this as of OP sentence:

The current README file is not formatted for GitHub.

GitHub might be not the no. 1 priority, in which case a more generic Markdown syntax way be preferred. E.g. in the open PR

stick to adding extra whitespace

is not done. But otherwise it should be fine.

Generally as a "standard" Markdown, I mean basically this syntax, which should work as intended with every dialect interpreter:

• https://daringfireball.net/projects/markdown/syntax
• https://www.markdownguide.org/basic-syntax/

the readme could be separate to a shiny part

Which means two files to maintain.

Don't understand me wrong, I don't want to argue against it and have no vote here anyway. Just want to tell OP why those "necessary changes to formatting" might not be seen as necessary by the maintainer. E.g. the same is true for a "shiny" Dropbear logo, I was wondering about 🙂: #196

from dropbear.

The idea to "separate" one big file to two smaller halves without intersection means that the overall maintenance burden should be the same.

Ah, but since GitHub only shows one readme, whatever you add with the second file, will be missing?

Certain people mean "CommonMark"

Ah right, that is the most complete basic syntax description 👍.

from dropbear.

One can indeed hyperlink other documents from the welcome/landing page on GitHub. The other documents could be in a textual format even.

from dropbear.

But those hyperlinked documents (unless images and such) cannot be expanded, is it? I know there are Markdown extensions which allow loading of external files, but I'm not aware of GitHub dialect supporting this.

from dropbear.

I don't know of a dialect that supported inlining either.

Some support various HTML tags within the Markdown code, but I consider that cheating.

from dropbear.