* Re: Documentation Bug
2024-07-19 18:04 ` Junio C Hamano
@ 2024-07-20 17:14 ` Jean-Noël AVILA
0 siblings, 0 replies; 3+ messages in thread
From: Jean-Noël AVILA @ 2024-07-20 17:14 UTC (permalink / raw)
To: Cory Kramer, Junio C Hamano; +Cc: git
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
^ permalink raw reply [flat|nested] 3+ messages in thread