Felipe Contreras <felipe.contreras@xxxxxxxxx> 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. 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, 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 [*].
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:
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.
[Reference]
* https://cdn.docbook.org/release/xsl/snapshot/doc/manpages/man.th.title.max.length.html
... or something along that line.
I did NOT verify the claim that even the longest will fit in
80-column limit, that credential-cache--daemon is the longest 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, but it may contain factual errors
that need to be updated when the patch gets rerolled.
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).
Thanks.
> ---
> Documentation/manpage-normal.xsl | 3 +++
> 1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
> index a9c7ec69f4..e7aa5df2fc 100644
> --- a/Documentation/manpage-normal.xsl
> +++ b/Documentation/manpage-normal.xsl
> @@ -8,6 +8,9 @@
> <xsl:param name="man.output.quietly" select="1"/>
> <xsl:param name="refentry.meta.get.quietly" select="1"/>
>
> +<!-- unset maximum length of title -->
> +<xsl:param name="man.th.title.max.length"/>
> +
> <!-- convert asciidoc callouts to man page format -->
> <xsl:template match="co">
> <xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/>
