Hacker News Reader

Comment by woodruffw | Hacker News Reader

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.

View on HN

README 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.

I don’t know about these restrictions — they feel pretty excessive in a world where every engineer I know uses a terminal that can render Unicode and (at least) 256 colors. Plus, they usually have more than 72 (or 80) columns available.

In my mind, the thing that makes Markdown a nice format (in contrast to something like ReST) is that it decomposes gracefully — the formatting indicators correspond pretty closely to the conventions that email and other plain-text mediums use. The fact that it converts to HTML is just a cherry on top.

The 72 (or 80) column standard is one that is guaranteed to be accessible in virtually any circumstances.

Such as, say, just for the sake of argument, when you've been awakened at 2 am by a pager, have travelled an hour to the colo, have a multi-switch KVM wired to a cabinet of otherwise headless boxen, several of which are embedded / dedicated devices with no package installation or updates possible, several of which support only serial terminal access (possibly given an equivalent access over TCP/IP or USB), and for which the output standard is an 80x24 terminal.

This might include ILOM, IPMI, or similar protocols.

There's too much RF in the colo itself to make a phone call, let alone support wireless or mobile data.

In such a circumstance, relying on anything but 7-bit ASCII text becomes really dicey.

Unicode has over 144,000 characters presently supported with more being added constantly. Systems without ongoing OS support (such as the six year old Android tablet I'm typing this on) simply won't have the new hawtness^Wcuteness installed, and I'll be looking at some variant of ▯▯▯▯▯▯▯▯. Which in context won't be especially useful.

Documentation in MS Word, DOCX, PDF, PS, or ePub will be simmilarly opaque.

Documentation in strict HTML ... without dependencies on images, CSS, or JS, may be useful, if I can aim w3m or lynx at it. (And I can always simply view the source.)

Documentation, like lifeboats, fire-extinguishers, and aircraft emergency slides, is intended for use in the least favourable, not most favourable conditions.

Your high-powered, graphical, UTF-8 / Unicode lastest-motherlovin-codeset Retina-display monitor should have no issues in taking 72-character-wrapped text and unfolding it to longer line lengths.

That 15 year old bit of embedded kit corporate's been too fucking cheap to replace or swap out when the universe is melting down, not so much.

72-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.

No. "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.

72 character lines is very annoying in a modern world. My display is 3440px wide and can easily fit 120 chars if I split it in thirds, the rest is just wasted space. Every terminal and text editor has word wrap now, this isn't a problem anymore. Even on a 1080p screen split it half, 72chars is too few.

Just 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.

Why can’t your editor or terminal support emoji? They’re just normal plain-text standard Unicode characters like letters, numbers, and punctuation.

Ideally 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

That 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.

Nothing prevents README or README.txt from also being present.

Being 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).

Microsoft might be steaming ahead on it, but I think GitHub’s extensions to Markdown predate their acquisition by a few years.

Correct 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)

Microsoft acquired Github in 2018.

Reply on news.ycombinator.com