4 ms·

>Embedded visual aids like diagrams and demos. >The build status identifies specific project aspects that are incomplete and/or causing instability. >One or m

by daptaq 9y ago

>Embedded visual aids like diagrams and demos. >The build status identifies specific project aspects that are incomplete and/or causing instability. >One or more badges showing code coverage or other quality metrics. I really have to disagree with points like these. I always hate cloning a project and then opening the README to find a totally unreadable mess of Markdown links and images or worse still - literal HTML. As an example, look at uBlock's README.md[0], which even though uBlock is a fantastic project in it's own right, has a horribly unreadable README. If you're already adding a README file within your code repositoy, you should assume that people will read it locally, without fancy HTML rendering. The whole point behind markup was to have a syntax which could be easily parsed by computers and humans alike (it was inspired by the plaintext email formatting style after all!). Graphics and badges should be put on a website, in this case for example GitHub's github.io service. Specifics should be placed in a man page or something comparable. Links should either be autolinks[1] or reference links[2], to keep the document clean and structured. I'm sure others could come up with more and better recommendations on how to use "normal" markdown to still create a decent README's for GitHub. Maybe we don't even need Markdown and we can just use plain utf-8[3]... [0]: https://raw.githubusercontent.com/gorhill/uBlock/master/README.md https://raw.githubusercontent.com/gorhill/uBlock/master/READ... [1]: http://spec.commonmark.org/0.28/#example-565 http://spec.commonmark.org/0.28/#example-565 [2]: http://spec.commonmark.org/0.28/#reference-link http://spec.commonmark.org/0.28/#reference-link [3]: I recently downloaded a dwm statusbar manager called "dstat" (from https://www.umaxx.net/ https://www.umaxx.net/) and it's README was a really nice surprise: https://sub.god.jp/f/JmiFHE9S.txt https://sub.god.jp/f/JmiFHE9S.txt (extracted and uploaded, since there's no public version)

Cyphase 9y ago
As a complete aside, some people (in an IRC channel) and I just spent 20+ minutes trying to figure out why https://sub.god.jp/f/JmiFHE9S.txt https://sub.god.jp/f/JmiFHE9S.txt was displaying in a non-default font in Firefox. Turns out it was being treated as encoded as Shift JIS, because the encoding wasn't explicitly specified in the headers and the TLD is .jp .[1] [1] https://dxr.mozilla.org/mozilla-central/source/dom/encoding/domainsfallbacks.properties#72 https://dxr.mozilla.org/mozilla-central/source/dom/encoding/...
ansible 9y ago
I've put this into a bash function to render markdown files in the terminal window function markdown() { pandoc -s -f markdown -t html "${1}" | sed 's/^<pre class/<p><\/p><pre class/' | lynx -stdin } ... which doesn't really address your main complaint, but can help in cases where you really don't want to exit your command-line. Requires the pandoc package, which isn't installed by default in Ubuntu.
- Cyphase 9y ago
  > Requires the pandoc package, which isn't installed by default in Ubuntu. Neither is lynx, since you mentioned it. Neat trick :).
michaelmior 9y ago
While the badges can get to be overkill (like in uBlock's case), I think having a small number with useful information (dependency status, code coverage, etc.) is helpful when quickly assesing a project.

by daptaq 9y ago

Cyphase 9y ago

As a complete aside, some people (in an IRC channel) and I just spent 20+ minutes trying to figure out why https://sub.god.jp/f/JmiFHE9S.txt https://sub.god.jp/f/JmiFHE9S.txt was displaying in a non-default font in Firefox. Turns out it was being treated as encoded as Shift JIS, because the encoding wasn't explicitly specified in the headers and the TLD is .jp .[1] [1] https://dxr.mozilla.org/mozilla-central/source/dom/encoding/domainsfallbacks.properties#72 https://dxr.mozilla.org/mozilla-central/source/dom/encoding/...

ansible 9y ago

I've put this into a bash function to render markdown files in the terminal window function markdown() { pandoc -s -f markdown -t html "${1}" | sed 's/^<pre class/<p><\/p><pre class/' | lynx -stdin } ... which doesn't really address your main complaint, but can help in cases where you really don't want to exit your command-line. Requires the pandoc package, which isn't installed by default in Ubuntu.

Cyphase 9y ago
> Requires the pandoc package, which isn't installed by default in Ubuntu. Neither is lynx, since you mentioned it. Neat trick :).

michaelmior 9y ago

While the badges can get to be overkill (like in uBlock's case), I think having a small number with useful information (dependency status, code coverage, etc.) is helpful when quickly assesing a project.