[ekalinin]

Summary

Fixes #153: an option to keep the inline code of the headings in backticks in the TOC.

Today the <code> tags of a heading are removed (since the fix of #13), so the TOC entry
has the code without backticks: # `Headline` gives * [Headline](#headline). A
linter that compares the entries with the headings fails on that, and the code is read
as markdown in the TOC: ## `**kwargs**` gives * [**kwargs**](#kwargs), rendered
as a bold "kwargs".

--keep-code writes every inline code element as a code span with the same content:

heading              without the option         with --keep-code
-------------------  -------------------------  -------------------------
`Headline`           [Headline](#headline)      [`Headline`](#headline)
`a<b>&c`             [a&lt;b&gt;&amp;c](#abc)   [`a<b>&c`](#abc)
`` a`b ``            [a`b](#ab)                 [``a`b``](#ab)
`**kwargs**`         [**kwargs**](#kwargs)      [`**kwargs**`](#kwargs)

• <, > and & inside the code are decoded: in a code span they are shown
  as is. The entities outside the code stay as before.
• The code is enclosed in one backtick more than the longest run of backticks inside it.
• One space is added on each side when the code starts or ends with a space or a
  backtick and is not only spaces, so the spaces at the edges are kept (CommonMark
  strips one from each side).

The issue proposes the name --no-code-tag-removal. --keep-code is used instead: it
says what the user gets, the option also decodes the entities and picks the backticks,
and the longer name does not fit the option column of --help.

Changes:

• gh-md-toc:
  • gh_toc_grab: a new parameter $7. With it, the sed step that removes <code> is
    skipped, and a loop in common_awk_script (shared by the default and OS/390
    branches) builds the code spans. The tags are removed only from the text around the
    code, otherwise the decoded a<b>&c would lose <b>. Without the option, the loop
    does not run and the sed step runs as before.
  • gh_toc_app: --keep-code is parsed right after --bullet, before -, so it works
    with stdin. It is passed to gh_toc (12th parameter), gh_toc_stdout (8th) and to
    the stdin call of gh_toc_grab.
  • --help: a new line right after --bullet.
• README.md: a sentence and an example after the --bullet example, without a new
  heading, so the README TOC asserted in the tests does not change.
• tests/tests.bats: a new fixture tests/test directory/test_keepcode.md (12
  headings, 13 code spans), 5 tests (a local file with and without the option, stdin
  with --bullet -, a remote URL pinned to a commit, --stdout), test_help updated.
• openspec: the add-keep-code change (proposal, design, specs, tasks), not archived
  yet. It adds the toc-keep-code spec and updates "Plain text of the heading" in
  toc-heading-markup to point to it.

Without --keep-code, the output does not change.

Not included: keeping the backticks by default, other markup back to markdown
(*em*, **strong**), headings missing from the TOC when GitHub puts a line break after
the heading tag (#201), a version bump.

Testing

• Before the change, the 4 new tests with the option and the help tests fail; the test
  without the option passes, it pins down the output that does not change. All 76 tests
  pass with the change (macOS, BSD awk 20200816).
• Checked manually:
  • the TOC entries of the fixture made with --keep-code, rendered by the markdown
    API, have the same <code> content as the headings, for all 13 code spans;
  • --keep-code --insert gives the same file as the output of --keep-code --stdout;
  • several inputs: the entries have the backticks and the link prefix;
  • the fixture with and without the option gives the same output with mawk 1.3.4 (the
    awk of the Debian Docker image) and GNU awk 5.2.1 as on macOS.
• make lint passes.