Documentation Bug

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

These include: --[no-]single-branch --[no-]shallow-submodules --[no-]reject-shallow --[no-]remote-submodules

For example the first option will render as "single-branch]".

Source: https://github.com/git/git/blob/master/Documentation/git-clone.txt#L12-L20

Cory Kramer <corykramer@google.com> writes:

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?

On Friday, 19 July 2024 20:04:15 CEST Junio C Hamano wrote:

Hello,

This discrepancy is the another instance of asciidoc.py vs. asciidoctor. The toolchain for git uses asciidoc.py, whereas git-scm.com uses asciidoctor to process the source txt files.

Asciidoc.py does not have the concept of generalized roles, whereas asciidoctor interprets [foo]`blah` as blah with role foo in the synopsis, making in effect foo disappear in the output. Note that square brackets not directly followed by an inline markup do not define a role, which is why we do not have the issue on other parts of the documentation.

This behavior of asciidoctor is not consistant (at least in my understanding), as it behaves like asciidoc.py when the same markup is used in a definition list.

In order to get a consistant result across asciidoctor and asciidoc.py, the only hack I have found is to use the {empty} entity to split the bracket part from the inline format part. It is ugly, but unfortunately the roles are a wanted feature by technical writers because it adds semantics to the source.

The main difference of rendering introduced by my patch is that placeholders and keywords are clearly differentiated. When visualizing with the man command, the reworked pages are following the general style applied to placeholders (which are underlined) and keywords (which are bold).

I can shortly submit a small patch to fix this, by introducing the ugly {empty} entities where needed. Despite not being active lately, I still have in project to propose reworked pages for git-add, git-status, git-diff and git- commit in a short future.

Best regards,

JN