fixup! [#147] Improve readme

README.md

@@ -27,8 +27,14 @@ and it will let you know when it finds a broken link.
 
 Comparing to alternative solutions, this tool tries to achieve the following points:
 
-* Quickness - local references are verified instantly even for moderately-sized repositories.
-* Easy setup - no extra actions required, just run the tool in the repository root.
+* Quickness
+  * References are verified in parallel.
+  * References with the same target URI are only verified once.
+  * It first attempts to verify external links with a `HEAD` request; only when that fails does it try a `GET` request.
+* Resilience
+  * When you have many links to the same domain, the service is likely to start replying with "429 Too Many Requests".
+    When this happens, `xrefcheck` will wait the requested amount of seconds before retrying.
+* Easy setup - no extra actions required, just run `xrefcheck` in the repository root.
 * Conservative verifier allows using this tool in CI, no false positives (e.g. on sites which require authentication) should be reported.
 
 ## A comparison with other solutions [↑](#xrefcheck)
@@ -40,7 +46,7 @@ Comparing to alternative solutions, this tool tries to achieve the following poi
   At the moment of writing, it scans only external references and checking anchors is not possible.
 * [remark-validate-links](https://github.com/remarkjs/remark-validate-links) and [remark-lint-no-dead-urls](https://github.com/davidtheclark/remark-lint-no-dead-urls) - highly configurable JavaScript solution for checking local and external links respectively.
   It is able to check multiple repositores at once if they are gathered in one folder.
-  Being written in JavaScript, it is fairly slow on large repositories.
+  Doesn't handle "429 Too Many Requests", so false positives are likely when you have many links to the same domain.
 * [markdown-link-check](https://github.com/tcort/markdown-link-check) - another checker written in JavaScript, scans one specific file at a time.
   Supports `mailto:` link resolution.
 * [url-checker](https://github.com/paramt/url-checker) - GitHub Action which checks external links in specified files.