mkj
Use github compatible markdown for README
The current README file is not formatted for GitHub. Change the formatting to markdown with the necessary changes to formatting.
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.
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.
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
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
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 👍.
One can indeed hyperlink other documents from the welcome/landing page on GitHub. The other documents could be in a textual format even.
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.
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.