{"thread":{"id":"59687","subject":"[PATCH] doc: manpage: remove maximum title length","startedAt":"2023-05-03T05:34:18Z","lastAt":"2023-05-08T00:20:37Z","messageCount":8,"participants":["Felipe Contreras","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"476490","messageId":"20230503052926.217219-1-felipe.contreras@gmail.com","threadId":"59687","inReplyTo":null,"subject":"[PATCH] doc: manpage: remove maximum title length","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-05-03T05:29:26Z","receivedAt":"2023-05-03T05:34:18Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"DocBook Stylesheets limit the size of the manpage titles for some\nreason.\n\nEven some of the longest git commands have no trouble fitting in 80\ncharacter terminals, so it's not clear why we would want to limit titles\nto 20 characters, especially when modern terminals are much bigger.\n\nFor example:\n\n--- a/git-credential-cache--daemon.1\n+++ b/git-credential-cache--daemon.1\n@@ -1,4 +1,4 @@\n-GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n+GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n\n NAME\n git-credential-cache--daemon - Temporarily store user credentials in\n@@ -24,4 +24,4 @@ DESCRIPTION\n GIT\n Part of the git(1) suite\n\n-Git omitted 2023-05-02 GIT-CREDENTIAL-CAC(1)\n+Git omitted 2023-05-02 GIT-CREDENTIAL-CACHE--DAEMON(1)\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/manpage-normal.xsl | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl\nindex a9c7ec69f4..e7aa5df2fc 100644\n--- a/Documentation/manpage-normal.xsl\n+++ b/Documentation/manpage-normal.xsl\n@@ -8,6 +8,9 @@\n \n \n \n+\n+\n+\n \n \n \t\n-- \n2.40.0+fc1\n\n"},{"id":"476519","messageId":"20230503164354.GC1789686@coredump.intra.peff.net","threadId":"59687","inReplyTo":"20230503052926.217219-1-felipe.contreras@gmail.com","subject":"Re: [PATCH] doc: manpage: remove maximum title length","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-05-03T16:43:54Z","receivedAt":"2023-05-03T16:43:58Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 02, 2023 at 11:29:26PM -0600, Felipe Contreras wrote:\n\n> DocBook Stylesheets limit the size of the manpage titles for some\n> reason.\n> \n> Even some of the longest git commands have no trouble fitting in 80\n> character terminals, so it's not clear why we would want to limit titles\n> to 20 characters, especially when modern terminals are much bigger.\n\nMakes sense.\n\nSince the manpage header shows the name twice, along with \"Git Manual\",\nthe practical limit for an 80-column terminal is somewhere around 35\ncharacters. If it's not hard to do, it might be worth setting the value\nthere, but I agree that we're unlikely to exceed that anyway, so it's\nprobably not a big deal either way.\n\nI could also see an argument that the truncation is worse than any\nwrapping or other ugliness that the user might see on a smaller\nterminal, which implies that \"no limit\" as you have here is the best\noption.\n\n> For example:\n> \n> --- a/git-credential-cache--daemon.1\n> +++ b/git-credential-cache--daemon.1\n> @@ -1,4 +1,4 @@\n> -GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n> +GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n> \n> NAME\n> git-credential-cache--daemon - Temporarily store user credentials in\n> @@ -24,4 +24,4 @@ DESCRIPTION\n> GIT\n> Part of the git(1) suite\n> \n> -Git omitted 2023-05-02 GIT-CREDENTIAL-CAC(1)\n> +Git omitted 2023-05-02 GIT-CREDENTIAL-CACHE--DAEMON(1)\n\nYour patch can't be applied by \"git am\" because of this diff in the\ncommit message (it thinks the commit message stops at the first diff,\neven if it is before a \"---\" marker). The usual practice is to indent\nthe included diff.\n\n-Peff\n"},{"id":"476524","messageId":"6452955ade0c9_1df7294b9@chronos.notmuch","threadId":"59687","inReplyTo":"20230503164354.GC1789686@coredump.intra.peff.net","subject":"Re: [PATCH] doc: manpage: remove maximum title length","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-05-03T17:09:46Z","receivedAt":"2023-05-03T17:10:34Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Jeff King wrote:\n> On Tue, May 02, 2023 at 11:29:26PM -0600, Felipe Contreras wrote:\n> \n> > DocBook Stylesheets limit the size of the manpage titles for some\n> > reason.\n> > \n> > Even some of the longest git commands have no trouble fitting in 80\n> > character terminals, so it's not clear why we would want to limit titles\n> > to 20 characters, especially when modern terminals are much bigger.\n> \n> Makes sense.\n> \n> Since the manpage header shows the name twice, along with \"Git Manual\",\n> the practical limit for an 80-column terminal is somewhere around 35\n> characters. If it's not hard to do, it might be worth setting the value\n> there,\n\nIt's not hard to do, but that would create a discrepancy with asciidoctor\nmanpage backend, which doesn't do that.\n\n> I could also see an argument that the truncation is worse than any\n> wrapping or other ugliness that the user might see on a smaller\n> terminal, which implies that \"no limit\" as you have here is the best\n> option.\n\nI think it's best to remove the limit so there are no surprises and the output\nis consistent among tools.\n\n> > For example:\n> > \n> > --- a/git-credential-cache--daemon.1\n> > +++ b/git-credential-cache--daemon.1\n> > @@ -1,4 +1,4 @@\n> > -GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n> > +GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n> > \n> > NAME\n> > git-credential-cache--daemon - Temporarily store user credentials in\n> > @@ -24,4 +24,4 @@ DESCRIPTION\n> > GIT\n> > Part of the git(1) suite\n> > \n> > -Git omitted 2023-05-02 GIT-CREDENTIAL-CAC(1)\n> > +Git omitted 2023-05-02 GIT-CREDENTIAL-CACHE--DAEMON(1)\n> \n> Your patch can't be applied by \"git am\" because of this diff in the\n> commit message (it thinks the commit message stops at the first diff,\n> even if it is before a \"---\" marker). The usual practice is to indent\n> the included diff.\n\nAll right, I'll send an update.\n\n-- \nFelipe Contreras\n"},{"id":"476525","messageId":"20230503171658.8996-1-felipe.contreras@gmail.com","threadId":"59687","inReplyTo":"20230503052926.217219-1-felipe.contreras@gmail.com","subject":"[PATCH v2] doc: manpage: remove maximum title length","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-05-03T17:16:58Z","receivedAt":"2023-05-03T17:17:41Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"DocBook Stylesheets limit the size of the manpage titles for some\nreason.\n\nEven some of the longest git commands have no trouble fitting in 80\ncharacter terminals, so it's not clear why we would want to limit titles\nto 20 characters, especially when modern terminals are much bigger.\n\nFor example:\n\n --- a/git-credential-cache--daemon.1\n +++ b/git-credential-cache--daemon.1\n @@ -1,4 +1,4 @@\n -GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n +GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n\n NAME\n git-credential-cache--daemon - Temporarily store user credentials in\n @@ -24,4 +24,4 @@ DESCRIPTION\n GIT\n Part of the git(1) suite\n\n -Git omitted 2023-05-02 GIT-CREDENTIAL-CAC(1)\n +Git omitted 2023-05-02 GIT-CREDENTIAL-CACHE--DAEMON(1)\n\nMoreover, asciidoctor manpage backend doesn't limit the title length, so\nwe probably want to do the same for docbook backends for consistency.\n\nSigned-off-by: Felipe Contreras \n---\n\nSince v1 the example diff in the commit message has been indented and an\nextra paragraph explaining the situation with asciidoctor manpage\nbackend was added.\n\nRange-diff against v1:\n1: b356b40db1 ! 1: ea17191bd5 doc: manpage: remove maximum title length\n @@ Commit message\n \n For example:\n \n - --- a/git-credential-cache--daemon.1\n - +++ b/git-credential-cache--daemon.1\n - @@ -1,4 +1,4 @@\n - -GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n - +GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n + --- a/git-credential-cache--daemon.1\n + +++ b/git-credential-cache--daemon.1\n + @@ -1,4 +1,4 @@\n + -GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n + +GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n \n - NAME\n - git-credential-cache--daemon - Temporarily store user credentials in\n - @@ -24,4 +24,4 @@ DESCRIPTION\n - GIT\n - Part of the git(1) suite\n + NAME\n + git-credential-cache--daemon - Temporarily store user credentials in\n + @@ -24,4 +24,4 @@ DESCRIPTION\n + GIT\n + Part of the git(1) suite\n \n - -Git omitted 2023-05-02 GIT-CREDENTIAL-CAC(1)\n - +Git omitted 2023-05-02 GIT-CREDENTIAL-CACHE--DAEMON(1)\n + -Git omitted 2023-05-02 GIT-CREDENTIAL-CAC(1)\n + +Git omitted 2023-05-02 GIT-CREDENTIAL-CACHE--DAEMON(1)\n +\n + Moreover, asciidoctor manpage backend doesn't limit the title length, so\n + we probably want to do the same for docbook backends for consistency.\n \n Signed-off-by: Felipe Contreras \n \n\n Documentation/manpage-normal.xsl | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl\nindex a9c7ec69f4..e7aa5df2fc 100644\n--- a/Documentation/manpage-normal.xsl\n+++ b/Documentation/manpage-normal.xsl\n@@ -8,6 +8,9 @@\n \n \n \n+\n+\n+\n \n \n \t\n-- \n2.40.0+fc1\n\n"},{"id":"476529","messageId":"xmqq7ctps438.fsf@gitster.g","threadId":"59687","inReplyTo":"20230503052926.217219-1-felipe.contreras@gmail.com","subject":"Re: [PATCH] doc: manpage: remove maximum title length","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-03T17:43:39Z","receivedAt":"2023-05-03T17:43:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> DocBook Stylesheets limit the size of the manpage titles for some\n> reason.\n>\n> Even some of the longest git commands have no trouble fitting in 80\n> character terminals, so it's not clear why we would want to limit titles\n> to 20 characters, especially when modern terminals are much bigger.\n\nI agree with the general thrust, but I do not think we are the ones\nwho limit it to 20. It is a value that is \"reasonable but somewhat\narbitrary\", decided by somebody, and may even vary across installed\nversions of DocBook XSL Stylesheets and their customizations, isn't\nit (in other words, for some readers of \"git log\", it may not even\nbe 20, if their distro tweaked the value to suit their needs)?\n\nPerhaps rephrase it ...\n\n DocBook Stylesheets limit the size of the manpage titles to\n avoid it (often shown twice, from both ends of the page)\n overlapping with other elements on the same line, such as the\n section name (for us, \"Git Manual\"). They say it is set to a\n \"reasonable but somewhat arbitrary\" value by default, and\n encourage \"experiment with changing the value in order to\n achieve the correct aesthetic results, where they document the\n man.th.title.max.length parameter [*].\n\n The longest title we need to show for the Git manual pages\n currently is \"git-credential-cache--daemon(1)\" that is 30\n characters long, but I've seen on my box with docbook-xsl\n 1.79.2+dfsg-2 installed that the \"reasonable\" default was set to\n 20, which would cause the title shown like so:\n\n GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n\n We could raise the limit to, say, 32 as a conservative choice\n and can get this line show the full title:\n\n GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n\n but because even the longest one we currently have would fit on\n an 80-column terminal, let's make it unlimited for now.\n\n [Reference]\n * https://cdn.docbook.org/release/xsl/snapshot/doc/manpages/man.th.title.max.length.html\n\n... or something along that line.\n\nI did NOT verify the claim that even the longest will fit in\n80-column limit, that credential-cache--daemon is the longest one,\nor that the box the problem was observed was using which version of\nthe stylesheet. The above example illustrates the level of detail\nneeded for a proper log message, but it may contain factual errors\nthat need to be updated when the patch gets rerolled.\n\nFWIW, my primary motivation behind suggesting update of the above\nlog message was to make sure that we document that we made a\nconscious decision to make it unlimited, instead of choosing another\narbitrary limit (which we can do when we actually need to).\n\nThanks.\n\n> ---\n> Documentation/manpage-normal.xsl | 3 +++\n> 1 file changed, 3 insertions(+)\n>\n> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl\n> index a9c7ec69f4..e7aa5df2fc 100644\n> --- a/Documentation/manpage-normal.xsl\n> +++ b/Documentation/manpage-normal.xsl\n> @@ -8,6 +8,9 @@\n> \n> \n> \n> +\n> +\n> +\n> \n> \n> \t\n"},{"id":"476531","messageId":"xmqqv8h9qp9c.fsf@gitster.g","threadId":"59687","inReplyTo":"xmqq7ctps438.fsf@gitster.g","subject":"Re: [PATCH] doc: manpage: remove maximum title length","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-03T17:49:19Z","receivedAt":"2023-05-03T17:49:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> FWIW, my primary motivation behind suggesting update of the above\n> log message was to make sure that we document that we made a\n> conscious decision to make it unlimited, instead of choosing another\n> arbitrary limit (which we can do when we actually need to).\n\nElsewhere I think I saw \"asciidoctor does not limit\" mentioned. If\nthat is the case, then it is a very good thing to throw in as a\njustification why we chose to make it unlimited instead of raising\nthe default limit.\n\n\n"},{"id":"476532","messageId":"xmqqr0rxqou7.fsf@gitster.g","threadId":"59687","inReplyTo":"20230503171658.8996-1-felipe.contreras@gmail.com","subject":"Re: [PATCH v2] doc: manpage: remove maximum title length","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-03T17:58:24Z","receivedAt":"2023-05-03T17:58:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> DocBook Stylesheets limit the size of the manpage titles for some\n> reason.\n> ...\n> Moreover, asciidoctor manpage backend doesn't limit the title length, so\n> we probably want to do the same for docbook backends for consistency.\n>\n> Signed-off-by: Felipe Contreras \n> ---\n\nLooking good. It is especially good that we say why we chose to\nmake it unlimited instead of raising it to some arbitrary value.\n\nThe claim that the longest one would fit on a line is not still\nsubstantiated (we could say \"git-X manual page\" needs the most\ncolumns and people can check for themselves), but I'll let it pass.\n\nWill queue. Thanks.\n\n> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl\n> index a9c7ec69f4..e7aa5df2fc 100644\n> --- a/Documentation/manpage-normal.xsl\n> +++ b/Documentation/manpage-normal.xsl\n> @@ -8,6 +8,9 @@\n> \n> \n> \n> +\n> +\n> +\n> \n> \n> \t\n"},{"id":"476734","messageId":"64584024e6fa6_4e6129413@chronos.notmuch","threadId":"59687","inReplyTo":"xmqq7ctps438.fsf@gitster.g","subject":"Re: [PATCH] doc: manpage: remove maximum title length","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-05-08T00:19:48Z","receivedAt":"2023-05-08T00:20:37Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Junio C Hamano wrote:\n> Felipe Contreras writes:\n> \n> > DocBook Stylesheets limit the size of the manpage titles for some\n> > reason.\n> >\n> > Even some of the longest git commands have no trouble fitting in 80\n> > character terminals, so it's not clear why we would want to limit titles\n> > to 20 characters, especially when modern terminals are much bigger.\n> \n> I agree with the general thrust, but I do not think we are the ones\n> who limit it to 20.\n\nWe are not explicitely telling docbook-xsl to limit the title to 20, no,\nbut we are limitting the tile to 20 by choosing to use docbook-xsl.\n\n> It is a value that is \"reasonable but somewhat arbitrary\", decided by\n> somebody, and may even vary across installed versions of DocBook XSL\n> Stylesheets and their customizations, isn't it (in other words, for some\n> readers of \"git log\", it may not even be 20,\n\nNo. Just because docbook-xsl says X doesn't mean X is true.\n\n> if their distro tweaked the value to suit their needs)?\n> \n> Perhaps rephrase it ...\n> \n> DocBook Stylesheets limit the size of the manpage titles to\n> avoid it (often shown twice, from both ends of the page)\n> overlapping with other elements on the same line, such as the\n> section name (for us, \"Git Manual\"). They say it is set to a\n> \"reasonable but somewhat arbitrary\" value by default, and\n> encourage \"experiment with changing the value in order to\n> achieve the correct aesthetic results, where they document the\n> man.th.title.max.length parameter [*].\n\nBut this isn't accurate. They don't limit the size of the manpage title, they\nonly do so *by default*.\n\n> The longest title we need to show for the Git manual pages\n> currently is \"git-credential-cache--daemon(1)\" that is 30\n> characters long, but I've seen on my box with docbook-xsl\n> 1.79.2+dfsg-2 installed that the \"reasonable\" default was set to\n> 20, which would cause the title shown like so:\n\nThis again is not accurate, because I'm 100% certain this is not just in\nmy box, as it's also the case in git-manpages.git:\n\nhttps://git.kernel.org/pub/scm/git/git-manpages.git/tree/man1/git-credential-cache--daemon.1\n\n> GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)\n> \n> We could raise the limit to, say, 32 as a conservative choice\n> and can get this line show the full title:\n> \n> GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)\n> \n> but because even the longest one we currently have would fit on\n> an 80-column terminal, let's make it unlimited for now.\n\nThis is not why I think we should do it.\n\n> ... or something along that line.\n\nExcept I don't agree with what was said on that line.\n\nLet's keep in mind that docbook-xsl is not the only way to generate manpages,\nso I don't think we should concern ourselves too much with what they do\nor don't do, nor what they say or don't say.\n\n> I did NOT verify the claim that even the longest will fit in\n> 80-column limit, that credential-cache--daemon is the longest one,\n\nMe neither, which is why I did not attempt to say that, but also: I\ndon't think it's particularly relevant which is the longest command\ntoday, because tomorrow somebody might propose an even bigger one.\n\n> or that the box the problem was observed was using which version of\n> the stylesheet.\n\nAgain: doesn't matter.\n\n> The above example illustrates the level of detail needed for a proper\n> log message,\n\nI don't think that level of detail is needed, or even desirable.\n\n> FWIW, my primary motivation behind suggesting update of the above\n> log message was to make sure that we document that we made a\n> conscious decision to make it unlimited, instead of choosing another\n> arbitrary limit (which we can do when we actually need to).\n\nThe conscious decision should be completely orthogonal to what\ndocbook-xsl developers considered a \"reasonable default\" some time ago\n(probably decades ago).\n\nThe options for our conscious decision are:\n\n 1. We don't limit the length of the title\n 2. We limit the length of the title to some number\n\nIf we never made the conscious decision to limit the length of the title\nto some arbitrary number, I think we should not do that (regardless of\ndocbook-xsl's default).\n\nIn other words: I don't think we should be burdened by the poor choices\nof some other project regarding the default values of their weird\nfeatures.\n\nCheers.\n\n-- \nFelipe Contreras\n"}]}