search

rehypejs / rehype-raw

plugin to parse the tree again
https://unifiedjs.com
MIT License
142 stars 9 forks source link

Updated example in Readme #13

Closed CxRes closed 5 years ago

CxRes commented 5 years ago

Updated the example in Readme to clarify the processing of markdown embedded within html.

In response to discussion in rehypejs/rehype-raw#8

codecov-io commented 5 years ago

Codecov Report

Merging #13 into master will not change coverage. The diff coverage is n/a.

Impacted file tree graph

@@          Coverage Diff          @@
##           master    #13   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files           1      1           
  Lines           3      3           
=====================================
  Hits            3      3

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update c8e7ca5...8838b79. Read the comment docs.

CxRes commented 5 years ago

I have created a new PR as requested. In this change I have moved the API (which is essentially one line) before the example as this allow me to keep the caution contiguous with the usage (my conscience will not allow me otherwise: human psychology is to miss the caution anyway, the separation would make it worse).

I must say that the checks here are a borderline OCD. I had made the original fix in Github itself (after all I am just changing the Readme) and not any functional code. Now, I have had to download 70MB of dev deps on a mobile connection just to alter a few Readme lines. Extremely inconvenient!

wooorm commented 5 years ago

Thanks for working on this @CxRes. I have used your examples but changed the structure a bit, and created GH-14 as a replacement PR.

In this change I have moved the API (which is essentially one line) before the example as this allow me to keep the caution contiguous with the usage (my conscience will not allow me otherwise: human psychology is to miss the caution anyway, the separation would make it worse).

I hear you, but I believe my PR is still readable, and it has the added benefit of having the same structure as the 400 other projects under the unified collective. Sticking with the rest is important for human psychology as well.

I must say that the checks here are a borderline OCD. I had made the original fix in Github itself (after all I am just changing the Readme) and not any functional code. Now, I have had to download 70MB of dev deps on a mobile connection just to alter a few Readme lines. Extremely inconvenient!

I’m sorry about the extra stuff you needed to download. I’m not sure where you are from and how much that costs you, but that sucks. In the future, there are a) ways to cache npm modules so that you barely hit the network, or b) ask maintainers to help. They often are willing to help.

The reason for checking prose and markdown is, again, because there are hundreds of projects being maintained by only a few people, that do so in their free time. But there are many many users. And it’s important that docs are of proper quality. And: it may be a bit inconvenient now, but this project is maintained for 3 years and will be maintained for many more years to come. Finally: docs are incredibly important. That’s why we‘re discussing this: to improve docs!

Lastly, tip: don’t use OCD in that sense, it often offends people with OCD, and there are other words that explain better what you mean (extremely nitpicky, maybe?). There’s no need to offend people in open source, but there is need to be inclusive!

I do appreciate your work, I used it and gave you credit, and I hope you agree that GH-14 is a good addition.