Re: Documentation Bug

[Junio C Hamano <gitster@pobox.com>]

Cory Kramer <corykramer@google.com> writes:

> In the docs for git-clone the brackets become mismatched for any
> options that have a [no-] counterpart.
> https://git-scm.com/docs/git-clone

Interesting.  The preformatted pages that were directly generated
from the sources at https://git.github.io/htmldocs/git-clone.html
has no such breakage.

Cory, thanks for reporting.

I think 76880f05 (doc: git-clone: apply new documentation formatting
guidelines, 2024-03-29) is where the alleged "breakage" came from.

Comparing it with pages that weren't updated by the topic that ends
at 58dd7e4b (Merge branch 'ja/doc-markup-updates', 2024-04-09), like

    https://git-scm.com/docs/git-clone
    https://git-scm.com/docs/git-add

I notice that the latter is rendered with "--[no-]ignore-removal"
correctly shown.

Two possible action items are

 - Compare the preformatted pages at https://git.github.io/htmldocs/
   between git-clone and git-add and re-evaluate if the earlier
   ja/doc-markup-updates topic did to the SYNOPSIS is really what we
   want (the difference is harder to assess by looking at the pages
   at https://git-scm.com/docs/).

 - Update the machinery that formats our documentation sources and
   renders at https://git-scm.com/docs/ to grok the mark-up used by
   ja/doc-markup-updates topic (currently in use for clone, init,
   and nothing else).

Do anybody remember what transmongering produces the copy shown at
git-scm.com from the source?  Is it computed from the preformatted
pages, or from the source?