{"thread":{"id":"59462","subject":"[PATCH] doc: asciidoc: remove custom header macro","startedAt":"2023-03-23T22:15:30Z","lastAt":"2023-04-07T14:30:19Z","messageCount":8,"participants":["Felipe Contreras","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"474057","messageId":"20230323221523.52472-1-felipe.contreras@gmail.com","threadId":"59462","inReplyTo":null,"subject":"[PATCH] doc: asciidoc: remove custom header macro","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-03-23T22:15:23Z","receivedAt":"2023-03-23T22:15:30Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"In 2007 we added a custom header macro to provide version information\n7ef195ba3e (Documentation: Add version information to man pages,\n2007-03-25),\n\nHowever, in 2008 asciidoc added the attributes to do this properly [1].\n\nThis was not implemented in Git until 2019: 226daba280 (Doc/Makefile:\ngive mansource/-version/-manual attributes, 2019-09-16).\n\nBut in 2023 we are doing it properly, so there's no need for the custom\nmacro.\n\n[1] https://github.com/asciidoc-py/asciidoc-py/commit/ad78a3c\n\nCc: Martin Ågren \nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoc.conf | 19 -------------------\n 1 file changed, 19 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 3e4c13971b..60f76f43ed 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -51,25 +51,6 @@ ifdef::doctype-manpage[]\n endif::doctype-manpage[]\n endif::backend-docbook[]\n \n-ifdef::doctype-manpage[]\n-ifdef::backend-docbook[]\n-[header]\n-template::[header-declarations]\n-\n-\n-{mantitle}\n-{manvolnum}\n-{mansource}\n-{manversion}\n-{manmanual}\n-\n-\n- {manname}\n- {manpurpose}\n-\n-endif::backend-docbook[]\n-endif::doctype-manpage[]\n-\n ifdef::backend-xhtml11[]\n [attributes]\n git-relative-html-prefix=\n-- \n2.39.2.13.g1fb56cf030\n\n"},{"id":"474905","messageId":"20230406035729.GA2092667@coredump.intra.peff.net","threadId":"59462","inReplyTo":"20230323221523.52472-1-felipe.contreras@gmail.com","subject":"Re: [PATCH] doc: asciidoc: remove custom header macro","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-04-06T03:57:29Z","receivedAt":"2023-04-06T03:57:37Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Mar 23, 2023 at 04:15:23PM -0600, Felipe Contreras wrote:\n\n> In 2007 we added a custom header macro to provide version information\n> 7ef195ba3e (Documentation: Add version information to man pages,\n> 2007-03-25),\n> \n> However, in 2008 asciidoc added the attributes to do this properly [1].\n> \n> This was not implemented in Git until 2019: 226daba280 (Doc/Makefile:\n> give mansource/-version/-manual attributes, 2019-09-16).\n> \n> But in 2023 we are doing it properly, so there's no need for the custom\n> macro.\n> \n> [1] https://github.com/asciidoc-py/asciidoc-py/commit/ad78a3c\n\nThis should be OK to do, as it is just touching the python asciidoc\nside. When we discussed those attributes in 2019:\n\n https://lore.kernel.org/git/20190320183229.GK31362@pobox.com/\n\nasciidoctor support was new and incomplete. It needed v1.5.7 (from\n2018), and even today still does not seem to handle manversion. But\nsince this patch leaves in place the equivalent hack in\nasciidoctor-extensions.rb, it will continue working.\n\n Aside: If we think asciidoctor 1.5.7 is recent enough to rely on, then\n we might want to simplify our hack to just output manversion. Right\n now we generate duplicate \"source\" and \"manual\" lines, though docbook\n seems to do OK with it.\n\n-Peff\n"},{"id":"474907","messageId":"xmqq8rf5r66s.fsf@gitster.g","threadId":"59462","inReplyTo":"20230406035729.GA2092667@coredump.intra.peff.net","subject":"Re: [PATCH] doc: asciidoc: remove custom header macro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-06T04:22:03Z","receivedAt":"2023-04-06T04:22:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Thu, Mar 23, 2023 at 04:15:23PM -0600, Felipe Contreras wrote:\n>\n>> In 2007 we added a custom header macro to provide version information\n>> 7ef195ba3e (Documentation: Add version information to man pages,\n>> 2007-03-25),\n>> \n>> However, in 2008 asciidoc added the attributes to do this properly [1].\n>> \n>> This was not implemented in Git until 2019: 226daba280 (Doc/Makefile:\n>> give mansource/-version/-manual attributes, 2019-09-16).\n>> \n>> But in 2023 we are doing it properly, so there's no need for the custom\n>> macro.\n>> \n>> [1] https://github.com/asciidoc-py/asciidoc-py/commit/ad78a3c\n>\n> This should be OK to do, as it is just touching the python asciidoc\n> side. When we discussed those attributes in 2019:\n>\n> https://lore.kernel.org/git/20190320183229.GK31362@pobox.com/\n>\n> asciidoctor support was new and incomplete. It needed v1.5.7 (from\n> 2018), and even today still does not seem to handle manversion. But\n> since this patch leaves in place the equivalent hack in\n> asciidoctor-extensions.rb, it will continue working.\n\nSounds like the proposed log message can use a bit more polishing to\nhelp future readers of \"git log\", then. But I think it is not\nrequired to be explicit about us leaving the asciidoctor side\nuntouched to keep it working (in other words, we do not talk about\nthings that we are not doing in our log message, unless it is so\nunnatural not to do them at the same time to warrant such an\nexplanation).\n\nWill queue with your Reviewed-by: in the morning.\n\nThanks, both.\n"},{"id":"474908","messageId":"CAMP44s2u4tj7hUZHZ9H4qsJGp1a=Y=YUTBAxmSzftdfHX_HqwQ@mail.gmail.com","threadId":"59462","inReplyTo":"20230406035729.GA2092667@coredump.intra.peff.net","subject":"Re: [PATCH] doc: asciidoc: remove custom header macro","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-06T06:18:36Z","receivedAt":"2023-04-06T06:18:53Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Apr 5, 2023 at 10:57 PM Jeff King wrote:\n>\n> On Thu, Mar 23, 2023 at 04:15:23PM -0600, Felipe Contreras wrote:\n>\n> > In 2007 we added a custom header macro to provide version information\n> > 7ef195ba3e (Documentation: Add version information to man pages,\n> > 2007-03-25),\n> >\n> > However, in 2008 asciidoc added the attributes to do this properly [1].\n> >\n> > This was not implemented in Git until 2019: 226daba280 (Doc/Makefile:\n> > give mansource/-version/-manual attributes, 2019-09-16).\n> >\n> > But in 2023 we are doing it properly, so there's no need for the custom\n> > macro.\n> >\n> > [1] https://github.com/asciidoc-py/asciidoc-py/commit/ad78a3c\n>\n> This should be OK to do, as it is just touching the python asciidoc\n> side. When we discussed those attributes in 2019:\n>\n> https://lore.kernel.org/git/20190320183229.GK31362@pobox.com/\n>\n> asciidoctor support was new and incomplete. It needed v1.5.7 (from\n> 2018),\n\nExcept that isn't true.\n\nThe `manmanual` and `mansource` attributes were supported since day 1\n[1], back in 2015 and included in v1.5.3. But for the manpage backend,\nwhich we refuse to use.\n\nIt's true they were added in 2018 and in v1.5.7 for the docbook5\nbackend [2], which is what we use when we do USE_ASCIIDOCTOR=y, but we\ncould have used the manpage backend instead, which already had support\nfor that 3 years prior.\n\n> and even today still does not seem to handle manversion.\n\nWhy do we need `manversion`?\n\nAll that it's used for is in the DocBook Stylesheets to join the\nsource name and the version, even its own documentation explains what\nit looks like in practice [3]:\n\n In practice, there are many pages that simply have a version number\nin the \"source\" field. So, it looks like what we have is a two-part\nfield, Name Version\n\nSo if we have `source=\"Git\"`, and `version=\"2.4.0\"`, we can just have\n`source=\"Git 2.40.0\"`.\n\nWhy do we have to split that information only for the DocBook\nStylesheets to join it in?\n\n> Aside: If we think asciidoctor 1.5.7 is recent enough to rely on, then\n> we might want to simplify our hack to just output manversion.\n\nThere is no need for any hack: we can just set the \"mansource\"\nattribute to \"Git $(GIT_VERSION)\", and everything will work correctly\nfor both asciidoc and asciidoctor in all backends.\n\nWhy do we insist on hacks for asciidoc.py/2007 and asciidoc|docbook5/2017?\n\nEspecially when I sent the fix for *everything* in 2021 [4].\n\nThis is absolutely no reason to complicate the joining of two strings this much.\n\nCheers.\n\n[1] https://github.com/asciidoctor/asciidoctor/commit/7bddc416\n[2] https://github.com/asciidoctor/asciidoctor/commit/6b07b0ba\n[3] https://docbook.sourceforge.net/release/xsl/current/doc/common/template.get.refentry.source.html\n[4] https://lore.kernel.org/git/20210514121435.504423-7-felipe.contreras@gmail.com/\n\n-- \nFelipe Contreras\n"},{"id":"474909","messageId":"20230406071914.GA2143526@coredump.intra.peff.net","threadId":"59462","inReplyTo":"CAMP44s2u4tj7hUZHZ9H4qsJGp1a=Y=YUTBAxmSzftdfHX_HqwQ@mail.gmail.com","subject":"Re: [PATCH] doc: asciidoc: remove custom header macro","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-04-06T07:19:14Z","receivedAt":"2023-04-06T07:19:20Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Apr 06, 2023 at 01:18:36AM -0500, Felipe Contreras wrote:\n\n> > and even today still does not seem to handle manversion.\n> \n> Why do we need `manversion`?\n> \n> All that it's used for is in the DocBook Stylesheets to join the\n> source name and the version, even its own documentation explains what\n> it looks like in practice [3]:\n> \n> In practice, there are many pages that simply have a version number\n> in the \"source\" field. So, it looks like what we have is a two-part\n> field, Name Version\n> \n> So if we have `source=\"Git\"`, and `version=\"2.4.0\"`, we can just have\n> `source=\"Git 2.40.0\"`.\n> \n> Why do we have to split that information only for the DocBook\n> Stylesheets to join it in?\n\nI don't know of any particular reason why we couldn't put both in the\nsource field.\n\nI had forgotten we discussed this 2 years ago.\n\n> > Aside: If we think asciidoctor 1.5.7 is recent enough to rely on, then\n> > we might want to simplify our hack to just output manversion.\n> \n> There is no need for any hack: we can just set the \"mansource\"\n> attribute to \"Git $(GIT_VERSION)\", and everything will work correctly\n> for both asciidoc and asciidoctor in all backends.\n> \n> Why do we insist on hacks for asciidoc.py/2007 and asciidoc|docbook5/2017?\n> \n> Especially when I sent the fix for *everything* in 2021 [4].\n\nYou say \"insist\" like somebody is arguing for it. It looks like the\nseries you linked got some review comments, and you followed-up. I\ndidn't carefully read the re-rolls (then or now), but the original\npatches seem like a good direction to me.\n\nLooking at the timing in the archive, I suspect that inter-personal\ndrama in other threads caused people not to read those re-rolls.\n\nAt any rate, I don't think any of that needs to hold up this patch,\nwhich is not touching the asciidoctor side at all (I only wondered while\nreviewing it what the implications might be).\n\n-Peff\n"},{"id":"474910","messageId":"20230406071958.GB2143526@coredump.intra.peff.net","threadId":"59462","inReplyTo":"xmqq8rf5r66s.fsf@gitster.g","subject":"Re: [PATCH] doc: asciidoc: remove custom header macro","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-04-06T07:19:58Z","receivedAt":"2023-04-06T07:20:19Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Apr 05, 2023 at 09:22:03PM -0700, Junio C Hamano wrote:\n\n> Sounds like the proposed log message can use a bit more polishing to\n> help future readers of \"git log\", then. But I think it is not\n> required to be explicit about us leaving the asciidoctor side\n> untouched to keep it working (in other words, we do not talk about\n> things that we are not doing in our log message, unless it is so\n> unnatural not to do them at the same time to warrant such an\n> explanation).\n\nYes, I think the \"is it unnatural\" is a debatable point here. I'm OK\nwith the commit message as-is.\n\n> Will queue with your Reviewed-by: in the morning.\n\nSounds good, thanks.\n\n-Peff\n"},{"id":"474917","messageId":"CAMP44s0DbALdFGsS=+NT6tTze=qK+z8EG0UuBVagPvsq9nby_g@mail.gmail.com","threadId":"59462","inReplyTo":"xmqq8rf5r66s.fsf@gitster.g","subject":"Re: [PATCH] doc: asciidoc: remove custom header macro","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-04-06T08:34:59Z","receivedAt":"2023-04-06T08:35:15Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Apr 5, 2023 at 11:22 PM Junio C Hamano wrote:\n>\n> Jeff King writes:\n>\n> > On Thu, Mar 23, 2023 at 04:15:23PM -0600, Felipe Contreras wrote:\n> >\n> >> In 2007 we added a custom header macro to provide version information\n> >> 7ef195ba3e (Documentation: Add version information to man pages,\n> >> 2007-03-25),\n> >>\n> >> However, in 2008 asciidoc added the attributes to do this properly [1].\n> >>\n> >> This was not implemented in Git until 2019: 226daba280 (Doc/Makefile:\n> >> give mansource/-version/-manual attributes, 2019-09-16).\n> >>\n> >> But in 2023 we are doing it properly, so there's no need for the custom\n> >> macro.\n> >>\n> >> [1] https://github.com/asciidoc-py/asciidoc-py/commit/ad78a3c\n> >\n> > This should be OK to do, as it is just touching the python asciidoc\n> > side. When we discussed those attributes in 2019:\n> >\n> > https://lore.kernel.org/git/20190320183229.GK31362@pobox.com/\n> >\n> > asciidoctor support was new and incomplete. It needed v1.5.7 (from\n> > 2018), and even today still does not seem to handle manversion. But\n> > since this patch leaves in place the equivalent hack in\n> > asciidoctor-extensions.rb, it will continue working.\n>\n> Sounds like the proposed log message can use a bit more polishing to\n> help future readers of \"git log\", then.\n\nYes, *if* what Jeff King was saying were true, which is not. At least\nnot completely.\n\n> But I think it is not required to be explicit about us leaving the\n> asciidoctor side untouched to keep it working (in other words, we do\n> not talk about things that we are not doing in our log message, unless\n> it is so unnatural not to do them at the same time to warrant such an\n> explanation).\n\nI did explain that we could fix all the issues of this particular\nproblem for both asciidoc and asciidoctor as far back as 2021 [1].\nThis fix did not materialize in subsequent patches: [2][3][4][5][6].\n\nBut the fix exists, and it's explicitly explained (multiple times).\n\nBasically: instead of trying to make docbook-xsl understand \"$version\"\nin order to join it as \"$source $version\". We can just say\n`source=\"$source $version\"` and forget about $version.\n\nI don't know how I can say it more clearly: we can fix all the\nproblems for all the tools and all their backends with one simple\npatch.\n\nSo after 6 attempts I'm trying to change the strategy and only clarify\nthe problem for asciidoc.py, which hopefully is clear now. But it can\nbe fixed for asciidoctor as well...*today*.\n\nCheers.\n\n[1] https://lore.kernel.org/git/20210514121435.504423-7-felipe.contreras@gmail.com/\n[2] https://lore.kernel.org/git/20210515115653.922902-4-felipe.contreras@gmail.com\n[3] https://lore.kernel.org/git/20210521223701.526547-4-felip01e.contreras@gmail.com/\n[4] https://lore.kernel.org/git/20210608090026.1737348-4-felipe.contreras@gmail.com/\n[5] https://lore.kernel.org/git/20210618215231.796592-420-felipe.contreras@gmail.com/\n[6] https://lore.kernel.org/git/20210621163110.1074145-4-felipe.contreras@gmail.com/\n\n-- \nFelipe Contreras\n"},{"id":"475001","messageId":"xmqqwn2nlq8c.fsf@gitster.g","threadId":"59462","inReplyTo":"20230406071914.GA2143526@coredump.intra.peff.net","subject":"Re: [PATCH] doc: asciidoc: remove custom header macro","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-07T14:30:11Z","receivedAt":"2023-04-07T14:30:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> At any rate, I don't think any of that needs to hold up this patch,\n> which is not touching the asciidoctor side at all (I only wondered while\n> reviewing it what the implications might be).\n\nYeah, sounds good. Wondering about and discussing possible\nimplications is also a good thing, when done in a productive way.\n\nQueued. Trickling in modernization a bit by bit to avoid hogging\ntoo much list bandwidth may also be a good thing to do.\n\nThanks.\n"}]}