| Message ID | pull.1749.git.git.1721507416683.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | asciidoctor: fix `synopsis` rendering | expand |
"Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Johannes Schindelin <johannes.schindelin@gmx.de> > > Since 76880f0510c (doc: git-clone: apply new documentation formatting > guidelines, 2024-03-29), the synopsis of `git clone`'s manual page is > rendered differently than before; Its parent commit did the same for > `git init`. > > The result looks quite nice. When rendered with AsciiDoc, that is. When > rendered using AsciiDoctor, the result is quite unpleasant to my eye, > reading something like this: > > SYNOPSIS > > git clone > [ > --template= > <template-directory>] > [ > -l > ] [ > -s > ] [ > --no-hardlinks > ] [ > -q > ] [ > [... continuing like this ...] Hmph, this may probably depend on the version of asciidoctor, but I am getting quite different output. It looks very similar to what is shown at https://git-scm.com/docs/git-clone/2.45.0. Even more puzzling, with or without this patch applied, I do not see any difference in the rendered output of samples I used, which were "clone", which has the changes from 76880f0510c and "add", which hasn't been broken by the series. $ make -C Documentation USE_ASCIIDOCTOR=YesPlease git-{clone,add}.{html,1} $ man -l Documentation/git-clone.1 $ lynx Documentation/git-clone.html $ man -l Documentation/git-add.1 $ lynx Documentation/git-add.html The rendered result is bad in the same way with or without this patch applied, and "git clone" manual page is simply incorrect by mangling a handful of command line options. A recent bug report in the thread that contains https://lore.kernel.org/git/xmqqle1xjm1s.fsf@gitster.g/ gives us more details. > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 3f2383a12c7..78e407e4bd1 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5 > ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 > ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions > ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' > +ASCIIDOC_EXTRA += -adocinfo=shared > ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS > DBLATEX_COMMON = > XMLTO_EXTRA += --skip-validation > diff --git a/Documentation/docinfo.html b/Documentation/docinfo.html > new file mode 100644 > index 00000000000..fb3560eb92b > --- /dev/null > +++ b/Documentation/docinfo.html > @@ -0,0 +1,5 @@ > +<style> > +pre>code { > + display: inline; > +} > +</style> > > base-commit: 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc
Junio C Hamano <gitster@pobox.com> writes: > The rendered result is bad in the same way with or without this > patch applied, and "git clone" manual page is simply incorrect by > mangling a handful of command line options. A recent bug report in > the thread that contains > > https://lore.kernel.org/git/xmqqle1xjm1s.fsf@gitster.g/ > > gives us more details. With Jean-Noël Avila's {empty} patch applied, would this patch be still necessary? I am wondering if the reason why "git clone" page needs this patch while others do not may have something to do with the mistaken triggering of "generalized roles" feature (whatever it is). Even though I dislike that we have to resort to the {empty} hack, if the misrendered block display you are fixing with this patch is due to the "generalized roles" problem, fixing the latter would also be the right fix for your problem. Thanks. >> diff --git a/Documentation/Makefile b/Documentation/Makefile >> index 3f2383a12c7..78e407e4bd1 100644 >> --- a/Documentation/Makefile >> +++ b/Documentation/Makefile >> @@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5 >> ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 >> ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions >> ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' >> +ASCIIDOC_EXTRA += -adocinfo=shared >> ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS >> DBLATEX_COMMON = >> XMLTO_EXTRA += --skip-validation >> diff --git a/Documentation/docinfo.html b/Documentation/docinfo.html >> new file mode 100644 >> index 00000000000..fb3560eb92b >> --- /dev/null >> +++ b/Documentation/docinfo.html >> @@ -0,0 +1,5 @@ >> +<style> >> +pre>code { >> + display: inline; >> +} >> +</style> >> >> base-commit: 76880f0510c6be9f6385f2d43dcfcba4eca9ccbc
Junio C Hamano <gitster@pobox.com> writes: > Junio C Hamano <gitster@pobox.com> writes: > >> The rendered result is bad in the same way with or without this >> patch applied, and "git clone" manual page is simply incorrect by >> mangling a handful of command line options. A recent bug report in >> the thread that contains >> >> https://lore.kernel.org/git/xmqqle1xjm1s.fsf@gitster.g/ >> >> gives us more details. > > With Jean-Noël Avila's {empty} patch applied, would this patch be > still necessary? The answer is no. I managed to reproduce the problem your patch fixes locally, applied Jean-Noël's patch which corrected the mark-up to avoid losing text in the [square brackets], but the problem still reproduced. It really seems that the `monospaced` text that are used in the SYNOPSIS section are rendered with display:block. I am not sure if forcing any <code> that appears as a (direct or indirect) descendant of <pre> with custom css is specific enough, but that certainly covers the breakage we see on the page. So the difference I observed between git-clone.html and say git-add.html is purely coming from use of `monospaced` in SYNOPSIS, and not because the unintended triggering of a feature by [text]`more text` that Jean-Noël's patch fixes. With or without that fix, the css tweak is still needed (it may be overly generic and may require us to tighten the selector later, but we can worry about it when somebody finds an actual breakage). It is unfortunate that all .html files ought to be generated in this project (in other words, nobody writes HTML by hand), but asciidoc(tor) insists that docinfo for html backend must be stored in a file whose extension is .html, which caused a "huh?" Ramsay reported earlier. Will queue. Thanks.
diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f2383a12c7..78e407e4bd1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -202,6 +202,7 @@ ASCIIDOC_DOCBOOK = docbook5 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +ASCIIDOC_EXTRA += -adocinfo=shared ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation diff --git a/Documentation/docinfo.html b/Documentation/docinfo.html new file mode 100644 index 00000000000..fb3560eb92b --- /dev/null +++ b/Documentation/docinfo.html @@ -0,0 +1,5 @@ +<style> +pre>code { + display: inline; +} +</style>