[ekalinin]

Summary

Fixes #141: for a GitHub API error other than a network error, bad credentials or the rate
limit, only the HTTP code was printed, and the reason that GitHub sends with it was
dropped. The #141 reporter thought it was a syntax error in the file; the file was larger
than the API limit.

Local file larger than the API limit	Output
0.8.0 (the version from #141)	empty TOC, exit 0
before	Parsing local markdown file requires access to github API Error: GitHub API request failed (HTTP 403) exit 1
after	the same two lines, then This API renders Markdown text up to 400 KB in size. The requested text is too large to render via the API. exit 1

About #141:

• The wiki page moved to https://github.com/indimail/indimail-mta/wiki/0-IndiMail-Wiki;
  its file 0-IndiMail Wiki.md is now 638679 bytes.
• The API (/markdown/raw) renders up to 409600 bytes: 409600 bytes render, 409601 bytes
  give HTTP 403 with the message above. The limit counts bytes, not characters.
• In June 2023 the file was 430599 bytes before the commit of the issue day and 441338
  bytes after it, both above today's limit. What the limit was in 2023 cannot be checked
  now.
• Workaround for such a page: its remote URL, gh-md-toc https://github.com/indimail/indimail-mta/wiki/0-IndiMail-Wiki,
  gives the TOC (160 entries), since GitHub renders the page itself. --insert needs a
  local file below the limit.

Changes:

• gh-md-toc (gh_toc_md2html): for other API errors, the message field of the JSON
  answer is taken with awk and passed in the error marker (XXApiErrorXX <code> <message>). The branches for network errors, bad credentials and the rate limit are not
  changed.
• gh-md-toc (gh_toc_check_api_error): the two lines are printed as before, and the
  message as the next line when there is one. Without a message the output is the same
  as before. With --stdout the lines go to stderr, as before.
• tests/tests.bats: a new test (#141) with a 1048576-byte file in $BATS_TEST_TMPDIR,
  well above the limit, so it does not depend on the exact number; it checks only
  too large in the message, since the text is GitHub's.
• openspec: the fix-api-error-message change (proposal, design, specs, tasks), not
  archived yet.

Not included: a TOC for files larger than the API limit (splitting a file would mean
parsing markdown, and anchors of repeated headings would differ from GitHub); a size
check before the API call (the limit would be a number in the script).

Testing

• The new test fails without the change (no third line); all 65 tests pass with it
  (macOS, BSD awk 20200816).
• The new test passes in ubuntu:24.04 with mawk.
• The [ BUG ] ... Unable to generate TOC #141 wiki file and --stdout on a 1 MiB file with markers print the three lines
  (on stdout and on stderr) with exit code 1.
• make lint passes.
• Not checked: OS/390.