Re: Documentation Bug

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 19, 2024, 18:04 UTC
Message-ID: <xmqqle1xjm1s.fsf@gitster.g>
In-Reply-To: <CAJ7O7F7Zxd-FUbdJh-zxr1FOrUmZQuwx4CHLbQ-ppbkSN79Z-Q@mail.gmail.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?