[ekalinin]

Summary

Fixes #62: a mode like --insert that outputs the entire new contents of the file to
stdout instead of overwriting it.

--stdout prints the whole document with the new TOC between <!--ts--> and
<!--te-->: the same content that --insert writes into the file. The file is not
changed, no .orig.<date> or .toc.<date> file is created, and nothing else goes to
stdout (no Table of Contents header, no status lines).

./gh-md-toc --stdout README.md > README.new.md
curl -s https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/README.md | ./gh-md-toc --stdout - > README.md

• gh-md-toc:
  • gh_toc_stdout (new): uses the same TOC block and the same sed expressions as
    --insert, without -i, so the output is byte-for-byte what --insert writes,
    a last line without a newline included. gh_toc and the --insert code are not
    changed.
  • gh_toc_app: --stdout is parsed right after --hide-footer and before
    --skip-header. It takes one local file or - for STDIN. --hide-footer,
    --skip-header, --indent, --depth, --numbered and --bullet work with it as
    with --insert; --insert and --no-backup next to it do not change the file.
  • Errors in this mode go to stderr with exit code 1 and an empty stdout, so with
    > out.md the error text does not end up in the file: no input, several inputs or
    a URL, a document without the markers (both before any network call), and the
    GitHub API errors. The other modes keep printing errors to stdout.
  • gh_toc_mktemp (new): the temporary file code of the - branch, shared with
    --stdout. On OS/390 the name gets $$.$RANDOM, because --stdout - makes two
    files in the same second. The temporary files of --stdout are removed on exit,
    errors included.
  • STDIN is now read with cat, for - too. The old while read -r loop removed
    leading and trailing whitespace and dropped a last line without a newline, so an
    indented code line like # comment became a TOC entry, and
    printf '# A\n\n## B' | gh-md-toc - printed nothing.
  • --help: a new line right after --hide-footer.
• README.md: a paragraph with examples in "Auto insert and update TOC", without a new
  heading, so the README TOC asserted in the tests does not change.
• tests/tests.bats: 15 new tests on a new fixture test_stdout.md (it has no newline
  at the end on purpose, no test writes into it); test_help updated.
• openspec: the add-toc-stdout change (proposal, design, specs, tasks), not archived
  yet.

Not included: a remote URL as input of --stdout (a GitHub page is loaded as rendered
HTML, there is no Markdown source; STDIN covers it), several inputs in one run, an
--output <FILE> option, printing the errors of the other modes to stderr.

Testing

• The new tests and the updated help tests fail without the change; all 49 tests pass
  with it (macOS, BSD sed).
• Checked manually: --numbered outline and --depth 1 with --stdout, and the
  remote README piped into --stdout - (exit code 0, the lines outside the markers are
  the same as in the input).
• make lint passes.