{"thread":{"id":"61811","subject":"Documentation Bug","startedAt":"2024-07-19T16:09:35Z","lastAt":"2024-07-20T17:14:31Z","messageCount":3,"participants":["Cory Kramer","Junio C Hamano","Jean-Noël AVILA"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"498970","messageId":"CAJ7O7F7Zxd-FUbdJh-zxr1FOrUmZQuwx4CHLbQ-ppbkSN79Z-Q@mail.gmail.com","threadId":"61811","inReplyTo":null,"subject":"Documentation Bug","fromName":"Cory Kramer","fromEmail":"corykramer@google.com","sentAt":"2024-07-19T16:09:22Z","receivedAt":"2024-07-19T16:09:35Z","isPatch":false,"sender":{"key":"corykramer@google.com","avatar":null},"body":"In the docs for git-clone the brackets become mismatched for any\noptions that have a [no-] counterpart.\nhttps://git-scm.com/docs/git-clone\n\nThese include:\n--[no-]single-branch\n--[no-]shallow-submodules\n--[no-]reject-shallow\n--[no-]remote-submodules\n\nFor example the first option will render as \"single-branch]\".\n\nSource: https://github.com/git/git/blob/master/Documentation/git-clone.txt#L12-L20\n"},{"id":"498973","messageId":"xmqqle1xjm1s.fsf@gitster.g","threadId":"61811","inReplyTo":"CAJ7O7F7Zxd-FUbdJh-zxr1FOrUmZQuwx4CHLbQ-ppbkSN79Z-Q@mail.gmail.com","subject":"Re: Documentation Bug","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-19T18:04:15Z","receivedAt":"2024-07-19T18:04:23Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Cory Kramer <corykramer@google.com> writes:\n\n> In the docs for git-clone the brackets become mismatched for any\n> options that have a [no-] counterpart.\n> https://git-scm.com/docs/git-clone\n\nInteresting.  The preformatted pages that were directly generated\nfrom the sources at https://git.github.io/htmldocs/git-clone.html\nhas no such breakage.\n\nCory, thanks for reporting.\n\nI think 76880f05 (doc: git-clone: apply new documentation formatting\nguidelines, 2024-03-29) is where the alleged \"breakage\" came from.\n\nComparing it with pages that weren't updated by the topic that ends\nat 58dd7e4b (Merge branch 'ja/doc-markup-updates', 2024-04-09), like\n\n    https://git-scm.com/docs/git-clone\n    https://git-scm.com/docs/git-add\n\nI notice that the latter is rendered with \"--[no-]ignore-removal\"\ncorrectly shown.\n\nTwo possible action items are\n\n - Compare the preformatted pages at https://git.github.io/htmldocs/\n   between git-clone and git-add and re-evaluate if the earlier\n   ja/doc-markup-updates topic did to the SYNOPSIS is really what we\n   want (the difference is harder to assess by looking at the pages\n   at https://git-scm.com/docs/).\n\n - Update the machinery that formats our documentation sources and\n   renders at https://git-scm.com/docs/ to grok the mark-up used by\n   ja/doc-markup-updates topic (currently in use for clone, init,\n   and nothing else).\n\nDo anybody remember what transmongering produces the copy shown at\ngit-scm.com from the source?  Is it computed from the preformatted\npages, or from the source?\n"},{"id":"499007","messageId":"22362805.EfDdHjke4D@cayenne","threadId":"61811","inReplyTo":"xmqqle1xjm1s.fsf@gitster.g","subject":"Re: Documentation Bug","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-07-20T17:14:07Z","receivedAt":"2024-07-20T17:14:31Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Friday, 19 July 2024 20:04:15 CEST Junio C Hamano wrote:\n> Cory Kramer <corykramer@google.com> writes:\n> \n> > In the docs for git-clone the brackets become mismatched for any\n> > options that have a [no-] counterpart.\n> > https://git-scm.com/docs/git-clone\n> \n> Interesting.  The preformatted pages that were directly generated\n> from the sources at https://git.github.io/htmldocs/git-clone.html\n> has no such breakage.\n> \n> Cory, thanks for reporting.\n> \n> I think 76880f05 (doc: git-clone: apply new documentation formatting\n> guidelines, 2024-03-29) is where the alleged \"breakage\" came from.\n> \n> Comparing it with pages that weren't updated by the topic that ends\n> at 58dd7e4b (Merge branch 'ja/doc-markup-updates', 2024-04-09), like\n> \n>     https://git-scm.com/docs/git-clone\n>     https://git-scm.com/docs/git-add\n> \n> I notice that the latter is rendered with \"--[no-]ignore-removal\"\n> correctly shown.\n> \n> Two possible action items are\n> \n>  - Compare the preformatted pages at https://git.github.io/htmldocs/\n>    between git-clone and git-add and re-evaluate if the earlier\n>    ja/doc-markup-updates topic did to the SYNOPSIS is really what we\n>    want (the difference is harder to assess by looking at the pages\n>    at https://git-scm.com/docs/).\n> \n>  - Update the machinery that formats our documentation sources and\n>    renders at https://git-scm.com/docs/ to grok the mark-up used by\n>    ja/doc-markup-updates topic (currently in use for clone, init,\n>    and nothing else).\n> \n> Do anybody remember what transmongering produces the copy shown at\n> git-scm.com from the source?  Is it computed from the preformatted\n> pages, or from the source?\n> \n\nHello,\n\nThis discrepancy is the another instance of asciidoc.py vs. asciidoctor. The \ntoolchain for git uses asciidoc.py, whereas git-scm.com uses asciidoctor to \nprocess the source txt files.\n\nAsciidoc.py does not have the concept of generalized roles, whereas \nasciidoctor interprets   [foo]`blah` as blah with role foo in the synopsis, \nmaking in effect foo disappear in the output. Note that square brackets not \ndirectly followed by an inline markup do not define a role, which is why we do \nnot have the issue on other parts of the documentation.\n\nThis behavior of asciidoctor is not consistant (at least in my understanding), \nas it behaves like asciidoc.py when the same markup is used in a definition \nlist.\n\nIn order to get a consistant result across asciidoctor and asciidoc.py, the \nonly hack I have found is to use the {empty} entity to split the bracket part \nfrom the inline format part. It is ugly, but unfortunately the roles are a \nwanted feature by technical writers because it adds semantics to the source.\n\nThe main difference of rendering introduced by my patch is that placeholders \nand keywords are clearly differentiated. When visualizing with the man command, \nthe reworked pages are following the general style applied to placeholders \n(which are underlined) and keywords (which are bold).\n\nI can shortly submit a small patch to fix this, by introducing the ugly  \n{empty} entities where needed. Despite not being active lately, I still have \nin project to propose reworked pages for git-add, git-status, git-diff and git-\ncommit in a short future.\n\nBest regards,\n\nJN\n\n\n\n\n\n\n"}]}