YJL

Last month, I had a short discussion with someone about a few funky naming scenarios of README that I dislike. After the chat, an idea has been brewing in me, hence this post title. Hopefully, this would become a series of issues I’ve seen in many README.

For this very first part, it’s lists mistakenly wrapped in block quotes, which happens quite often and many people make such mistake. The following is a GIF of a README, consisting of the rendered results on PyPI and GitHub, plus the relevant reStructuredText source code.

The bullet lists are wrapped inside block quotes, which are by mistakes, or simply the lack of the knowledge of reStructuredText and failures to check the rendered results on those websites.

It’s not only happening on README, even on PEPs (Python Enhancement Proposals) with final status as seen in the GIF below.

When you are not meant to quote lists, you don’t nest lists inside block quotes. All of the cases above are errors by the writers. They are simple to fix, here are a few thoughts:

• Learn the markup language

  A text block that is indented relative to the preceding text, without preceding markup indicating it to be a literal block or other content, is a block quote.

  —reStructuredText Markup Specification

• Check the rendered results by markup processor locally

  For reStructuredText, you can use rst2html.py to render a HTML to preview in web browser.

• Check the rendered results on websites

  For README.md on GitHub, get a GRIP.

Somehow, I have a feeling that these people are not only unfamiliar with block quote styles on those websites, but also the HTML, therefore unable to spot the errors.

This type of mistake probably is only possible in reStructuredText, definitely not in Markdown since it requires > to mark a quote, but Markdown has its own share of inexperienced users, stay tuned.