{"thread":{"id":"55669","subject":"[PATCH] INSTALL: note about make man with Asciidoctor backend","startedAt":"2021-05-12T06:42:40Z","lastAt":"2021-06-02T20:08:39Z","messageCount":6,"participants":["Bagas Sanjaya","Junio C Hamano","Felipe Contreras","Martin Ågren"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"424289","messageId":"20210512064128.15411-1-bagasdotme@gmail.com","threadId":"55669","inReplyTo":null,"subject":"[PATCH] INSTALL: note about make man with Asciidoctor backend","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-12T06:41:29Z","receivedAt":"2021-05-12T06:42:40Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"\"make man\" can now be also done with Asciidoctor's manpage backend\ninstead of asciidoc+xmlto.\n\nUpdate INSTALL to reflect that.\n\nSigned-off-by: Bagas Sanjaya \n---\n\n This patch is based on \"doc: add an option to have Asciidoctor build\n man pages directly\" series by brian m. carlson [1]. It can be added\n to that series.\n\n [1]:\nhttps://lore.kernel.org/git/20210512021138.63598-1-sandals@crustytoothpaste.net/\n\n INSTALL | 10 ++++++++--\n 1 file changed, 8 insertions(+), 2 deletions(-)\n\ndiff --git a/INSTALL b/INSTALL\nindex 66389ce059..89e31566c3 100644\n--- a/INSTALL\n+++ b/INSTALL\n@@ -184,8 +184,9 @@ Issues of note:\n \n \"make doc\" builds documentation in man and html formats; there are\n also \"make man\", \"make html\" and \"make info\". Note that \"make html\"\n- requires asciidoc, but not xmlto. \"make man\" (and thus make doc)\n- requires both.\n+ requires asciidoc, but not xmlto. \"make man\" requires either\n+ Asciidoctor or asciidoc+xmlto. \"make doc\" requires both asciidoc\n+ and xmlto.\n \n \"make install-doc\" installs documentation in man format only; there\n are also \"make install-man\", \"make install-html\" and \"make\n@@ -201,6 +202,11 @@ Issues of note:\n use Asciidoctor (requires Ruby) by passing USE_ASCIIDOCTOR=YesPlease\n to make. You need at least Asciidoctor version 1.5.\n \n+ You can also do \"make man\" using Asciidoctor's manpage backend in\n+ place of xmlto by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease. Version\n+ 2.0 or later is highly recommended, as these version properly handle\n+ apostrophes.\n+\n There are also \"make quick-install-doc\", \"make quick-install-man\"\n and \"make quick-install-html\" which install preformatted man pages\n and html documentation. To use these build targets, you need to\n-- \n2.25.1\n\n"},{"id":"424294","messageId":"xmqqtun8fncl.fsf@gitster.g","threadId":"55669","inReplyTo":"20210512064128.15411-1-bagasdotme@gmail.com","subject":"Re: [PATCH] INSTALL: note about make man with Asciidoctor backend","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-12T07:00:26Z","receivedAt":"2021-05-12T07:00:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> \"make man\" can now be also done with Asciidoctor's manpage backend\n> instead of asciidoc+xmlto.\n>\n> Update INSTALL to reflect that.\n>\n> Signed-off-by: Bagas Sanjaya \n> ---\n>\n> This patch is based on \"doc: add an option to have Asciidoctor build\n> man pages directly\" series by brian m. carlson [1]. It can be added\n> to that series.\n\nIt's not like \"can be\"; it would not make any sense to queue this\npatch before queuing those two patches below it ;-)\n\nNot everybody with Asciidoctor can do the \"man\" without xmlto; they\nmust have recent enough vintage of Asciidoctor, or they need xmlto.\nThe second hunk makes it quite clear, but the updated text in the\nfirst hunk falls a bit short to convey that and needs a bit more\nwork to clarify, I would think.\n\n> diff --git a/INSTALL b/INSTALL\n> index 66389ce059..89e31566c3 100644\n> --- a/INSTALL\n> +++ b/INSTALL\n> @@ -184,8 +184,9 @@ Issues of note:\n> \n> \"make doc\" builds documentation in man and html formats; there are\n> also \"make man\", \"make html\" and \"make info\". Note that \"make html\"\n> - requires asciidoc, but not xmlto. \"make man\" (and thus make doc)\n> - requires both.\n> + requires asciidoc, but not xmlto. \"make man\" requires either\n> + Asciidoctor or asciidoc+xmlto. \"make doc\" requires both asciidoc\n> + and xmlto.\n\nAs \"make doc\" is \"make -C Documentaiton all\",\n \"make html\" is \"make -C Documentaiton html\",\n \"make man\" is \"make -C Documentaiton man\",\nand \n \"make -C Documentation all\" is \"make -C Documentation html man\"\n\nit seems that those who choose to go xmlto-less route for manpages\nshould not need xmlto while doing \"make doc\", so the last part of\nthe updated text is not quite accurate, no?\n\n> @@ -201,6 +202,11 @@ Issues of note:\n> use Asciidoctor (requires Ruby) by passing USE_ASCIIDOCTOR=YesPlease\n> to make. You need at least Asciidoctor version 1.5.\n> \n> + You can also do \"make man\" using Asciidoctor's manpage backend in\n> + place of xmlto by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease. Version\n> + 2.0 or later is highly recommended, as these version properly handle\n> + apostrophes.\n> +\n\nHmph, I wasn't closely following the previous discussion, but is the\napostrophes the primary reason why anything below 2.0 is not usable?\n\nI actually do not mind, for clarity and brevity's sake, to give\nreaders a bit of white lie and just say something along the lines of\n\n If you use Asciidoctor version 2.0 or later, you can choose to\n directly generate manpages with its manpage backend, instaed of\n using xmlto in between, by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease\n to \"make man\".\n\nto _require_ 2.0 without even hinting that earlier versions might be\nusable.\n\nIn any case, thanks for a good start.\n"},{"id":"424299","messageId":"609b8e214e1b6_6e4e92087e@natae.notmuch","threadId":"55669","inReplyTo":"xmqqtun8fncl.fsf@gitster.g","subject":"Re: [PATCH] INSTALL: note about make man with Asciidoctor backend","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-12T08:13:21Z","receivedAt":"2021-05-12T08:13:29Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Bagas Sanjaya writes:\n> \n> > \"make man\" can now be also done with Asciidoctor's manpage backend\n> > instead of asciidoc+xmlto.\n> >\n> > Update INSTALL to reflect that.\n> >\n> > Signed-off-by: Bagas Sanjaya \n> > ---\n> >\n> > This patch is based on \"doc: add an option to have Asciidoctor build\n> > man pages directly\" series by brian m. carlson [1]. It can be added\n> > to that series.\n> \n> It's not like \"can be\"; it would not make any sense to queue this\n> patch before queuing those two patches below it ;-)\n> \n> Not everybody with Asciidoctor can do the \"man\" without xmlto; they\n> must have recent enough vintage of Asciidoctor, or they need xmlto.\n\nThis is something yet to be determined (I will investigate).\n\nIt's likely that they *can* do `make man` without xmlto, but perhaps\nthey wouldn't have a perfect output (yet to be determined).\n\n> > @@ -201,6 +202,11 @@ Issues of note:\n> > use Asciidoctor (requires Ruby) by passing USE_ASCIIDOCTOR=YesPlease\n> > to make. You need at least Asciidoctor version 1.5.\n> > \n> > + You can also do \"make man\" using Asciidoctor's manpage backend in\n> > + place of xmlto by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease. Version\n> > + 2.0 or later is highly recommended, as these version properly handle\n> > + apostrophes.\n> > +\n> \n> Hmph, I wasn't closely following the previous discussion, but is the\n> apostrophes the primary reason why anything below 2.0 is not usable?\n\n\"Not usable\"?\n\nI haven't been able to reproduce the original supposed problem, but even\nif true, the man pages would be quite usable.\n\n(not beeing able to copy-paste chunks of code from a man page with\napostrophes can't be hardly considered \"unusable\").\n\n\nEither way, more work is needed to figure out what's going on.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"424472","messageId":"CAN0heSrNzxSpq=trPvOHAYx_yT1W=WuN1XstzTRjHdZko-i+DA@mail.gmail.com","threadId":"55669","inReplyTo":"609b8e214e1b6_6e4e92087e@natae.notmuch","subject":"Re: [PATCH] INSTALL: note about make man with Asciidoctor backend","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2021-05-13T13:41:11Z","receivedAt":"2021-05-13T13:41:35Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Wed, 12 May 2021 at 10:13, Felipe Contreras\n wrote:\n>\n> Junio C Hamano wrote:\n> > Bagas Sanjaya writes:\n> >\n> > > + You can also do \"make man\" using Asciidoctor's manpage backend in\n> > > + place of xmlto by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease. Version\n> > > + 2.0 or later is highly recommended, as these version properly handle\n> > > + apostrophes.\n> > > +\n> >\n> > Hmph, I wasn't closely following the previous discussion, but is the\n> > apostrophes the primary reason why anything below 2.0 is not usable?\n>\n> \"Not usable\"?\n>\n> I haven't been able to reproduce the original supposed problem, but even\n> if true, the man pages would be quite usable.\n\nEven early 2.0.x had some issues [1]. It's always debatable whether they're\nsignificant or not, i.e., is a significant speed-up worth it if the\nresult is just-as-informative-but-a-bit-ugly-here-and-there? We should\nprovide some rough background here to help people and distros decide.\nMaybe something like\n\n \"This can be quite a bit faster and requires fewer dependencies, but\n please note that this is early work: there are some typographical\n issues we know of, and there might be others.\"\n\nbut hopefully phrased better than that. I would suggest the commit\nmessage saying something like \"I skimmed through the doc-diff between\nthe asciidoctor-with-xmlto and asciidoctor-without-xmlto (using\nasciidoctor v2.x.y) -- there are quite many minor differences, but\nnothing particularly jarring stands out\".\n\n[1] https://lore.kernel.org/git/20190325190041.GM4047@pobox.com/\n\nMartin\n"},{"id":"424506","messageId":"xmqqwns29ydw.fsf@gitster.g","threadId":"55669","inReplyTo":"CAN0heSrNzxSpq=trPvOHAYx_yT1W=WuN1XstzTRjHdZko-i+DA@mail.gmail.com","subject":"Re: [PATCH] INSTALL: note about make man with Asciidoctor backend","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-13T20:23:07Z","receivedAt":"2021-05-13T20:23:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n>> > Bagas Sanjaya writes:\n>> >\n>> > > + You can also do \"make man\" using Asciidoctor's manpage backend in\n>> > > + place of xmlto by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease. Version\n>> > > + 2.0 or later is highly recommended, as these version properly handle\n>> > > + apostrophes.\n>> ...\n>\n> Even early 2.0.x had some issues [1]. It's always debatable whether they're\n> significant or not, i.e., is a significant speed-up worth it if the\n> result is just-as-informative-but-a-bit-ugly-here-and-there? We should\n> provide some rough background here to help people and distros decide.\n\nWhat does \"properly handle apostrophes\" refer to exactly? I got an\nimpression that it was the pretty-quoting that breaks cut-and-paste,\nwhich is a usability issue for manpages.\n\n> Maybe something like\n>\n> \"This can be quite a bit faster and requires fewer dependencies, but\n> please note that this is early work: there are some typographical\n> issues we know of, and there might be others.\"\n>\n> but hopefully phrased better than that.\n\nThat looks like a good starting point.\n\n"},{"id":"426255","messageId":"60b7e4fbc1e03_167521208cb@natae.notmuch","threadId":"55669","inReplyTo":"CAN0heSrNzxSpq=trPvOHAYx_yT1W=WuN1XstzTRjHdZko-i+DA@mail.gmail.com","subject":"Re: [PATCH] INSTALL: note about make man with Asciidoctor backend","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-02T20:07:23Z","receivedAt":"2021-06-02T20:08:39Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Martin Ågren wrote:\n> On Wed, 12 May 2021 at 10:13, Felipe Contreras\n> wrote:\n> >\n> > Junio C Hamano wrote:\n> > > Bagas Sanjaya writes:\n> > >\n> > > > + You can also do \"make man\" using Asciidoctor's manpage backend in\n> > > > + place of xmlto by passing USE_ASCIIDOCTOR_MANPAGE=YesPlease. Version\n> > > > + 2.0 or later is highly recommended, as these version properly handle\n> > > > + apostrophes.\n> > > > +\n> > >\n> > > Hmph, I wasn't closely following the previous discussion, but is the\n> > > apostrophes the primary reason why anything below 2.0 is not usable?\n> >\n> > \"Not usable\"?\n> >\n> > I haven't been able to reproduce the original supposed problem, but even\n> > if true, the man pages would be quite usable.\n> \n> Even early 2.0.x had some issues [1].\n> [1] https://lore.kernel.org/git/20190325190041.GM4047@pobox.com/\n\nThat issue affects only the docbook generation, not direct man pages.\n\nSo far nobody has mentioned any issues with USE_ASCIIDOCTOR_MANPAGE=1 in\nolder asciidoctor, especially not regarding apostrophes.\n\n-- \nFelipe Contreras"}]}