Re: Documentation Bug

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Friday, 19 July 2024 20:04:15 CEST Junio C Hamano wrote:
> 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?
> 

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