[ekalinin]

Summary

Fixes #110: a way to run --insert on all markdown files of a directory.

Today --insert with several local files stops at the first file without the
<!--ts--> and <!--te--> markers: it exits with 1, and the files after it are not
processed, even when they have the markers. The markers are checked after the GitHub API
request, so the request for that file is spent too.

--skip-no-markers skips such a file instead:

	Without the option	With --skip-no-markers
a.md (markers), b.md (none), c.md (markers)	TOC in a.md, error for b.md, c.md not processed, exit 1	TOC in a.md and c.md, b.md not changed, exit 0
GitHub API request for b.md	yes	no
stderr	-	b.md: Warning: no <!--ts--> or <!--te--> in the file, skipped

With find, this also covers the first request of #110, the recursive folders:

find . -name '*.md' -exec ./gh-md-toc --insert --no-backup --hide-footer --skip-no-markers {} +

Changes:

• gh-md-toc:
  • gh_toc: with the option, a local input that is an existing file is checked for
    the marker lines (the same regexes as --insert, see toc-markers) right at the
    start, before the "Table of Contents" header and the GitHub API request. Without
    them, the warning goes to stderr and the function returns, so the loop goes on to
    the next input. The option is a new last (11th) parameter.
  • A missing path, a directory and - are not skipped: they go the same way as before
    and exit with 1, so a typo in a CI command does not pass with exit 0.
  • gh_toc_app: --skip-no-markers is parsed right after --hide-footer and turns on
    --insert, as --no-backup and --hide-footer do. With --stdout it is an error
    on stderr with exit code 1, before any network call.
  • --help: a new line right after --hide-footer.
• README.md: a sentence and the find example in "Auto insert and update TOC",
  without a new heading, so the README TOC asserted in the tests does not change.
• tests/tests.bats: 6 tests on files in $BATS_TEST_TMPDIR (several files, one file
  with one marker and an invalid token, a missing file, the option alone, several files
  without the option, the error with --stdout); test_help updated.
• openspec: the add-skip-no-markers change (proposal, design, specs, tasks), not
  archived yet. It adds the toc-skip-no-markers spec and updates "Help lists the
  option" in toc-stdout: --stdout follows --skip-no-markers in --help now.

Without --skip-no-markers, the output, the exit codes and the stop at the first file
without markers do not change.

Not included: a directory walk in gh-md-toc itself (--all), adding the markers to a
file (--auto, --head of #117), skipping by default, a version bump.

Testing

• Before the change, the 4 new tests for the option and the help tests fail; the tests
  for a missing file and for several files without the option pass, they pin down the
  behavior that does not change. All 71 tests pass with the change (macOS, BSD awk
  20200816).
• Checked manually: the find example in a temporary directory with a.md,
  sub/c.md (with markers) and b.md (without), and the option with the remote
  sitemap.js README (TOC and !! ... is not a local file, exit 0).
• make lint passes.
• Not checked locally: GNU tools (CI) and OS/390.