{"thread":{"id":"55640","subject":"[RFC suggestion] Generate manpage directly with Asciidoctor","startedAt":"2021-05-07T06:06:37Z","lastAt":"2021-05-12T01:44:44Z","messageCount":38,"participants":["Bagas Sanjaya","Randall S. Becker","Đoàn Trần Công Danh","brian m. carlson","Jeff King","Felipe Contreras","Martin Ågren","Jean-Noël Avila","Ævar Arnfjörð Bjarmason"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"423861","messageId":"3461c7b0-594d-989e-3048-2fc6583084ad@gmail.com","threadId":"55640","inReplyTo":null,"subject":"[RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-07T06:06:31Z","receivedAt":"2021-05-07T06:06:37Z","isPatch":false,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Hi,\n\nAsciidoctor has support for directly generating manpage, see [1].\n\nWe support using Asciidoctor as drop-in replacement for original\nAsciidoc, but currently we need to use xmlto together with Asciidoc(tor)\nto produce manpages. However, most users don't inclined to install\nxmlto toolchain, partly because they had to download more than 300 MB\nof data just to install xmlto and its dependencies (including dblatex\nand texlive).\n\nSo completely migrating to Asciidoctor can eliminate xmlto requirement\nfor generating manpage.\n\nWhat do you think about above?\n\n[1]: https://docs.asciidoctor.org/asciidoctor/latest/manpage-backend/\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"423868","messageId":"00db01d74338$d45615c0$7d024140$@nexbridge.com","threadId":"55640","inReplyTo":"3461c7b0-594d-989e-3048-2fc6583084ad@gmail.com","subject":"RE: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2021-05-07T12:02:13Z","receivedAt":"2021-05-07T12:02:27Z","isPatch":false,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On May 7, 2021 2:07 AM, Bagas Sanjaya wrote:\n>To: Git Users \n>Subject: [RFC suggestion] Generate manpage directly with Asciidoctor\n>Asciidoctor has support for directly generating manpage, see [1].\n>\n>We support using Asciidoctor as drop-in replacement for original Asciidoc, but\n>currently we need to use xmlto together with Asciidoc(tor) to produce\n>manpages. However, most users don't inclined to install xmlto toolchain, partly\n>because they had to download more than 300 MB of data just to install xmlto\n>and its dependencies (including dblatex and texlive).\n>\n>So completely migrating to Asciidoctor can eliminate xmlto requirement for\n>generating manpage.\n>\n>What do you think about above?\n\nOur toolchain does not support asciidoctor itself because of porting issues. I am not sure it is available everywhere.\n\n-Randall\n\n-- Brief whoami:\nNonStop developer since approximately 211288444200000000\nUNIX developer since approximately 421664400\n-- In my real life, I talk too much.\n\n\n\n"},{"id":"423869","messageId":"YJUyHkYAIth0W9dY@danh.dev","threadId":"55640","inReplyTo":"3461c7b0-594d-989e-3048-2fc6583084ad@gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Đoàn Trần Công Danh","fromEmail":"congdanhqx@gmail.com","sentAt":"2021-05-07T12:27:10Z","receivedAt":"2021-05-07T12:27:17Z","isPatch":false,"sender":{"key":"congdanhqx@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42673067?v=4"},"body":"On 2021-05-07 13:06:31+0700, Bagas Sanjaya wrote:\n> Hi,\n> \n> Asciidoctor has support for directly generating manpage, see [1].\n\nWhile I'm impressed with this news.\n\n> We support using Asciidoctor as drop-in replacement for original\n> Asciidoc, but currently we need to use xmlto together with Asciidoc(tor)\n> to produce manpages. However, most users don't inclined to install\n> xmlto toolchain, partly because they had to download more than 300 MB\n> of data just to install xmlto and its dependencies (including dblatex\n> and texlive).\n\nI'm pretty sure xmlto doesn't depend on dblatex and/or texlive.\n\nI'm building Git and Git's documentation on different Linux boxes with\nasciidoc, most of them don't have dblatex and/or texlive.\nIn fact, I only have texlive installed in my laptop.\n\nI guess you're using Debian or one of its derived distribution?\nDebian puts dblatex as xmlto's rec. [2]\n\nI think you can use:\n\n\tapt install --no-install-recommends xmlto\n\nto avoid those recommendations.\n\n> So completely migrating to Asciidoctor can eliminate xmlto requirement\n> for generating manpage.\n> \n> What do you think about above?\n\nHm, I'm pretty sure Ruby (asciidoctor's language) is very hard to port.\nLast I heard, it's buggy on some platforms.\n\nI think we're better to do like this:\n\n* If we're using asciidoc, we will use xmlto\n* If we're using asciidoctor, we will generate man-pages with\n asciidoctor directly\n\n> [1]: https://docs.asciidoctor.org/asciidoctor/latest/manpage-backend/\n\n[2]: https://packages.debian.org/sid/xmlto\n\n-- \nDanh\n"},{"id":"423870","messageId":"91eb6197-41b5-257a-34d5-6865df793880@gmail.com","threadId":"55640","inReplyTo":"YJUyHkYAIth0W9dY@danh.dev","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-07T12:47:03Z","receivedAt":"2021-05-07T12:47:09Z","isPatch":false,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 07/05/21 19.27, Đoàn Trần Công Danh wrote:\n> I'm pretty sure xmlto doesn't depend on dblatex and/or texlive.\n> \n> I'm building Git and Git's documentation on different Linux boxes with\n> asciidoc, most of them don't have dblatex and/or texlive.\n> In fact, I only have texlive installed in my laptop.\n> \n> I guess you're using Debian or one of its derived distribution?\n> Debian puts dblatex as xmlto's rec. [2]\n> \n> I think you can use:\n> \n> \tapt install --no-install-recommends xmlto\n> \n> to avoid those recommendations.\n>\n\nYes, I'm using Ubuntu (derived from Debian).\n\n> Hm, I'm pretty sure Ruby (asciidoctor's language) is very hard to port.\n> Last I heard, it's buggy on some platforms.\n> \n> I think we're better to do like this:\n> \n> * If we're using asciidoc, we will use xmlto\n> * If we're using asciidoctor, we will generate man-pages with\n> asciidoctor directly\n> \n\nNice for your suggestion.\n\nBut will the resulting manpage from asciidoc+xmlto and from asciidoctor\nsyntatically and semantically same?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"423880","messageId":"YJWiQH2nf0B14Zy7@camp.crustytoothpaste.net","threadId":"55640","inReplyTo":"3461c7b0-594d-989e-3048-2fc6583084ad@gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-05-07T20:25:36Z","receivedAt":"2021-05-07T20:25:43Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-05-07 at 06:06:31, Bagas Sanjaya wrote:\n> Hi,\n> \n> Asciidoctor has support for directly generating manpage, see [1].\n> \n> We support using Asciidoctor as drop-in replacement for original\n> Asciidoc, but currently we need to use xmlto together with Asciidoc(tor)\n> to produce manpages. However, most users don't inclined to install\n> xmlto toolchain, partly because they had to download more than 300 MB\n> of data just to install xmlto and its dependencies (including dblatex\n> and texlive).\n\nIf you're installing on Debian, you want to install with\n--no-install-recommends to avoid the dependency on dblatex or fop,\nlibpaper-utils, and zip. That should avoid the large downloads.\n\n> So completely migrating to Asciidoctor can eliminate xmlto requirement\n> for generating manpage.\n> \n> What do you think about above?\n\nI didn't do this because it makes things very complicated in the\nMakefile and my goal was to minimize the needed changes and divergence.\nI'm not opposed to someone else doing it, but I expect it will be a\nbunch of work.\n\nIt also doesn't help if you're generating more than just the manual\npages, since generating the PDFs will definitely require xmlto and\neither dblatex or fop. I personally prefer fop over dblatex, but folks\nhave different opinions.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"423883","messageId":"YJW81zNr5bgW+yVs@coredump.intra.peff.net","threadId":"55640","inReplyTo":"YJWiQH2nf0B14Zy7@camp.crustytoothpaste.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-07T22:19:03Z","receivedAt":"2021-05-07T22:19:06Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, May 07, 2021 at 08:25:36PM +0000, brian m. carlson wrote:\n\n> > So completely migrating to Asciidoctor can eliminate xmlto requirement\n> > for generating manpage.\n> > \n> > What do you think about above?\n> \n> I didn't do this because it makes things very complicated in the\n> Makefile and my goal was to minimize the needed changes and divergence.\n> I'm not opposed to someone else doing it, but I expect it will be a\n> bunch of work.\n\nYeah. In the period where we support both asciidoc and asciidoctor,\nusing the same flow for both (even if it's suboptimal for asciidoctor)\nkept the complexity down.\n\nI _thought_ the original asciidoc was marked as deprecated /\nunmaintained at some point. But it does seem to have gotten a few\nreleases in the last year (it looks like maybe the python 2 version was\nEOL, but somebody decided to make the effort to port it to python 3?).\n\nBut I wouldn't be at all sad to just standardize on asciidoctor. I think\nwe're at parity in terms of the output (thanks to lots of work from you\nand Martin over the past couple of years), and I've generally found it\nnicer to work with.\n\nThe only downside is that it may be available in fewer places (though\nI'd think that python vs ruby is not so different). IMHO it's OK to be\naggressive about the doc toolchain requirements, because the fallback is\nalways grabbing the preformatted roff or HTML pages that were generated\non a different system.\n\n-Peff\n"},{"id":"423884","messageId":"6095c3c8fba6_cfc72088a@natae.notmuch","threadId":"55640","inReplyTo":"3461c7b0-594d-989e-3048-2fc6583084ad@gmail.com","subject":"RE: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-07T22:48:40Z","receivedAt":"2021-05-07T22:48:50Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> Asciidoctor has support for directly generating manpage, see [1].\n> \n> We support using Asciidoctor as drop-in replacement for original\n> Asciidoc, but currently we need to use xmlto together with Asciidoc(tor)\n> to produce manpages. However, most users don't inclined to install\n> xmlto toolchain, partly because they had to download more than 300 MB\n> of data just to install xmlto and its dependencies (including dblatex\n> and texlive).\n> \n> So completely migrating to Asciidoctor can eliminate xmlto requirement\n> for generating manpage.\n> \n> What do you think about above?\n\nMakes complete sense. If only we had some patches to go along with that\nproposal.\n\n-- \nFelipe Contreras\n"},{"id":"423885","messageId":"6095c54fe0766_cfc7208e0@natae.notmuch","threadId":"55640","inReplyTo":"00db01d74338$d45615c0$7d024140$@nexbridge.com","subject":"RE: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-07T22:55:11Z","receivedAt":"2021-05-07T22:55:17Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Randall S. Becker wrote:\n> On May 7, 2021 2:07 AM, Bagas Sanjaya wrote:\n> >To: Git Users \n> >Subject: [RFC suggestion] Generate manpage directly with Asciidoctor\n> >What do you think about above?\n> \n> Our toolchain does not support asciidoctor itself because of porting\n> issues. I am not sure it is available everywhere.\n\nThen don't use it.\n\nIf I understand correctly the proposal affects people that build with\nUSE_ASCIIDOCTOR=YesPlease only.\n\n-- \nFelipe Contreras\n"},{"id":"423887","messageId":"YJXF3oq4n/NFJSx3@camp.crustytoothpaste.net","threadId":"55640","inReplyTo":"00db01d74338$d45615c0$7d024140$@nexbridge.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-05-07T22:57:34Z","receivedAt":"2021-05-07T22:58:12Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-05-07 at 12:02:13, Randall S. Becker wrote:\n> On May 7, 2021 2:07 AM, Bagas Sanjaya wrote:\n> >To: Git Users \n> >Subject: [RFC suggestion] Generate manpage directly with Asciidoctor\n> >Asciidoctor has support for directly generating manpage, see [1].\n> >\n> >We support using Asciidoctor as drop-in replacement for original Asciidoc, but\n> >currently we need to use xmlto together with Asciidoc(tor) to produce\n> >manpages. However, most users don't inclined to install xmlto toolchain, partly\n> >because they had to download more than 300 MB of data just to install xmlto\n> >and its dependencies (including dblatex and texlive).\n> >\n> >So completely migrating to Asciidoctor can eliminate xmlto requirement for\n> >generating manpage.\n> >\n> >What do you think about above?\n> \n> Our toolchain does not support asciidoctor itself because of porting issues. I am not sure it is available everywhere.\n\nI think Asciidoctor is pure Ruby, since it also uses JRuby and Opal to\nrun in Java and JavaScript environments. Ruby is relatively portable to\nmost architectures and systems (for example, it runs on 16 Debian\narchitectures).\n\nIs the problem in your case Ruby or is it Asciidoctor itself? I'm happy\nto send portability patches to Asciidoctor if necessary, but I'm not\nsure I'm a good candidate to send patches to Ruby itself, especially for\nan OS I don't use.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"423888","messageId":"6095c74993f19_cfc72085d@natae.notmuch","threadId":"55640","inReplyTo":"YJUyHkYAIth0W9dY@danh.dev","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-07T23:03:37Z","receivedAt":"2021-05-07T23:03:41Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Đoàn Trần Công Danh wrote:\n> On 2021-05-07 13:06:31+0700, Bagas Sanjaya wrote:\n> > So completely migrating to Asciidoctor can eliminate xmlto requirement\n> > for generating manpage.\n> > \n> > What do you think about above?\n> \n> Hm, I'm pretty sure Ruby (asciidoctor's language) is very hard to port.\n> Last I heard, it's buggy on some platforms.\n\nAnd I'm pretty sure it isn't.\n\nRuby is a mainstream language. At some point it was #8 in the TIOBE\nindex, above PHP and Perl. Right now it's #11.\n\nA lot of effort has been put to make Ruby work on all platforms.\n\n> I think we're better to do like this:\n> \n> * If we're using asciidoc, we will use xmlto\n> * If we're using asciidoctor, we will generate man-pages with\n> asciidoctor directly\n\nThis certainly is the way to go.\n\nI'm not sure if Bagas suggested to make USE_ASCIIDOCTOR=YesPlease the\ndefault, but first we would need to make sure the output without xmlto\nis desirable, which we don't at the moment.\n\nSo, even if we were to consider this, *first* the option to use pure\nasciidoctor needs to be in place.\n\nCheers.\n\n-- \nFelipe Contreras"},{"id":"423891","messageId":"6095ceb984401_cfc7208b9@natae.notmuch","threadId":"55640","inReplyTo":"YJWiQH2nf0B14Zy7@camp.crustytoothpaste.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-07T23:35:21Z","receivedAt":"2021-05-07T23:35:30Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"brian m. carlson wrote:\n> On 2021-05-07 at 06:06:31, Bagas Sanjaya wrote:\n> > So completely migrating to Asciidoctor can eliminate xmlto requirement\n> > for generating manpage.\n> > \n> > What do you think about above?\n> \n> I didn't do this because it makes things very complicated in the\n> Makefile and my goal was to minimize the needed changes and divergence.\n> I'm not opposed to someone else doing it, but I expect it will be a\n> bunch of work.\n\nI don't think it would be that complicated.\n\nThis patch seems to do the trick here:\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex c2baad0bd8..8fa4896d22 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -189,6 +189,7 @@ ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage\n endif\n \n SHELL_PATH ?= $(SHELL)\n@@ -360,9 +361,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS\n manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n \n+ifdef TXT_TO_MAN\n+%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n+\t$(TXT_TO_MAN) -o $@+ $< && \\\n+\tmv $@+ $@\n+else\n %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n \t$(QUIET_XMLTO)$(RM) $@ && \\\n \t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n+endif\n \n %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n\nI'm sure this can be improved with some knowledge about intermediary\nrules.\n\n> It also doesn't help if you're generating more than just the manual\n> pages, since generating the PDFs will definitely require xmlto and\n> either dblatex or fop. I personally prefer fop over dblatex, but folks\n> have different opinions.\n\nHuh? user-manual.pdf seems to require DBLATEX, not XMLTO.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"423892","messageId":"YJXT7AaqCeCV4WcZ@camp.crustytoothpaste.net","threadId":"55640","inReplyTo":"6095ceb984401_cfc7208b9@natae.notmuch","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-05-07T23:57:32Z","receivedAt":"2021-05-07T23:58:15Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-05-07 at 23:35:21, Felipe Contreras wrote:\n> I don't think it would be that complicated.\n> \n> This patch seems to do the trick here:\n> \n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index c2baad0bd8..8fa4896d22 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -189,6 +189,7 @@ ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n> DBLATEX_COMMON =\n> XMLTO_EXTRA += --skip-validation\n> XMLTO_EXTRA += -x manpage.xsl\n> +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage\n> endif\n> \n> SHELL_PATH ?= $(SHELL)\n> @@ -360,9 +361,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS\n> manpage-base-url.xsl: manpage-base-url.xsl.in\n> \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n> \n> +ifdef TXT_TO_MAN\n> +%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n> +\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> +\t$(TXT_TO_MAN) -o $@+ $< && \\\n> +\tmv $@+ $@\n> +else\n> %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n> \t$(QUIET_XMLTO)$(RM) $@ && \\\n> \t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n> +endif\n> \n> %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n> \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> \n> I'm sure this can be improved with some knowledge about intermediary\n> rules.\n\nIt's not quite that simple. It requires changes to\nasciidoctor-extensions.rb and we also need to consider\nNO_MAN_BOLD_LITERAL and GNU_ROFF. The latter especially is likely to be\ninconvenient, since according to the Makefile, it's impossible to write\nman output that works across troff versions.\n\nWe will also want to preserve the ability to use xmlto because we\ncurrently have doc-diff which helps us find divergences in the behavior\nof AsciiDoc and Asciidoctor, many of which affect all formats, and that\nwill be completely useless if we use two different rendering toolchains.\n\nSo, yes, this is a good start, but it's not quite as trivial as it seems.\n\n> > It also doesn't help if you're generating more than just the manual\n> > pages, since generating the PDFs will definitely require xmlto and\n> > either dblatex or fop. I personally prefer fop over dblatex, but folks\n> > have different opinions.\n> \n> Huh? user-manual.pdf seems to require DBLATEX, not XMLTO.\n\nAh, yes, because we do it manually instead of using xmlto.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"423904","messageId":"013c01d743ab$7577c0d0$60674270$@nexbridge.com","threadId":"55640","inReplyTo":"YJXF3oq4n/NFJSx3@camp.crustytoothpaste.net","subject":"RE: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Randall S. Becker","fromEmail":"rsbecker@nexbridge.com","sentAt":"2021-05-08T01:42:46Z","receivedAt":"2021-05-08T01:42:59Z","isPatch":false,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On May 7, 2021 6:58 PM, brian m. carlson wrote:\n>Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor\n>\n>On 2021-05-07 at 12:02:13, Randall S. Becker wrote:\n>> On May 7, 2021 2:07 AM, Bagas Sanjaya wrote:\n>> >To: Git Users \n>> >Subject: [RFC suggestion] Generate manpage directly with Asciidoctor\n>> >Asciidoctor has support for directly generating manpage, see [1].\n>> >\n>> >We support using Asciidoctor as drop-in replacement for original\n>> >Asciidoc, but currently we need to use xmlto together with\n>> >Asciidoc(tor) to produce manpages. However, most users don't inclined\n>> >to install xmlto toolchain, partly because they had to download more\n>> >than 300 MB of data just to install xmlto and its dependencies (including\n>dblatex and texlive).\n>> >\n>> >So completely migrating to Asciidoctor can eliminate xmlto\n>> >requirement for generating manpage.\n>> >\n>> >What do you think about above?\n>>\n>> Our toolchain does not support asciidoctor itself because of porting issues. I\n>am not sure it is available everywhere.\n>\n>I think Asciidoctor is pure Ruby, since it also uses JRuby and Opal to run in Java\n>and JavaScript environments. Ruby is relatively portable to most architectures\n>and systems (for example, it runs on 16 Debian architectures).\n>\n>Is the problem in your case Ruby or is it Asciidoctor itself? I'm happy to send\n>portability patches to Asciidoctor if necessary, but I'm not sure I'm a good\n>candidate to send patches to Ruby itself, especially for an OS I don't use.\n\nIn this case, Ruby is not 100% portable to all platforms. I have an old port, but the latest version is not portable because of unportable dependencies - not for a lack of a large amount of trying. So the assumption is not entirely workable. My only option is to take the pre-generated pages from the manpages repo.\n\n-Randall\n\n"},{"id":"423908","messageId":"YJYBOrm2cQkkVteb@coredump.intra.peff.net","threadId":"55640","inReplyTo":"YJXT7AaqCeCV4WcZ@camp.crustytoothpaste.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-08T03:10:50Z","receivedAt":"2021-05-08T03:10:54Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, May 07, 2021 at 11:57:32PM +0000, brian m. carlson wrote:\n\n> It's not quite that simple. It requires changes to\n> asciidoctor-extensions.rb and we also need to consider\n> NO_MAN_BOLD_LITERAL and GNU_ROFF. The latter especially is likely to be\n> inconvenient, since according to the Makefile, it's impossible to write\n> man output that works across troff versions.\n> \n> We will also want to preserve the ability to use xmlto because we\n> currently have doc-diff which helps us find divergences in the behavior\n> of AsciiDoc and Asciidoctor, many of which affect all formats, and that\n> will be completely useless if we use two different rendering toolchains.\n\nSpeaking of doc-diff: with that patch applied, try \"./doc-diff\n--asciidoctor HEAD^ HEAD\", which shows quite a few of the complications\n(another one seems to be that all of the linkgit macros are broken).\n\n-Peff\n"},{"id":"423909","messageId":"YJYERMX0OZI6DEWR@coredump.intra.peff.net","threadId":"55640","inReplyTo":"YJYBOrm2cQkkVteb@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-08T03:23:48Z","receivedAt":"2021-05-08T03:23:50Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, May 07, 2021 at 11:10:50PM -0400, Jeff King wrote:\n\n> On Fri, May 07, 2021 at 11:57:32PM +0000, brian m. carlson wrote:\n> \n> > It's not quite that simple. It requires changes to\n> > asciidoctor-extensions.rb and we also need to consider\n> > NO_MAN_BOLD_LITERAL and GNU_ROFF. The latter especially is likely to be\n> > inconvenient, since according to the Makefile, it's impossible to write\n> > man output that works across troff versions.\n> > \n> > We will also want to preserve the ability to use xmlto because we\n> > currently have doc-diff which helps us find divergences in the behavior\n> > of AsciiDoc and Asciidoctor, many of which affect all formats, and that\n> > will be completely useless if we use two different rendering toolchains.\n> \n> Speaking of doc-diff: with that patch applied, try \"./doc-diff\n> --asciidoctor HEAD^ HEAD\", which shows quite a few of the complications\n> (another one seems to be that all of the linkgit macros are broken).\n\nHmph. Actually, this seems to give inconsistent results. There\ndefinitely is a problem. Try:\n\n cd Documentation\n make USE_ASCIIDOCTOR=1 git.1\n man -l git.1 >old\n git am .../the_patch\n make USE_ASCIIDOCTOR=1 git.1\n man -l git.1 >new\n diff -u old new\n\nwhich shows it. I think the patch does not specify the dependencies to\nmake correctly (and doc-diff reuses the worktree to avoid work). Doing\nthis:\n\n git am .../the_patch\n ./doc-diff --asciidoctor HEAD HEAD\n ./doc-diff --asciidoctor HEAD^ HEAD\n\nworks around it and shows the extent of the problem.\n\n(Not really a critique on the patch, which I know was meant to be a\nquick illustration, but I thought it worth pointing out a doc-diff\ncommand which actually works).\n\n-Peff\n"},{"id":"423910","messageId":"cfe45519-9c47-7773-080a-af222a775011@gmail.com","threadId":"55640","inReplyTo":"YJW81zNr5bgW+yVs@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-08T04:22:55Z","receivedAt":"2021-05-08T04:23:02Z","isPatch":false,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 08/05/21 05.19, Jeff King wrote:\n\n> I _thought_ the original asciidoc was marked as deprecated /\n> unmaintained at some point. But it does seem to have gotten a few\n> releases in the last year (it looks like maybe the python 2 version was\n> EOL, but somebody decided to make the effort to port it to python 3?).\n\nAsciidoc.py [1] now supports Python 3, however it only handles legacy\nAsciiDoc syntax.\n\n[1]: https://github.com/asciidoc-py/asciidoc-py\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"423911","messageId":"5130bb11-002c-9aa9-ac6d-11bfd6f85f3f@gmail.com","threadId":"55640","inReplyTo":"6095c74993f19_cfc72085d@natae.notmuch","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-08T04:27:01Z","receivedAt":"2021-05-08T04:27:07Z","isPatch":false,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 08/05/21 06.03, Felipe Contreras wrote:\n >> I think we're better to do like this:\n>>\n>> * If we're using asciidoc, we will use xmlto\n>> * If we're using asciidoctor, we will generate man-pages with\n>> asciidoctor directly\n> \n> This certainly is the way to go.\n> \n> I'm not sure if Bagas suggested to make USE_ASCIIDOCTOR=YesPlease the\n> default, but first we would need to make sure the output without xmlto\n> is desirable, which we don't at the moment.\n\nI'm not aiming for defaulting to AsciiDoctor, but I agree that we would like\nto migrate away from xmlto by making sure the output sans it is desirable.\n\n> So, even if we were to consider this, *first* the option to use pure\n> asciidoctor needs to be in place.\n\nDon't you know there is USE_ASCIIDOCTOR=YesPlease flag which do the job?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"423952","messageId":"YJcrNXEwNJpB8G/0@camp.crustytoothpaste.net","threadId":"55640","inReplyTo":"YJYBOrm2cQkkVteb@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-05-09T00:22:13Z","receivedAt":"2021-05-09T00:22:41Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-05-08 at 03:10:50, Jeff King wrote:\n> On Fri, May 07, 2021 at 11:57:32PM +0000, brian m. carlson wrote:\n> \n> > It's not quite that simple. It requires changes to\n> > asciidoctor-extensions.rb and we also need to consider\n> > NO_MAN_BOLD_LITERAL and GNU_ROFF. The latter especially is likely to be\n> > inconvenient, since according to the Makefile, it's impossible to write\n> > man output that works across troff versions.\n> > \n> > We will also want to preserve the ability to use xmlto because we\n> > currently have doc-diff which helps us find divergences in the behavior\n> > of AsciiDoc and Asciidoctor, many of which affect all formats, and that\n> > will be completely useless if we use two different rendering toolchains.\n> \n> Speaking of doc-diff: with that patch applied, try \"./doc-diff\n> --asciidoctor HEAD^ HEAD\", which shows quite a few of the complications\n> (another one seems to be that all of the linkgit macros are broken).\n\nYes, that's because the linkgit macros are specified on a\nformat-specific basis by the extensions file and without updating\nthey won't understand how to generate output for the manpage formatter.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"423956","messageId":"CAN0heSpN_ieGc2HJCvSsmUuEqS-GGPDcZHz=v2Z3hJY=Or_HMw@mail.gmail.com","threadId":"55640","inReplyTo":"YJW81zNr5bgW+yVs@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-09T08:20:37Z","receivedAt":"2021-05-09T08:20:53Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sat, 8 May 2021 at 00:19, Jeff King wrote:\n>\n> I _thought_ the original asciidoc was marked as deprecated /\n> unmaintained at some point. But it does seem to have gotten a few\n> releases in the last year (it looks like maybe the python 2 version was\n> EOL, but somebody decided to make the effort to port it to python 3?).\n>\n> But I wouldn't be at all sad to just standardize on asciidoctor. I think\n> we're at parity in terms of the output (thanks to lots of work from you\n> and Martin over the past couple of years), and I've generally found it\n> nicer to work with.\n\nI tend to think asciidoctor even renders our manpages *better* than\nasciidoc does. Not by a huge margin, but a few things here and there.\nSome time around the Python 2 EOL, I was about to propose flipping the\ndefault, but then I went to look up the asciidoc EOL schedule, and like\nyou, I noticed that it was a lot more alive and kicking than I thought\nit was. So it's not so much \"we should flip to avoid a bitrotting\ndependency\" as it is \"asciidoctor is arguably nicer\" or \"it's the way\nforward\".\n\nI've done some working-around in the past to try to make something look\nnon-broken in both of asciidoc and asciidoctor. Working with *three*\ntoolchains, we should probably be clear about which one it is we're\ngoing to leave behind, and that shouldn't be the default. I'll be happy\nto make a patch. I can't use the EOL argument, it seems, but I do think\nit's the only thing that will allow us to reach an xmlto-less generation\nof the manpages without losing our minds.\n\n> The only downside is that it may be available in fewer places (though\n> I'd think that python vs ruby is not so different). IMHO it's OK to be\n> aggressive about the doc toolchain requirements, because the fallback is\n> always grabbing the preformatted roff or HTML pages that were generated\n> on a different system.\n\nIn general, I agree. I do think it's important that \"most people\ncontributing to Git\", whatever that means, can build the documentation\nto check the part they're adding/modifying and not find it broken left\nand right. They would then (quite rightly) not even bother building it.\n\nWhen we looked at xmlto-less rendering around two years ago [1], we\nfound various asciidoctor bugs up to and around version 2.0. We would\nlikely need to require some >=2.0.x. The exact requirements will\nprobably only become clear when someone really does the work.\n\nI think what I'm arguing for is\n\n 1) switch the default to asciidoctor,\n 2) enable optionally using it without xmlto,\n 3) figure out what broke and fix it, and document which is the minimum\n asciidoctor version we're going to bother with for (2),\n 4) lather, rinse, repeat (3),\n 5) switch the default to not using xmlto,\n 6) drop the xmlto way of generating the manpages(?).\n\n[1] https://lore.kernel.org/git/20190317194431.GY31362@pobox.com/\n\nMartin\n"},{"id":"423958","messageId":"CAN0heSrbJQjzbwm3CiNh7UduKSYKogsHBh6RQszDuk2cGu=r=w@mail.gmail.com","threadId":"55640","inReplyTo":"6095ceb984401_cfc7208b9@natae.notmuch","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-09T08:29:08Z","receivedAt":"2021-05-09T08:29:21Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sat, 8 May 2021 at 01:40, Felipe Contreras\n wrote:\n>\n> brian m. carlson wrote:\n> > On 2021-05-07 at 06:06:31, Bagas Sanjaya wrote:\n> > > So completely migrating to Asciidoctor can eliminate xmlto requirement\n> > > for generating manpage.\n> > >\n> > > What do you think about above?\n> >\n> > I didn't do this because it makes things very complicated in the\n> > Makefile and my goal was to minimize the needed changes and divergence.\n> > I'm not opposed to someone else doing it, but I expect it will be a\n> > bunch of work.\n>\n> I don't think it would be that complicated.\n>\n> This patch seems to do the trick here:\n\nThis looks similar to Todd's wip [1]. Here's something\nwhitespace-damaged on top that improves some things, but I'm sure\nthere's more to do. I think in order to work on this, it would need to\nbe a separate switch so that we can use asciidoctor both the old-school\nand the new-school way for a while.\n\n[1] https://lore.kernel.org/git/20190317194431.GY31362@pobox.com/\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 0cfa88a92b..9f73d2d033 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -192,7 +192,9 @@ ASCIIDOC_HTML = xhtml5\n ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n-ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+ASCIIDOC_EXTRA += -alitdd='\\--'\n+ASCIIDOC_EXTRA += -aplus='+'\n+ASCIIDOC_COMMON += -a mansource=\"Git $(GIT_VERSION)\" -a manmanual=\"Git Manual\"\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\ndiff --git a/Documentation/asciidoctor-extensions.rb\nb/Documentation/asciidoctor-extensions.rb\nindex d906a00803..fb74443241 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -10,11 +10,16 @@ module Git\n\n def process(parent, target, attrs)\n prefix = parent.document.attr('git-relative-html-prefix')\n+ s = \"#{target}(#{attrs[1]})\"\n if parent.document.doctype == 'book'\n \"\" \\\n \"#{target}(#{attrs[1]})\"\n+ elsif parent.document.basebackend? 'manpage'\n+ # FIXME: boldness should respect NO_MAN_BOLD_LITERAL?\n+ # -- should be doable using an attribute, similar\n+ # to \"prefix\" above\n+ create_inline(parent, :quoted, s, type: :strong).convert\n elsif parent.document.basebackend? 'html'\n %(#{target}(#{attrs[1]}))\n elsif parent.document.basebackend? 'docbook'\n \"\\n\" \\\n \"#{target}\" \\\n"},{"id":"423976","messageId":"CAMP44s3wagd6pk-YfnYV3QoRbZ5cRA0MBU4=Mdxerbdx80J7hw@mail.gmail.com","threadId":"55640","inReplyTo":"CAN0heSpN_ieGc2HJCvSsmUuEqS-GGPDcZHz=v2Z3hJY=Or_HMw@mail.gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-09T18:46:39Z","receivedAt":"2021-05-09T18:46:54Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, May 9, 2021 at 3:26 AM Martin Ågren wrote:\n\n> I think what I'm arguing for is\n>\n> 1) switch the default to asciidoctor,\n> 2) enable optionally using it without xmlto,\n> 3) figure out what broke and fix it, and document which is the minimum\n> asciidoctor version we're going to bother with for (2),\n> 4) lather, rinse, repeat (3),\n> 5) switch the default to not using xmlto,\n> 6) drop the xmlto way of generating the manpages(?).\n\nAre there some minimal requirements to say; this documentation was\nbuilt correctly (as far as we know)? If so, maybe we can add a\nchecker, or perhaps add a test under t/.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424069","messageId":"CAN0heSrcZrfD60SJW9pJADwF8=SQ3Zw0KW1ZZvF4EPh82cNtPw@mail.gmail.com","threadId":"55640","inReplyTo":"CAMP44s3wagd6pk-YfnYV3QoRbZ5cRA0MBU4=Mdxerbdx80J7hw@mail.gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-10T18:43:26Z","receivedAt":"2021-05-10T18:43:41Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 9 May 2021 at 20:46, Felipe Contreras\n wrote:\n>\n> Are there some minimal requirements to say; this documentation was\n> built correctly (as far as we know)? If so, maybe we can add a\n> checker, or perhaps add a test under t/.\n\nThere's `make check-doc` which does some linting. But that's about\nchecking that there's a manpage at all for each builtin, that the doc\nsources list sections in the right order, and such things. It doesn't\nactually build the docs.\n\nci/test-documentation.sh runs `make check-doc` (see above), then goes on\nto actually build the docs using both asciidoc and asciidoctor. It\nchecks the exit status, but also that stderr is empty after filtering\nout some expected, harmless output.\n\nI think that's about the right balance. We could perhaps do something\nunder t/, but it probably shouldn't be to actually build the stuff. More\nlike, \"oh, you've built the documentation -- let me sanity-check it for\nyou\". One way to detect that it makes sense to check it might be to see\nif the Git version in the manpage footer(s) matches the version under\ntest. But I don't know what to check next. (Actually, if we do find the\nversion number there, we have verified a fairly tricky piece of content\ninjection. At least \"tricky\" as in \"we have more than one way of doing\nit, because we support more than one toolchain\" [1]. And if that stuff\nbroke, the test wouldn't notice, if we relied on detecting a version\nmatch to even start testing...)\n\n[1] See 7a30134358 (\"asciidoctor-extensions: provide ``\",\n2019-09-16) and its parent commit.\n\nMartin\n"},{"id":"424080","messageId":"YJmykGWaWi03+WoW@coredump.intra.peff.net","threadId":"55640","inReplyTo":"CAN0heSpN_ieGc2HJCvSsmUuEqS-GGPDcZHz=v2Z3hJY=Or_HMw@mail.gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-10T22:24:16Z","receivedAt":"2021-05-10T22:24:24Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, May 09, 2021 at 10:20:37AM +0200, Martin Ågren wrote:\n\n> > But I wouldn't be at all sad to just standardize on asciidoctor. I think\n> > we're at parity in terms of the output (thanks to lots of work from you\n> > and Martin over the past couple of years), and I've generally found it\n> > nicer to work with.\n> \n> I tend to think asciidoctor even renders our manpages *better* than\n> asciidoc does. Not by a huge margin, but a few things here and there.\n\nYeah, I'd agree with that.\n\n> Some time around the Python 2 EOL, I was about to propose flipping the\n> default, but then I went to look up the asciidoc EOL schedule, and like\n> you, I noticed that it was a lot more alive and kicking than I thought\n> it was. So it's not so much \"we should flip to avoid a bitrotting\n> dependency\" as it is \"asciidoctor is arguably nicer\" or \"it's the way\n> forward\".\n\nI'm OK with those arguments, too. :)\n\n> > The only downside is that it may be available in fewer places (though\n> > I'd think that python vs ruby is not so different). IMHO it's OK to be\n> > aggressive about the doc toolchain requirements, because the fallback is\n> > always grabbing the preformatted roff or HTML pages that were generated\n> > on a different system.\n> \n> In general, I agree. I do think it's important that \"most people\n> contributing to Git\", whatever that means, can build the documentation\n> to check the part they're adding/modifying and not find it broken left\n> and right. They would then (quite rightly) not even bother building it.\n\nAgreed. But I think that is mostly the case (asciidoctor seems no harder\nto acquire on most modern systems than asciidoc; there are system\npackages in most cases, and decent binary-package systems for both ruby\nand python if you really need it).\n\nIt does create a situation where people like Randall on NonStop might\nneed to do part of their dev work on another, more mainstream platform.\nBut I suspect that is already the case.\n\n> When we looked at xmlto-less rendering around two years ago [1], we\n> found various asciidoctor bugs up to and around version 2.0. We would\n> likely need to require some >=2.0.x. The exact requirements will\n> probably only become clear when someone really does the work.\n\nThat does make things a little less convenient; Debian stable, for\ninstance, still has 1.5.8. It's not too hard to install an updated gem,\nbut not quite as nice as using the system package (it also makes things\nweird for building the stable Debian package itself, which would want to\nrely only on other packages; but of course any proposed change to the\ndoc toolchain would be for new versions, and would not get backported\nthere anyway).\n\n> I think what I'm arguing for is\n> \n> 1) switch the default to asciidoctor,\n> 2) enable optionally using it without xmlto,\n> 3) figure out what broke and fix it, and document which is the minimum\n> asciidoctor version we're going to bother with for (2),\n> 4) lather, rinse, repeat (3),\n> 5) switch the default to not using xmlto,\n> 6) drop the xmlto way of generating the manpages(?).\n\nI'm unclear when support for python asciidoc goes away here. Is it part\nof step 6 (because it does not have another way of generating them)? Or\ndoes it live on forever as a non-default legacy system? I'd prefer not,\nbut as long as we are clear about the primary target and leave it up to\npeople interested in the legacy to do the compat fixes, that might be\nOK.\n\n-Peff\n"},{"id":"424098","messageId":"609a07ca6a51c_5afe12088b@natae.notmuch","threadId":"55640","inReplyTo":"YJmykGWaWi03+WoW@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-11T04:27:54Z","receivedAt":"2021-05-11T04:28:03Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Sun, May 09, 2021 at 10:20:37AM +0200, Martin Ågren wrote:\n> > In general, I agree. I do think it's important that \"most people\n> > contributing to Git\", whatever that means, can build the documentation\n> > to check the part they're adding/modifying and not find it broken left\n> > and right. They would then (quite rightly) not even bother building it.\n> \n> Agreed. But I think that is mostly the case (asciidoctor seems no harder\n> to acquire on most modern systems than asciidoc; there are system\n> packages in most cases, and decent binary-package systems for both ruby\n> and python if you really need it).\n> \n> It does create a situation where people like Randall on NonStop might\n> need to do part of their dev work on another, more mainstream platform.\n> But I suspect that is already the case.\n\nOr use distributed tarballs with already built documentation.\n\nI don't see any big issue with cross-compilation though.\n\n> > When we looked at xmlto-less rendering around two years ago [1], we\n> > found various asciidoctor bugs up to and around version 2.0. We would\n> > likely need to require some >=2.0.x. The exact requirements will\n> > probably only become clear when someone really does the work.\n> \n> That does make things a little less convenient; Debian stable, for\n> instance, still has 1.5.8.\n\nAnd it has git 2.20.1, released at the end of 2018.\n\nI've never understood developers worried about how the bleeding edge\nwould build in ancient platforms, when ancient platforms don't care\nabout the bleeding edge.\n\n> It's not too hard to install an updated gem, but not quite as nice as\n> using the system package (it also makes things weird for building the\n> stable Debian package itself, which would want to rely only on other\n> packages; but of course any proposed change to the doc toolchain would\n> be for new versions, and would not get backported there anyway).\n\nAnyone trying to build git master on top of Debian stable 1. probably\ncan live with the output of the current doc toolchain, and 2. probably\ndoesn't exist.\n\nI'm not sure how much the git project gains by worrying about such\na hypothetical person.\n\n> > I think what I'm arguing for is\n> > \n> > 1) switch the default to asciidoctor,\n> > 2) enable optionally using it without xmlto,\n> > 3) figure out what broke and fix it, and document which is the minimum\n> > asciidoctor version we're going to bother with for (2),\n> > 4) lather, rinse, repeat (3),\n> > 5) switch the default to not using xmlto,\n> > 6) drop the xmlto way of generating the manpages(?).\n> \n> I'm unclear when support for python asciidoc goes away here. Is it part\n> of step 6 (because it does not have another way of generating them)? Or\n> does it live on forever as a non-default legacy system? I'd prefer not,\n> but as long as we are clear about the primary target and leave it up to\n> people interested in the legacy to do the compat fixes, that might be\n> OK.\n\nHow about we leave the legacy system in place as an alternative, and\ndecide later what to do with it?\n\n-- \nFelipe Contreras"},{"id":"424108","messageId":"YJogn8cUtSP/BAbJ@coredump.intra.peff.net","threadId":"55640","inReplyTo":"609a07ca6a51c_5afe12088b@natae.notmuch","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-11T06:13:51Z","receivedAt":"2021-05-11T06:13:53Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, May 10, 2021 at 11:27:54PM -0500, Felipe Contreras wrote:\n\n> Jeff King wrote:\n> > On Sun, May 09, 2021 at 10:20:37AM +0200, Martin Ågren wrote:\n> > > In general, I agree. I do think it's important that \"most people\n> > > contributing to Git\", whatever that means, can build the documentation\n> > > to check the part they're adding/modifying and not find it broken left\n> > > and right. They would then (quite rightly) not even bother building it.\n> > \n> > Agreed. But I think that is mostly the case (asciidoctor seems no harder\n> > to acquire on most modern systems than asciidoc; there are system\n> > packages in most cases, and decent binary-package systems for both ruby\n> > and python if you really need it).\n> > \n> > It does create a situation where people like Randall on NonStop might\n> > need to do part of their dev work on another, more mainstream platform.\n> > But I suspect that is already the case.\n> \n> Or use distributed tarballs with already built documentation.\n\nFor users, yes. But the context above is about people who are\ncontributing to Git, and writing their own new documentation. Presumably\nthey'd like to build it to see the output.\n\n> > That does make things a little less convenient; Debian stable, for\n> > instance, still has 1.5.8.\n> \n> And it has git 2.20.1, released at the end of 2018.\n> \n> I've never understood developers worried about how the bleeding edge\n> would build in ancient platforms, when ancient platforms don't care\n> about the bleeding edge.\n\nAgain, this is about developers. Are there people contributing new\ndocumentation to Git who are doing so on Debian stable, and would be\ninconvenienced by needing to upgrade their toolchain?\n\n> > > I think what I'm arguing for is\n> > > \n> > > 1) switch the default to asciidoctor,\n> > > 2) enable optionally using it without xmlto,\n> > > 3) figure out what broke and fix it, and document which is the minimum\n> > > asciidoctor version we're going to bother with for (2),\n> > > 4) lather, rinse, repeat (3),\n> > > 5) switch the default to not using xmlto,\n> > > 6) drop the xmlto way of generating the manpages(?).\n> > \n> > I'm unclear when support for python asciidoc goes away here. Is it part\n> > of step 6 (because it does not have another way of generating them)? Or\n> > does it live on forever as a non-default legacy system? I'd prefer not,\n> > but as long as we are clear about the primary target and leave it up to\n> > people interested in the legacy to do the compat fixes, that might be\n> > OK.\n> \n> How about we leave the legacy system in place as an alternative, and\n> decide later what to do with it?\n\nThat's what I was asking.\n\nLeaving it forever does mean supporting xmlto forever, which complicates\nthe Makefile (and that support will bitrot if people are not actually\nbuilding it).\n\n-Peff\n"},{"id":"424117","messageId":"609a3a5a7aa08_5d5d32088@natae.notmuch","threadId":"55640","inReplyTo":"YJogn8cUtSP/BAbJ@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-11T08:03:38Z","receivedAt":"2021-05-11T08:03:43Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Mon, May 10, 2021 at 11:27:54PM -0500, Felipe Contreras wrote:\n> > Jeff King wrote:\n> > > It does create a situation where people like Randall on NonStop might\n> > > need to do part of their dev work on another, more mainstream platform.\n> > > But I suspect that is already the case.\n> > \n> > Or use distributed tarballs with already built documentation.\n> \n> For users, yes. But the context above is about people who are\n> contributing to Git, and writing their own new documentation. Presumably\n> they'd like to build it to see the output.\n\nI'm a developer, I've added 261 lines and removed 212 lines to the\ndocumentation, and I've very rarely built it. Why? Because it takes too\nlong.\n\nBut you were talking about Randall, who I don't know what his role is,\nbut my bet is that he is a packager. It's not the same thing. Randall\nhas contributed only one patch to the Documentation, and it was to\ninstall pre-formatted documentation. Precisely what I thought he would be\ninterested in.\n\nIn fact, the bulk of his contribution was to install-doc-quick.sh, which\nneeds git-htmldocs and git-manpages. Two repositories I didn't even know\nexisted. So that's yet another option for him.\n\nOf course Randall can say if he sees himself as a developer.\n\n> > > That does make things a little less convenient; Debian stable, for\n> > > instance, still has 1.5.8.\n> > \n> > And it has git 2.20.1, released at the end of 2018.\n> > \n> > I've never understood developers worried about how the bleeding edge\n> > would build in ancient platforms, when ancient platforms don't care\n> > about the bleeding edge.\n> \n> Again, this is about developers. Are there people contributing new\n> documentation to Git who are doing so on Debian stable, and would be\n> inconvenienced by needing to upgrade their toolchain?\n\nDevelopers don't need to create (or use) debian packages. They can\nsimply do `gem install asciidoctor` and be done with it. Some may even\ncreate a docker container to install all the doc toolchain in order to\navoid polluting their main environment.\n\nI for one would start building the documentation more if all I needed is\none dependency.\n\n> > > I'm unclear when support for python asciidoc goes away here. Is it part\n> > > of step 6 (because it does not have another way of generating them)? Or\n> > > does it live on forever as a non-default legacy system? I'd prefer not,\n> > > but as long as we are clear about the primary target and leave it up to\n> > > people interested in the legacy to do the compat fixes, that might be\n> > > OK.\n> > \n> > How about we leave the legacy system in place as an alternative, and\n> > decide later what to do with it?\n> \n> That's what I was asking.\n> \n> Leaving it forever does mean supporting xmlto forever, which complicates\n> the Makefile (and that support will bitrot if people are not actually\n> building it).\n\nIndeed. If and when it's clear the xmlto part has bitrotten, and\npeople are happy with the asciidoc toolchain and output, then it can be\nobsoleted.\n\nThat would be my vote (I don't think there will be a strong need to main\nthe xmlto parts).\n\nIt doesn't need to be decided today though.\n\n-- \nFelipe Contreras\n"},{"id":"424118","messageId":"0fd3182c-3805-ee1b-5a35-e0c9a67892ab@gmail.com","threadId":"55640","inReplyTo":"CAN0heSpN_ieGc2HJCvSsmUuEqS-GGPDcZHz=v2Z3hJY=Or_HMw@mail.gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jean-Noël Avila","fromEmail":"avila.jn@gmail.com","sentAt":"2021-05-11T09:04:50Z","receivedAt":"2021-05-11T09:04:58Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On 09/05/2021 at 10:20, Martin Ågren wrote :\n>\n> I tend to think asciidoctor even renders our manpages *better* than\n> asciidoc does. Not by a huge margin, but a few things here and there.\n> Some time around the Python 2 EOL, I was about to propose flipping the\n> default, but then I went to look up the asciidoc EOL schedule, and like\n> you, I noticed that it was a lot more alive and kicking than I thought\n> it was. So it's not so much \"we should flip to avoid a bitrotting\n> dependency\" as it is \"asciidoctor is arguably nicer\" or \"it's the way\n> forward\".\n\nIf we start to change the documentation format to \"the way  forward\", we\nmay soon end up with a format which is no longer handled by the legacy\nasciidoc.py\n\nAs stated on https://github.com/asciidoc-py/asciidoc-py :\n\n\"AsciiDoc.py is a legacy processor for this syntax, handling an older\nrendition of AsciiDoc. As such, this will not properly handle the\ncurrent AsciiDoc specification. It is suggested that unless you\nspecifically require the AsciiDoc.py toolchain, you should find a\nprocessor that handles the modern AsciiDoc syntax.\"\n\n\nSo, as soon as the asciidoc format formal specification will gain\ntraction in the public, we can expect asciidoc to be abandoned for new\nprojects and receive minimal maintenance only for compatibility with\nlegacy documentation.\n\nOne argument in favor of Asciidoctor is that it's delivered \"with\nbatteries\", meaning that you can generate manpages, html and even pdf\nwith the same tool, without requiring secondary or even tertiary\ntoolchains, which should ease usage on a broader range of platforms.\n\nFWIW, we are already using Asciidoctor for publishing the manpages to\nhttps://git-scm.com\n\nJN\n\n\n"},{"id":"424125","messageId":"877dk5tovj.fsf@evledraar.gmail.com","threadId":"55640","inReplyTo":"609a3a5a7aa08_5d5d32088@natae.notmuch","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-05-11T12:44:41Z","receivedAt":"2021-05-11T12:51:35Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Tue, May 11 2021, Felipe Contreras wrote:\n\n> Jeff King wrote:\n>> On Mon, May 10, 2021 at 11:27:54PM -0500, Felipe Contreras wrote:\n>> > Jeff King wrote:\n>> [...]\n>> > I've never understood developers worried about how the bleeding edge\n>> > would build in ancient platforms, when ancient platforms don't care\n>> > about the bleeding edge.\n>> \n>> Again, this is about developers. Are there people contributing new\n>> documentation to Git who are doing so on Debian stable, and would be\n>> inconvenienced by needing to upgrade their toolchain?\n>\n> Developers don't need to create (or use) debian packages. They can\n> simply do `gem install asciidoctor` and be done with it. Some may even\n> create a docker container to install all the doc toolchain in order to\n> avoid polluting their main environment.\n>\n> I for one would start building the documentation more if all I needed is\n> one dependency.\n\nJust because I'm developing the latest git.git revision on Debian stable\nthat doesn't mean that I'm keen to install the very latest openssl,\nlibcurl, asciidoc, C compiler, or whatever other thing we depend on.\n\nI'm not disagreeing with bumping the dependency in this case (I haven't\nlooked into it). I'm just pointing out that in general there's a lot of\nuse-cases for e.g. building a latest git on an N year old OS.\n\nOf course we can ask these people to just build their dependencies too,\nas I noted in [1] in a past discussion. Whether we bump our required\ndependencies is a trade-off between our own convenience and these sorts\nof in-the-wild builds.\n\nI'm just saying we should keep this use-case in mind, it's not an all or\nnothing where you either have ancient deps + ancient git or bleeding\nedge deps + bleeding edge git. A lot of people build ancient deps +\nbleeding edge git.\n\nThe \"just use the built doc tarballs\" is only a partial solution, and\ne.g. won't work for someone who's interested in building \"next\" or\notherwise applying local patches that have doc changes.\n\n1. https://lore.kernel.org/git/874ltg2tvo.fsf@gmail.com/\n"},{"id":"424170","messageId":"CAN0heSp6uw7yqNZLD5w13xJUgnUtgHM0OYw9KQ6Z-FKk+x4OPA@mail.gmail.com","threadId":"55640","inReplyTo":"YJmykGWaWi03+WoW@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-11T18:45:10Z","receivedAt":"2021-05-11T18:45:28Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 11 May 2021 at 00:24, Jeff King wrote:\n>\n> On Sun, May 09, 2021 at 10:20:37AM +0200, Martin Ågren wrote:\n>\n> > it was. So it's not so much \"we should flip to avoid a bitrotting\n> > dependency\" as it is \"asciidoctor is arguably nicer\" or \"it's the way\n> > forward\".\n>\n> I'm OK with those arguments, too. :)\n\nExcellent. :)\n\n> > When we looked at xmlto-less rendering around two years ago [1], we\n> > found various asciidoctor bugs up to and around version 2.0. We would\n> > likely need to require some >=2.0.x. The exact requirements will\n> > probably only become clear when someone really does the work.\n>\n> That does make things a little less convenient; Debian stable, for\n> instance, still has 1.5.8. It's not too hard to install an updated gem,\n> but not quite as nice as using the system package (it also makes things\n> weird for building the stable Debian package itself, which would want to\n> rely only on other packages; but of course any proposed change to the\n> doc toolchain would be for new versions, and would not get backported\n> there anyway).\n\nRight. And 1.5.8 is perfectly fine for ascidoctor *with* xmlto, i.e., as\nlong as we're discussing moving away from asciidoc, not moving away from\nxmlto entirely. And soon enough, Debian stable should be at 2.12. ;-)\n(I realize Debian stable was just an example.)\n\n> > I think what I'm arguing for is\n> >\n> > 1) switch the default to asciidoctor,\n> > 2) enable optionally using it without xmlto,\n> > 3) figure out what broke and fix it, and document which is the minimum\n> > asciidoctor version we're going to bother with for (2),\n> > 4) lather, rinse, repeat (3),\n> > 5) switch the default to not using xmlto,\n> > 6) drop the xmlto way of generating the manpages(?).\n>\n> I'm unclear when support for python asciidoc goes away here. Is it part\n> of step 6 (because it does not have another way of generating them)? Or\n> does it live on forever as a non-default legacy system? I'd prefer not,\n> but as long as we are clear about the primary target and leave it up to\n> people interested in the legacy to do the compat fixes, that might be\n> OK.\n\nI think I meant it to happen somewhere in step 3 or 4, I just didn't\ncall it out. If it happens super-early in step 3, that would perhaps be\na bit unfortunate. But if fixing up the last few bits of\nxmlto-vs-no-xmlto with asciidoctor involves giving up on asciidoc, then\nso be it... If nothing else, we might all of a sudden find that our\nasciidoc-processed docs look awful and that nobody seems to have\nnoticed.\n\nMartin\n"},{"id":"424172","messageId":"CAN0heSpNhfmsVO5rME1xZzPPbkCuDm0ng64xWNx4xy+8ZrVz+Q@mail.gmail.com","threadId":"55640","inReplyTo":"0fd3182c-3805-ee1b-5a35-e0c9a67892ab@gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-11T18:54:33Z","receivedAt":"2021-05-11T18:54:51Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 11 May 2021 at 11:04, Jean-Noël Avila wrote:\n>\n> On 09/05/2021 at 10:20, Martin Ågren wrote :\n> >\n> > I tend to think asciidoctor even renders our manpages *better* than\n> > asciidoc does. Not by a huge margin, but a few things here and there.\n> > Some time around the Python 2 EOL, I was about to propose flipping the\n> > default, but then I went to look up the asciidoc EOL schedule, and like\n> > you, I noticed that it was a lot more alive and kicking than I thought\n> > it was. So it's not so much \"we should flip to avoid a bitrotting\n> > dependency\" as it is \"asciidoctor is arguably nicer\" or \"it's the way\n> > forward\".\n>\n> If we start to change the documentation format to \"the way forward\", we\n> may soon end up with a format which is no longer handled by the legacy\n> asciidoc.py\n\nWe used to be in a situation where Asciidoctor looked worse and the\nrendered versions were quite different. We've fixed up quite a few\ndiscrepancies by making some change that \"happens\" to be a noop with one\nengine but an improvement with the other. (That it just \"happens\" has\nsometimes been my feeling anyway.) Sometimes, we've been able to improve\nboth by spotting a difference, so that's good.\n\nI would also expect that with more eyes on asciidoctor-built docs\n(because default) and fewer on the other, the non-default will start to\ndegrade.\n\n> As stated on https://github.com/asciidoc-py/asciidoc-py :\n>\n> \"AsciiDoc.py is a legacy processor for this syntax, handling an older\n> rendition of AsciiDoc. As such, this will not properly handle the\n> current AsciiDoc specification. It is suggested that unless you\n> specifically require the AsciiDoc.py toolchain, you should find a\n> processor that handles the modern AsciiDoc syntax.\"\n\nThanks for that quote. It's very enlightening.\n\n> FWIW, we are already using Asciidoctor for publishing the manpages to\n> https://git-scm.com\n\nThank you for all your work on that site!\n\nMartin\n"},{"id":"424175","messageId":"609ad46776dec_6011e208d7@natae.notmuch","threadId":"55640","inReplyTo":"877dk5tovj.fsf@evledraar.gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-11T19:00:55Z","receivedAt":"2021-05-11T19:01:02Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n> On Tue, May 11 2021, Felipe Contreras wrote:\n> \n> > Jeff King wrote:\n> >> On Mon, May 10, 2021 at 11:27:54PM -0500, Felipe Contreras wrote:\n> >> > Jeff King wrote:\n> >> [...]\n> >> > I've never understood developers worried about how the bleeding edge\n> >> > would build in ancient platforms, when ancient platforms don't care\n> >> > about the bleeding edge.\n> >> \n> >> Again, this is about developers. Are there people contributing new\n> >> documentation to Git who are doing so on Debian stable, and would be\n> >> inconvenienced by needing to upgrade their toolchain?\n> >\n> > Developers don't need to create (or use) debian packages. They can\n> > simply do `gem install asciidoctor` and be done with it. Some may even\n> > create a docker container to install all the doc toolchain in order to\n> > avoid polluting their main environment.\n> >\n> > I for one would start building the documentation more if all I needed is\n> > one dependency.\n> \n> Just because I'm developing the latest git.git revision on Debian stable\n> that doesn't mean that I'm keen to install the very latest openssl,\n> libcurl, asciidoc, C compiler, or whatever other thing we depend on.\n> \n> I'm not disagreeing with bumping the dependency in this case (I haven't\n> looked into it). I'm just pointing out that in general there's a lot of\n> use-cases for e.g. building a latest git on an N year old OS.\n\nI'm not disagreeing with that. The reason I mentioned it is what Jeff\nsaid next:\n\n> > > It's not too hard to install an updated gem, but not quite as nice\n> > > as using the system package (it also makes things weird for\n> > > building the stable Debian package itself, which would want to\n> > > rely only on other packages; but of course any proposed change to\n> > > the doc toolchain would be for new versions, and would not get\n> > > backported there anyway).\n\nDoing `gem install` solves the problem for whomever wants to build the\nlatest git in Debian stable.\n\nBuilding Debian stable packages is something else.\n\n> Of course we can ask these people to just build their dependencies too,\n> as I noted in [1] in a past discussion. Whether we bump our required\n> dependencies is a trade-off between our own convenience and these sorts\n> of in-the-wild builds.\n> \n> I'm just saying we should keep this use-case in mind, it's not an all or\n> nothing where you either have ancient deps + ancient git or bleeding\n> edge deps + bleeding edge git. A lot of people build ancient deps +\n> bleeding edge git.\n\nBut what is \"this\"?\n\n 1) Building the latest documentation in Debian stable\n 2) Packaging the latest git in Debian stable\n\nIf it's 1) then there's no problem: `gem install` does the trick, and in\nfact in their CI builds [1] they test with versions of Ruby as old as\n2.3, and Debian stable ships with 2.5.\n\nI test my own Ruby code with versions of Ruby as old as 2.0 and there's\nrarely any issue. What works with Ruby 2.3 works with Ruby 2.0. Ruby is\nnot like python (where 3.0 is completely different from 2.0).\n\nIf it's 2) then that's where I say: who cares?\n\n> The \"just use the built doc tarballs\" is only a partial solution, and\n> e.g. won't work for someone who's interested in building \"next\" or\n> otherwise applying local patches that have doc changes.\n\nRight, but \"just use the built doc tarballs\" is not the suggestion for\npeople trying to do 1).\n\nCheers.\n\n[1] https://github.com/asciidoctor/asciidoctor/actions/runs/830132862\n\n-- \nFelipe Contreras"},{"id":"424179","messageId":"YJrV52HOv0mlbJB1@coredump.intra.peff.net","threadId":"55640","inReplyTo":"CAN0heSp6uw7yqNZLD5w13xJUgnUtgHM0OYw9KQ6Z-FKk+x4OPA@mail.gmail.com","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-11T19:07:19Z","receivedAt":"2021-05-11T19:07:32Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 11, 2021 at 08:45:10PM +0200, Martin Ågren wrote:\n\n> > That does make things a little less convenient; Debian stable, for\n> > instance, still has 1.5.8. It's not too hard to install an updated gem,\n> > but not quite as nice as using the system package (it also makes things\n> > weird for building the stable Debian package itself, which would want to\n> > rely only on other packages; but of course any proposed change to the\n> > doc toolchain would be for new versions, and would not get backported\n> > there anyway).\n> \n> Right. And 1.5.8 is perfectly fine for ascidoctor *with* xmlto, i.e., as\n> long as we're discussing moving away from asciidoc, not moving away from\n> xmlto entirely. And soon enough, Debian stable should be at 2.12. ;-)\n> (I realize Debian stable was just an example.)\n\nDebian stable is just an example, but I also consider it a bit of a\nbenchmark for \"reasonable\". Surely there are people running RHEL6\nsomewhere in this world, but it's hard to care too much about them.\n\nI think the transition you're proposing would probably take a while to\ndo, too. If we don't drop the python asciidoc support until close to the\nend, then that buys a bit more time. Likewise, this isn't a hard limit\nfor OS support for users. The worst case is just making things slightly\nmore inconvenient for Git developers on older systems, because because\nthey might have to install an updated gem rather than using the system\npackage (you sometimes can end up in dependency hell for a gem upgrade\nwith versions of ruby, system libraries, etc, but I haven't found\nasciidoctor particularly needy in that respect).\n\nSo I dunno. I certainly don't have a big complaint about _starting_ the\ntransition. If we can hold on to python asciidoc support (or even\nold-asciidoctor + xmlto) for a while as a fallback, even if we know it's\nslowly bitrotting, then it's possible nobody would even complain.\n\n-Peff\n"},{"id":"424180","messageId":"YJrWXfmaNVIL/TzT@coredump.intra.peff.net","threadId":"55640","inReplyTo":"609ad46776dec_6011e208d7@natae.notmuch","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-05-11T19:09:17Z","receivedAt":"2021-05-11T19:09:20Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 11, 2021 at 02:00:55PM -0500, Felipe Contreras wrote:\n\n> > > > It's not too hard to install an updated gem, but not quite as nice\n> > > > as using the system package (it also makes things weird for\n> > > > building the stable Debian package itself, which would want to\n> > > > rely only on other packages; but of course any proposed change to\n> > > > the doc toolchain would be for new versions, and would not get\n> > > > backported there anyway).\n> \n> Doing `gem install` solves the problem for whomever wants to build the\n> latest git in Debian stable.\n> \n> Building Debian stable packages is something else.\n\nPerhaps I wasn't clear with the \"but of course\" part of my statement. It\nwas meant to rebut the earlier half of the parenthetical. I.e., drawing\nthat same distinction as \"we don't have to worry about packaging Debian\nstable here\".\n\n-Peff\n"},{"id":"424182","messageId":"CAN0heSpTPb_3h_Bn6Tboqvg_hW2bT184Z34pfQXg0q_u+JgDXQ@mail.gmail.com","threadId":"55640","inReplyTo":"YJrV52HOv0mlbJB1@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-11T19:11:59Z","receivedAt":"2021-05-11T19:12:17Z","isPatch":false,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 11 May 2021 at 21:07, Jeff King wrote:\n>\n> So I dunno. I certainly don't have a big complaint about _starting_ the\n> transition. If we can hold on to python asciidoc support (or even\n> old-asciidoctor + xmlto) for a while as a fallback, even if we know it's\n> slowly bitrotting, then it's possible nobody would even complain.\n\nYou made several good points; I just quoted the last few here. Thanks\nfor your thoughts on this.\n\nMartin\n"},{"id":"424193","messageId":"609ae59dc3f0c_60649208b8@natae.notmuch","threadId":"55640","inReplyTo":"YJrV52HOv0mlbJB1@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-11T20:14:21Z","receivedAt":"2021-05-11T20:14:26Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> The worst case is just making things slightly more inconvenient for\n> Git developers on older systems, because because they might have to\n> install an updated gem rather than using the system package (you\n> sometimes can end up in dependency hell for a gem upgrade with\n> versions of ruby, system libraries, etc, but I haven't found\n> asciidoctor particularly needy in that respect).\n\nThe asciidoctor gem has *zero* dependencies. If you end up in a\ndependency hell, it wasn't the fault of asciidoctor, and it won't be\naffected.\n\nI've been using Ruby for at least 15 years, and I've never found myself\nin a dependency hell, so it would be interesting to see how anybody\ncould end up there. Sometimes the mix between system and user gems is\nconfusing, but they work fine. I wouldn't call that a \"dependency hell\".\n\nAnd of course you can always just `rm -r $GEM_HOME` and start fresh.\nMost gems install rather quickly.\n\n-- \nFelipe Contreras\n"},{"id":"424194","messageId":"609ae77fc684e_6064920816@natae.notmuch","threadId":"55640","inReplyTo":"YJrWXfmaNVIL/TzT@coredump.intra.peff.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-11T20:22:23Z","receivedAt":"2021-05-11T20:22:28Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Tue, May 11, 2021 at 02:00:55PM -0500, Felipe Contreras wrote:\n> \n> > > > > It's not too hard to install an updated gem, but not quite as nice\n> > > > > as using the system package (it also makes things weird for\n> > > > > building the stable Debian package itself, which would want to\n> > > > > rely only on other packages; but of course any proposed change to\n> > > > > the doc toolchain would be for new versions, and would not get\n> > > > > backported there anyway).\n> > \n> > Doing `gem install` solves the problem for whomever wants to build the\n> > latest git in Debian stable.\n> > \n> > Building Debian stable packages is something else.\n> \n> Perhaps I wasn't clear with the \"but of course\" part of my statement. It\n> was meant to rebut the earlier half of the parenthetical. I.e., drawing\n> that same distinction as \"we don't have to worry about packaging Debian\n> stable here\".\n\nAh, I undesrstood wrong there, it seems we are in agreement.\n\nSemicolons in English are similar to semicolons in computer languages:\nwhen I read ($a; $b), $a needs to stand on its own. If $b is really\nimportant I would do ($a, but $b). But this is like splitting hairs of\nsplitted hairs.\n\nI've seen too much discussion and too few patches, I'll send the mockup\nI did a few days ago to see if it sticks.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424223","messageId":"YJsPuU5eLO8TkY2L@camp.crustytoothpaste.net","threadId":"55640","inReplyTo":"609a07ca6a51c_5afe12088b@natae.notmuch","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-05-11T23:14:01Z","receivedAt":"2021-05-11T23:14:15Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-05-11 at 04:27:54, Felipe Contreras wrote:\n> I've never understood developers worried about how the bleeding edge\n> would build in ancient platforms, when ancient platforms don't care\n> about the bleeding edge.\n\nDebian stable is a common environment to do development on. I know\npeople who do use it for Git development, so I suspect we'll want to\ncontinue to support it. In fact, most of my colleagues who use a Debian\nsystem for development use Debian stable, I'd say.\n\nMoreover, in some cases, the distros one can use for development are\nrestricted due to requirements for software that runs on corporate\nmachines, so making things work nicely on the latest stable versions of\nDebian and Ubuntu is generally kind.\n\nYes, people _can_ run \"gem install asciidoctor\", but people who are not\nRuby developers generally would prefer a distro package over installing\none-off gems, especially since getting the binaries into PATH is tricky\nwith gem.\n\n> > It's not too hard to install an updated gem, but not quite as nice as\n> > using the system package (it also makes things weird for building the\n> > stable Debian package itself, which would want to rely only on other\n> > packages; but of course any proposed change to the doc toolchain would\n> > be for new versions, and would not get backported there anyway).\n> \n> Anyone trying to build git master on top of Debian stable 1. probably\n> can live with the output of the current doc toolchain, and 2. probably\n> doesn't exist.\n\nI believe I have just demonstrated that 2 is false above.\n\n> > > I think what I'm arguing for is\n> > > \n> > > 1) switch the default to asciidoctor,\n> > > 2) enable optionally using it without xmlto,\n> > > 3) figure out what broke and fix it, and document which is the minimum\n> > > asciidoctor version we're going to bother with for (2),\n> > > 4) lather, rinse, repeat (3),\n> > > 5) switch the default to not using xmlto,\n> > > 6) drop the xmlto way of generating the manpages(?).\n> > \n> > I'm unclear when support for python asciidoc goes away here. Is it part\n> > of step 6 (because it does not have another way of generating them)? Or\n> > does it live on forever as a non-default legacy system? I'd prefer not,\n> > but as long as we are clear about the primary target and leave it up to\n> > people interested in the legacy to do the compat fixes, that might be\n> > OK.\n> \n> How about we leave the legacy system in place as an alternative, and\n> decide later what to do with it?\n\nI think it would be fine to just leave it in place for now and let\npeople decide which toolchain they'd like to use.\n-- \nbrian m. carlson (he/him or they/them)\nHouston, Texas, US\n"},{"id":"424247","messageId":"609b330873c0a_678ff20833@natae.notmuch","threadId":"55640","inReplyTo":"YJsPuU5eLO8TkY2L@camp.crustytoothpaste.net","subject":"Re: [RFC suggestion] Generate manpage directly with Asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T01:44:40Z","receivedAt":"2021-05-12T01:44:44Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"brian m. carlson wrote:\n> On 2021-05-11 at 04:27:54, Felipe Contreras wrote:\n> > I've never understood developers worried about how the bleeding edge\n> > would build in ancient platforms, when ancient platforms don't care\n> > about the bleeding edge.\n> \n> Debian stable is a common environment to do development on. I know\n> people who do use it for Git development, so I suspect we'll want to\n> continue to support it.\n\nI didn't mean to suggest otherwise.\n\n> Yes, people _can_ run \"gem install asciidoctor\", but people who are not\n> Ruby developers generally would prefer a distro package over installing\n> one-off gems, especially since getting the binaries into PATH is tricky\n> with gem.\n\nYes, but there's only so much we can hold hands with our users.\n\nIf a user:\n\n 1. Uses an acient distribution\n 2. Wants to build the documentation\n 3. Enables USE_ASCIIDOCTOR\n 4. Doesn't know Ruby\n 5. Wants to use distribution packages\n 6. Is bothered by the output\n\nI think it's valid for the project to say \"you are on your own\". In\nfact, not really that because if they contact the mailing list we would\nhelp them.\n\nThe only thing we could do is print a warning if they try to build with\nversions of asciidoctor that we know are problematic.\n\nThat being said; it's not \"tricky\" to get binaries into your PATH:\n\n export PATH=\"$GEM_HOME/bin:$PATH\"\n\nAnd you don't need to get gem binaries into your PATH:\n\n export GEM_HOME=/tmp/gems\n gem install asciidoctor\n make USE_ASCIIDOCTOR=YesPlease ASCIIDOC=$GEM_HOME/bin/asciidoctor doc\n\nWorks just fine without modifying PATH.\n\n> > > It's not too hard to install an updated gem, but not quite as nice as\n> > > using the system package (it also makes things weird for building the\n> > > stable Debian package itself, which would want to rely only on other\n> > > packages; but of course any proposed change to the doc toolchain would\n> > > be for new versions, and would not get backported there anyway).\n> > \n> > Anyone trying to build git master on top of Debian stable 1. probably\n> > can live with the output of the current doc toolchain, and 2. probably\n> > doesn't exist.\n> \n> I believe I have just demonstrated that 2 is false above.\n\nI meant trying to build the documentation of git on git master.\n\n> > > > I think what I'm arguing for is\n> > > > \n> > > > 1) switch the default to asciidoctor,\n> > > > 2) enable optionally using it without xmlto,\n> > > > 3) figure out what broke and fix it, and document which is the minimum\n> > > > asciidoctor version we're going to bother with for (2),\n> > > > 4) lather, rinse, repeat (3),\n> > > > 5) switch the default to not using xmlto,\n> > > > 6) drop the xmlto way of generating the manpages(?).\n> > > \n> > > I'm unclear when support for python asciidoc goes away here. Is it part\n> > > of step 6 (because it does not have another way of generating them)? Or\n> > > does it live on forever as a non-default legacy system? I'd prefer not,\n> > > but as long as we are clear about the primary target and leave it up to\n> > > people interested in the legacy to do the compat fixes, that might be\n> > > OK.\n> > \n> > How about we leave the legacy system in place as an alternative, and\n> > decide later what to do with it?\n> \n> I think it would be fine to just leave it in place for now and let\n> people decide which toolchain they'd like to use.\n\nAgreed.\n\n-- \nFelipe Contreras\n"}]}