Re: [PATCH] doc: manpage: remove maximum title length
Show 11 quoted lines
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
> > DocBook Stylesheets limit the size of the manpage titles for some
> > reason.
> >
> > Even some of the longest git commands have no trouble fitting in 80
> > character terminals, so it's not clear why we would want to limit titles
> > to 20 characters, especially when modern terminals are much bigger.
>
> I agree with the general thrust, but I do not think we are the ones
> who limit it to 20.
We are not explicitely telling docbook-xsl to limit the title to 20, no, but we are limitting the tile to 20 by choosing to use docbook-xsl.
> It is a value that is "reasonable but somewhat arbitrary", decided by
> somebody, and may even vary across installed versions of DocBook XSL
> Stylesheets and their customizations, isn't it (in other words, for some
> readers of "git log", it may not even be 20,
No. Just because docbook-xsl says X doesn't mean X is true.
Show 12 quoted lines
> if their distro tweaked the value to suit their needs)?
>
> Perhaps rephrase it ...
>
> DocBook Stylesheets limit the size of the manpage titles to
> avoid it (often shown twice, from both ends of the page)
> overlapping with other elements on the same line, such as the
> section name (for us, "Git Manual"). They say it is set to a
> "reasonable but somewhat arbitrary" value by default, and
> encourage "experiment with changing the value in order to
> achieve the correct aesthetic results, where they document the
> man.th.title.max.length parameter [*].
But this isn't accurate. They don't limit the size of the manpage title, they only do so *by default*.
Show 5 quoted lines
> The longest title we need to show for the Git manual pages
> currently is "git-credential-cache--daemon(1)" that is 30
> characters long, but I've seen on my box with docbook-xsl
> 1.79.2+dfsg-2 installed that the "reasonable" default was set to
> 20, which would cause the title shown like so:
This again is not accurate, because I'm 100% certain this is not just in my box, as it's also the case in git-manpages.git:
https://git.kernel.org/pub/scm/git/git-manpages.git/tree/man1/git-credential-cache--daemon.1
Show 9 quoted lines
> GIT-CREDENTIAL-CAC(1) Git Manual GIT-CREDENTIAL-CAC(1)
>
> We could raise the limit to, say, 32 as a conservative choice
> and can get this line show the full title:
>
> GIT-CREDENTIAL-CACHE--DAEMON(1) Git Manual GIT-CREDENTIAL-CACHE--DAEMON(1)
>
> but because even the longest one we currently have would fit on
> an 80-column terminal, let's make it unlimited for now.
This is not why I think we should do it.
> ... or something along that line.
Except I don't agree with what was said on that line.
Let's keep in mind that docbook-xsl is not the only way to generate manpages, so I don't think we should concern ourselves too much with what they do or don't do, nor what they say or don't say.
> I did NOT verify the claim that even the longest will fit in
> 80-column limit, that credential-cache--daemon is the longest one,
Me neither, which is why I did not attempt to say that, but also: I don't think it's particularly relevant which is the longest command today, because tomorrow somebody might propose an even bigger one.
> or that the box the problem was observed was using which version of
> the stylesheet.
> The above example illustrates the level of detail needed for a proper
> log message,
I don't think that level of detail is needed, or even desirable.
> FWIW, my primary motivation behind suggesting update of the above
> log message was to make sure that we document that we made a
> conscious decision to make it unlimited, instead of choosing another
> arbitrary limit (which we can do when we actually need to).
The conscious decision should be completely orthogonal to what docbook-xsl developers considered a "reasonable default" some time ago (probably decades ago).
The options for our conscious decision are:
1. We don't limit the length of the title
2. We limit the length of the title to some number
If we never made the conscious decision to limit the length of the title to some arbitrary number, I think we should not do that (regardless of docbook-xsl's default).
In other words: I don't think we should be burdened by the poor choices of some other project regarding the default values of their weird features.
Cheers.
--
Felipe Contreras
Felipe Contreras
