5 ms·
I've noticed a lot of projects in the past few years put a lot of stuff like this in their READMEs, with the (presumable) end goal of making their repository re
by woodruffw 5y ago
I've noticed a lot of projects in the past few years put a lot of stuff like this in their READMEs, with the (presumable) end goal of making their repository really "pop" on GitHub. That's perfectly fine! But sometimes it goes so far as to actively impede reading the README in a text editor, since it's now full of tables and Markdown abuse aimed at making it render correctly on GitHub. It also has a tendency to break other sites (think package management indices) that tend to consume READMEs, as they're now being fed all kinds of weird GitHub-specific Markdown. That leads to an overall worse user experience, e.g. when I'm selecting a package from PyPI or crates.io.
Given that projects are now using their READMEs as de-facto `index.html` pages, we really ought to just have an `INDEX.md` or similar convention for presenting all the cute stuff.
- mmahemoff 5y agoIdeally those tools would render a file called README.md as readable HTML. For example, w3m renders this project's README cleanly - https://ibb.co/WPDDL0d https://ibb.co/WPDDL0d
- woodruffw 5y agoThat would be ideal, yeah. But I don’t begrudge them for failing to do so: GitHub-flavored Markdown is a significantly more complicated beast than “common” Markdown, which is itself somewhat fragmented.
- gopiandcode 5y agoBeing slightly cynical here, I'd presume that's not a bug, but rather the intended outcome, and this phenomenon with markdown is just a canary for M$'s impeding extinguish phase (after having embraced and extended git forges like github).
- woodruffw 5y agoMicrosoft might be steaming ahead on it, but I think GitHub’s extensions to Markdown predate their acquisition by a few years.
- WalterGR 5y agoCorrect on the latter. GFM (Github-flavored Markdown) - "In 2017, GitHub released a formal specification of their GitHub Flavored Markdown (GFM) that is based on CommonMark." (https://en.wikipedia.org/wiki/Markdown https://en.wikipedia.org/wiki/Markdown) Microsoft acquired Github in 2018.
- throwawayboise 5y agoREADME or INSTALL (no extension) files should be plain text, folded at 72 columns. You should assume the people actually trying to build your software are working in a shell in a terminal and using less(1) or maybe vi or some other text editor to read the README file. Even markdown is too much, though it's tolerable if named README.md so I at least can know to run it through a filter. Including icons, emojis, animations in such a file is right out.
- erezsh 5y agoJust because you code like it's the 90s doesn't mean everyone else has to. But I'm pretty sure even in the 90s everyone had word-wrap, so the 72 columns thingy never really made sense for texts that don't have indentation.
- franga2000 5y agoNo. "The arbitrary limitations that I have voluntarily put on myself and my system should be adhered to by everyone in the world, despite great detriment to anyone else who uses at rhis point decades old technology to its full capabilities." Are you hearing yourself? There are so many other minorities out there that deserve being catered to a billion times more than you. People with real issues that they can't just turn off with a "startx" command.
- kens 5y ago72-column lines are important because the IBM 709 vacuum tube computer(1958) could only read 72 columns from an 80-column punch card. (Due to its 36-bit word size.) Thus, FORTRAN only used 72 columns and this became a standard. 60 years later, this limitation is still affecting people.
- vdjao 5y agoHa thanks for the laugh. Today I was in term and full screened it in my curved widescreen monitor to review some lengthy iptable entries and logs. Couldn’t imagine only having 80 columns anymore.
- chrisseaton 5y ago
- bombcar 5y agoNothing prevents README or README.txt from also being present.